作者:opLW
目录
1.文档中常用的标签
2.Kotlin与java文档中的不同点
3.Markdown在Kotlin文档中的应用
1.Kotlin文档中常用的标签
-
1.1 常用标签
标签 作用 特殊注意点 @constructor 描述 介绍主构造函数 只用于类 @author 作者 介绍作者 @since 版本 介绍当前类或方法产生于哪个版本 @param 参数名 描述 介绍参数 可以使用"[]"将参数名与描述隔开 @see <标识符> 引用其他类或方法 标识符后如添加的描述不会被写入文档中 @sample <标识符> 举例如何使用当前方法或者类 标识符后如添加的描述不会被写入文档中 @receiver <标识符> 描述 介绍扩展函数的接收者 标识符需要使用”[]“符号括起来,添加的描述有效 @throws 异常名 描述、@exception 异常名 描述 提醒使用者需要注意的异常 两个标签标注的内容,在生成文档时会归于一类:Throws @suppress 对于不需要写入文档但需要对外公开的元素,使用@suppress 具有此便签的元素不会被写入文档文件 @Deprecated 表明当前类或方法过时 @return 描述 介绍返回值 -
1.2 示例
/** * @constructor 构建一个Kdoc测试类 * @author opLW * @date 2020/2/7 * @since 0.0.1 */ class LabelTest() { /** * [我是一个链接][com.oplw.test.kdoc.MarkdownTest.testTitle] * * `我是代码段` * * [我是超链接](https://baidu.com) * * @param i 传进来的参数为i * @see com.oplw.test.kdoc.MarkdownTest.testTitle * @sample com.oplw.test.kdoc.MarkdownTest.testTitle * @throws MyException 当i小于0时抛出异常 * @exception MyException 当i小于0时抛出异常 * @return 返回值为整型 */ fun testFun(i: Int): Int { if (i < 0) { throw MyException("The value of i is smaller than 0") } return i } inner class MyException(errorMsg: String): Exception(errorMsg) } /** * @receiver [com.oplw.test.kdoc.MarkdownTest.testTitle] 我是一个扩展函数 */ fun LabelTest.extentsion() { }
-
1.3 @Throws注解和@throws标签的区别 前面提到的@throws标签用于文档,Kotlin中还有一个@Throws注解用于改善与Java的互操性。
- 背景 Java中的异常有必检异常和非必检异常两类。但Kotlin与Java不同,Kotlin没有必检异常 ,也就是不是必须要使用try…catch捕获异常;也不需要声明抛出的异常,即使是从Java类派生时,也不必声明方法抛出的异常。但是如果要捕获或抛出也是可以的。
- 作用 当在Java类中使用可能会抛出异常的Kotlin方法时,为该方法添加@Throws(SomeException::class)注解,这样在Java中就可以(而且有必要)处理异常。
- 参考文章 throws Exception in a method with Kotlin
2.Kotlin与java文档中的部分区别
- 2.1 链接方式 文档中经常需要引用到其他元素,通过链接可以快速查阅其他相关的内容
-
Java
Java
中的链接使用到@link
,具体使用如下:/** * 链接方式一:{@link test#testBlock()} * <p>链接方式二:{@link com.oplw.test.test#testBlock()}</p> */
@link
需要配合{}符号使用。可以单独一行,也可以穿插在其他文字中间; -
Kotlin KDoc用内联标记来代替@link
格式:[描述链接的文字][类或方法]/** * [这是一个链接][com.oplw.test.kdoc.MarkdownTest.testTitle] */
上述为
Kotlin
中链接的方式,需要注意的是:- 其中描述链接的文字可以被省略
- 当使用全限定名表达一个类时,Kotlin使用"."符号分割组件,而Java使用的是“#”(其他地方亦是如此)
-
- 2.2 超链接的方式
Java
使用html
的格式,Kotlin
使用markdowm
的格式// Java /** * @see <a href="http://baidu.com">描述链接的文字</a> */ // Kotlin /** * [描述链接的文字](https://baidu.com) */
- 2.3 文档中的代码 文档中启用代码模式,将代码与普通文字区分。
如上述代码所示。// Java /** * {@code java} */ // Kotlin /** * `Kotlin` */
Java
使用@code
标签,Kotlin
则使用反引号(英文输入法下,Esc
键下方的键) - 2.4 正文格式的差异
Kotlin
引入Markdown
撰写正文,下面单独讲。
3.Markdown在Kotlin文档中的应用
-
3.1 进行测试 如下将常用的Markdown语法应用到各个方法中
class MarkdownTest { /** * **1.使用 = 和 - 标记一级和二级标题** * * 我展示的是一级标题 * ================= * * 我展示的是二级标题 * ----------------- * * **2.使用 # 号标记** * * # 一级标题 * ## 二级标题 * ### 三级标题 * #### 四级标题 * ##### 五级标题 * ###### 六级标题 */ fun testTitle() {} ......省略其他方法 }
-
3.2 测试结果
- 在Android Studio中的效果 语法比较多,不一一贴出
- 在文档文件中的结果 同样贴出部分
- 在Android Studio中的效果 语法比较多,不一一贴出
-
3.3 总结
有效的语法 无效的语法 使用"#"及改变其个数来创建多级标题 使用”=====“或”------“创建多级标题 通过“空行”来换行 使用”~~文字~~“创建删除线 使用"*“或”_"及改变其个数调整字体的粗细、倾斜 使用"<u>文字</u>"为文字添加下划线 使用”-"创建多级列表 使用”==文字==“为文字添加颜色 使用反引号制作代码 使用”>“创建区块 使用连续三个单引号制作代码块 图片链接 [描述链接的文字](URL) 格式的链接 制作表格的符号
万水千山总是情,麻烦手下别留情。
如若讲得有不妥,文末留言告知我,
如若觉得还可以,收藏点赞要一起。
opLW原创七言律诗,转载请注明出处