6.7.5 为 Kotlin 代码编写文档：KDoc

原文链接: https://kotlinlang.org/docs/kotlin-doc.html

6.7.5 为 Kotlin 代码编写文档：KDoc

用于为 Kotlin 代码编写文档的语言（相当于 Java 的 Javadoc）称为 KDoc。本质上，KDoc 结合了 Javadoc 的块标签语法（并扩展以支持 Kotlin 特有的构造）和用于行内标记的 Markdown。

注意： Kotlin 的文档引擎 Dokka 能够理解 KDoc，并可用于生成多种格式的文档。更多信息请阅读我们的 Dokka 文档。

KDoc 语法

与 Javadoc 一样，KDoc 注释以 /** 开始、以 */ 结束。注释的每一行都可以以星号开头，该星号不被视为注释内容的一部分。

按照约定，文档文本的第一段（直到第一个空行的文本块）是该元素的摘要描述，其后的文本则是详细描述。

每个块标签都从新的一行开始，并以 @ 字符开头。

下面是一个用 KDoc 编写文档的类示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

/**
 * A group of *members*.
 *
 * This class has no useful logic; it's just a documentation example.
 *
 * @param T the type of a member in this group.
 * @property name the name of this group.
 * @constructor Creates an empty group.
 */
class Group<T>(val name: String) {
    /**
     * Adds a [member] to this group.
     * @return the new size of the group.
     */
    fun add(member: T): Int { ... }
}

块标签

KDoc 目前支持以下块标签：

@param name

为函数的值参数，或类、属性、函数的类型参数编写文档。为了更好地把参数名与描述分开，如果你愿意，可以把参数名括在方括号中。因此下面两种语法是等价的：

@param name description.
@param[name] description.

@return

为函数的返回值编写文档。

@constructor

为类的主构造函数编写文档。

@receiver

为扩展函数的接收者编写文档。

@property name

为类中具有指定名称的属性编写文档。该标签可用于为在主构造函数中声明的属性编写文档，因为在这种情况下把文档注释直接写在属性定义之前会很别扭。

@throws class、@exception class

为方法可能抛出的异常编写文档。由于 Kotlin 没有受检异常，也就不要求记录所有可能的异常，但当该标签能为类的使用者提供有用信息时，你仍然可以使用它。

@sample identifier

把具有指定限定名的函数体嵌入当前元素的文档中，以展示该元素的使用示例。

@see identifier

把指向指定类或方法的链接添加到文档的 另请参阅 区块中。

@author

指定被记录元素的作者。

@since

指定被记录元素是在哪个软件版本中引入的。

@suppress

把该元素排除在生成的文档之外。可用于那些不属于模块官方 API、但仍需在外部可见的元素。

注意： KDoc 不支持 @deprecated 标签。请改用 @Deprecated 注解。

行内标记

对于行内标记，KDoc 使用常规的 Markdown 语法，并扩展以支持链接到代码中其他元素的简写语法。

指向元素的链接

要链接到另一个元素（类、方法、属性或参数），只需把它的名称放在方括号中：

Use the method [foo] for this purpose.

如果你想为链接指定自定义标签，请在元素链接之前用另一对方括号给出它：

Use [this method][foo] for this purpose.

你也可以在元素链接中使用限定名。注意，与 Javadoc 不同，限定名始终使用点号分隔各个组成部分，即使在方法名之前也是如此：

Use [kotlin.reflect.KClass.properties] to enumerate the properties of the class.

元素链接中的名称使用与被记录元素内部使用该名称时相同的规则来解析。特别是，这意味着如果你已经把某个名称导入当前文件，那么在 KDoc 注释中使用它时就不需要写完全限定名。

注意，KDoc 没有任何用于解析链接中重载成员的语法。由于 Kotlin 的文档生成工具会把一个函数的所有重载的文档放在同一页上，因此要让链接生效，并不需要指明是哪一个重载函数。

外部链接

要添加外部链接，请使用典型的 Markdown 语法：

For more information about KDoc syntax, see [KDoc](<example-URL>).

接下来学什么？

了解如何使用 Kotlin 的文档生成工具 Dokka。