Kotlin -- 一文详解Kotlin文档

作者：opLW

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中的效果 语法比较多，不一一贴出
- 在文档文件中的结果 同样贴出部分

3.3 总结

有效的语法	无效的语法
使用"#"及改变其个数来创建多级标题	使用”=====“或”------“创建多级标题
通过“空行”来换行	使用”~~文字~~“创建删除线
使用"*“或”_"及改变其个数调整字体的粗细、倾斜	使用"<u>文字</u>"为文字添加下划线
使用”-"创建多级列表	使用”==文字==“为文字添加颜色
使用反引号制作代码	使用”>“创建区块
使用连续三个单引号制作代码块	图片链接
[描述链接的文字](URL) 格式的链接	制作表格的符号

万水千山总是情，麻烦手下别留情。
如若讲得有不妥，文末留言告知我，
如若觉得还可以，收藏点赞要一起。
opLW原创七言律诗，转载请注明出处

op小白

发布了23 篇原创文章 · 获赞 33 · 访问量 8929

私信关注

Kotlin -- 一文详解Kotlin文档

目录

1.Kotlin文档中常用的标签

2.Kotlin与java文档中的部分区别

3.Markdown在Kotlin文档中的应用

猜你喜欢