为 Kotlin 项目编写文档：进阶水平

轻松学习Python，无需理论负担。在浏览器中直接解决带自动检查的实践任务，无需安装任何东西。

引言：为什么 Kotlin 文档需要特殊方法

Kotlin 作为一种现代多范式语言，为开发者提供了独特的功能：空安全、扩展函数、协程和 DSL。然而，这些功能也给文档编写带来了挑战。普通的 JavaDoc 风格注释往往无法充分描述 Kotlin 的复杂结构。在进阶水平上，仅仅编写“函数描述”是不够的。有必要创建对内部团队和外部库用户都有用的文档。

在本文中，我们将探讨为 Kotlin 项目编写文档的专业工具和方法：从使用带有扩展标签的 KDoc，到配置 Dokka 和集成自动网站生成。

1. KDoc：扩展功能与标签

KDoc 是 Kotlin 的标准标记语言，基于 JavaDoc，但针对语言特性进行了扩展。进阶开发者知道，KDoc 支持注释内的 Markdown，这使其比 JavaDoc 更强大。

1.1. KDoc 基本标签

@param — 描述函数或类的参数。
@return — 描述返回值。
@throws / @exception — 描述异常。
@see — 链接到其他代码元素。
@sample — 嵌入来自单独文件的代码示例。
@property — 记录类的属性。
@receiver — 记录扩展函数（描述 this 代表什么）。

1.2. KDoc 进阶使用示例

考虑一个带有协程和空安全的扩展函数示例：

/** * 使用给定的 [transform] 函数异步转换列表 [items]。 * * 此函数使用协程并行处理元素。 * 与标准的 [map] 不同，它并发执行转换。 * * @param T 原始列表的元素类型。 * @param R 结果列表的元素类型。 * @param items 要转换的元素列表。 * @param transform 应用于每个元素的挂起 (suspend) 函数。 * @return 转换后的元素列表。 * @throws CancellationException 如果协程在执行期间被取消。 * @sample com.example.ParallelMapExample.main * @receiver 不适用（顶层函数）。 */suspend fun <T, R> parallelMap(    items: List<T>,    transform: suspend (T) -> R): List<R> {    return coroutineScope {        items.map { async { transform(it) } }.awaitAll()    }}

请注意 @sample 标签。它允许引用一个实际的示例文件，该文件将在通过 Dokka 生成文档时自动包含在内。

1.3. 记录 DSL

对于 Kotlin 中的 DSL（领域特定语言），记录上下文尤为重要。使用 @receiver 标签来指示 lambda 中的接收者对象：

/** * 创建一个 HTML 表格。 * * @param init 在 [TableBuilder] 上下文中的 lambda 初始化器。 * @receiver [TableBuilder] — 提供配置表格方法的对象。 */fun htmlTable(init: TableBuilder.() -> Unit): String {    val builder = TableBuilder()    builder.init()    return builder.render()}