为 Kotlin 项目编写文档：从 A 到 Z

引言：为什么文档对 Kotlin 项目很重要

编写文档不仅仅是一种形式，更是成功 Kotlin 项目的关键要素。良好的文档化代码可以加快新开发者的入职速度，简化维护工作，并减少错误数量。Kotlin 作为一种现代语言，提供了强大的文档创建工具：KDoc（类似于 JavaDoc）和 Dokka（文档生成器）。在本文中，我们将介绍为 Kotlin 项目编写文档的完整流程：从代码中的注释到发布最终文档。

无论您是在开发库、API 还是内部应用程序，遵循文档化的最佳实践都将使您的代码清晰易懂。让我们从基础开始。

KDoc 基础：语法与结构

KDoc 是一种用于文档化 Kotlin 代码的标记语言。它基于 JavaDoc，但针对 Kotlin 的特性进行了调整：空安全、扩展函数、属性和 Lambda 表达式。KDoc 注释以 /** 开头，以 */ 结尾。

KDoc 注释的基本结构

每个 KDoc 注释由描述和可选的标签组成。主要标签包括：

\n
• @param — 函数参数的描述
\n
• @return — 返回值的描述
\n
• @throws 或 @exception — 异常的描述
\n
• @see — 指向其他元素的链接
\n
• @sample — 插入代码示例
\n
• @property — 类属性的描述
\n
• @constructor — 构造函数的描述
\n
• @receiver — 扩展函数的接收者描述
\n

一个简单的 KDoc 注释示例：

/**\n * 计算给定数字的阶乘。\n *\n * 使用迭代方法以避免栈溢出。\n * 仅适用于非负整数。\n *\n * @param n 要计算阶乘的非负整数\n * @return 数字 n 的阶乘 (n!)\n * @throws IllegalArgumentException 如果 n < 0\n */\nfun factorial(n: Int): Long {\n    require(n >= 0) { "n must be non-negative" }\n    var result = 1L\n    for (i in 2..n) {\n        result *= i\n    }\n    return result\n}

文档化属性和类

对于类和属性，请使用 @property 标签：

/**\n * 表示系统中的一个用户。\n *\n * @property id 用户的唯一标识符\n * @property name 用户的全名\n * @property email 电子邮件地址\n * @property isActive 账户活动状态标志\n */\ndata class User(\n    val id: Long,\n    val name: String,\n    val email: String,\n    val isActive: Boolean = true\n)

使用 Dokka 生成文档

Dokka 是 Kotlin 官方文档生成工具。它支持多种输出格式：HTML、Markdown、Javadoc 和 JSON。Dokka 能够处理多平台项目，并正确显示 Kotlin 特有的结构。

在 Gradle 中配置 Dokka

要将 Dokka 添加到项目中，请在 build.gradle.kts 中引入插件：

plugins {\n    id("org.jetbrains.dokka") version "1.9.20"\n}\n\ntasks.dokkaHtml {\n    outputDirectory.set(buildDir.resolve("dokka"))\n    moduleName.set("My Kotlin Library")\n}\n\ntasks.dokkaJavadoc {\n    outputDirectory.set(buildDir.resolve("javadoc"))\n}

之后，运行命令 ./gradlew dokkaHtml — 文档将生成在 build/dokka 文件夹中。

Dokka 的高级功能

Dokka 支持自定义外观、包含/排除包以及添加额外页面。自定义配置示例：