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

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

引言：为什么文档是 Kotlin 项目成功的关键？

在现代 Kotlin 开发世界中，编写干净高效的代码只是成功的一半。另一半同样重要的部分是创建高质量的文档。文档完善的项目不仅仅是一堆注释。它是对未来的投资：它简化了新开发人员的入职流程，加快了调试速度，便于代码库的维护，并使您的 API 对他人易于理解。没有文档，即使是最天才的代码也可能会变成一个没人愿意触碰的“黑匣子”。

在本文中，我们将详细讲解为 Kotlin 项目编写文档的完整过程——从 KDoc 语法基础到使用 Dokka 自动生成漂亮的网站。您将学习如何使文档不仅有用，而且易于阅读，同时还将了解一些最佳实践，帮助您保持文档的及时更新。

1. KDoc 基础：如何在 Kotlin 中编写注释

KDoc 是用于记录 Kotlin 代码的标准标记语言，与 JavaDoc 非常相似。KDoc 注释以 /** 开头，以 */ 结尾。内部使用特殊的标记，用于描述参数、返回值和异常。

1.1. KDoc 注释的基本结构

您最常使用的基本标签：

@param — 描述函数或类的参数。
@return — 描述返回值。
@throws 或 @exception — 描述函数可能抛出的异常。
@see — 链接到其他代码元素。
@sample — 链接到使用示例。

1.2. 函数示例

考虑一个计算算术平均值的简单函数：

/** * 计算两个数的算术平均值。 * * 此函数接受两个整数并返回它们的平均值 * 作为浮点数。如果两个数都为零，函数 * 将返回 0.0。 * * @param a 第一个整数。 * @param b 第二个整数。 * @return 数字 a 和 b 的算术平均值。 * @throws IllegalArgumentException 如果两个参数都为零（可选，仅作示例）。 * @see Math#sqrt * @sample com.example.calculator.averageSample */fun average(a: Int, b: Int): Double {    if (a == 0 && b == 0) {        throw IllegalArgumentException("两个数不能都为零")    }    return (a + b) / 2.0}

1.3. 记录类和属性

不仅函数需要文档，类、接口及其属性也需要。这有助于快速理解模块的用途。

/** * 用于处理用户的仓库。 * * 此类封装了用户数据的访问逻辑， * 包括搜索、保存和删除操作。 * * @property databaseSource 数据库的数据源。 * @property cacheSource 缓存的数据源。 * @constructor 使用给定的数据源创建仓库实例。 */class UserRepository(    private val databaseSource: UserDatabaseSource,    private val cacheSource: UserCacheSource) {    /**     * 当前用户的 ID。     * 如果用户未登录，可以为 null。     */    var currentUserId: String? = null}