Kotlin 文档：编写自解释的代码

Kotlin 项目文档：被理解的艺术

想象一下：你打开一个别人的 Kotlin 项目。代码优美、简洁，但……你不明白这个函数是做什么的，以及它返回什么。熟悉吗？现在想象一下，这个项目是你自己的，但半年后。Kotlin 文档不仅仅是对同事的礼貌。这是对你代码未来的投资。

在本文中，我们将探讨 Kotlin 项目文档编写的最佳实践。您将学习如何使用 KDoc、Dokka 和普通注释，让您的代码自解释。开始吧！

为什么 Kotlin 文档并不枯燥？

Kotlin 是一种为人类设计的语言。它读起来像英语，其语法消除了样板代码。但即使是最优雅的代码，如果没有文档也可能是个谜。尤其是当涉及到：

\n
• 复杂的业务逻辑；
\n
• 其他开发者使用的库和 API；
\n
• 生命周期较长的 Android 项目；
\n
• 人员流动频繁的企业解决方案。
\n

良好的 Kotlin 文档 解决三个问题：解释代码 “做什么”、“为什么” 这样做以及 “如何” 使用它。没有它，您可能会得到没人愿意碰的代码（甚至包括您自己）。

KDoc：Kotlin 文档编写的主要工具

KDoc 是 Kotlin 的 JavaDoc 对应物。它使用 /** ... */ 形式的注释并支持 Markdown。这是 Kotlin 项目文档的事实标准。

以下是一个基本示例：

/**\n * 根据用户状态计算折扣。\n *\n * @param price 商品原价。\n * @param userLevel 用户等级（BRONZE, SILVER, GOLD）。\n * @return 折扣后的最终价格。\n * @throws IllegalArgumentException 如果 price 为负数。\n */\nfun calculateDiscount(price: Double, userLevel: UserLevel): Double {\n    // 逻辑\n}

请注意：KDoc 使用 @param、@return、@throws 标签。但与 JavaDoc 不同，您可以直接在注释内编写 Markdown。这对于列表、链接和格式化非常方便。

KDoc 最佳实践

\n
• 为人编写，而非机器。 不要重复代码中显而易见的内容。不要写 // 设置值，而应写 // 设置用于计算税的值。
\n
• 为公共 API 编写文档。 内部函数（private 或 internal）可以简要记录或不记录。
\n
• 使用 @see 和 @sample。 引用相关函数或使用示例。
\n
• 不要忘记为扩展函数使用 @receiver。
\n

Dokka：将注释转化为漂亮的文档

Dokka 是 Kotlin 的文档生成器。它可以生成 HTML、Markdown、JavaDoc，甚至多平台项目的文档。如果您正在编写库或在团队中工作，Dokka 是您最好的朋友。

安装很简单。在 build.gradle.kts 中添加插件：

plugins {\n    id("org.jetbrains.dokka") version "1.9.20"\n}

然后运行命令：

./gradlew dokkaHtml

Dokka 将生成 build/dokka/html 文件夹，其中包含漂亮的文档，包括您所有的 KDoc 注释、类层次结构，甚至源代码链接。

Dokka 提示

\n
• 在 dokkaConfiguration 中配置项目徽标和描述；
\n
• 使用 @suppress 隐藏不需要的