1. 什么是 Dokka 以及为什么需要它

Dokka 是 JetBrains 公司为 Kotlin 语言开发的现代文档生成引擎。与传统的 JavaDoc 不同，Dokka 理解 Kotlin 的特性：空安全、扩展函数、属性、协程、密封类以及其他独特的语言结构。如果您正在用 Kotlin 编写库或 API，Dokka 可以自动生成可读性强、结构清晰的文档，格式包括 HTML、Markdown、Javadoc，甚至 JSON 以便进一步处理。

为什么需要它？首先，Dokka 大大简化了大型项目中文档的维护——只需在代码中编写 KDoc 注释（类似于 JavaDoc，但支持 Markdown），该工具就会生成一个完整的网站。其次，Dokka 能够将来自多个 Gradle 或 Maven 模块的文档合并到一个项目中，这对于多模块库至关重要。第三，它支持通过模板和插件进行自定义，允许您根据企业风格调整外观。

Dokka 被广泛用于 Kotlin 官方文档（kotlinlang.org）、Ktor、Exposed、Kotlinx.serialization 等库中。它是 Kotlin 项目文档的事实标准，如果您希望自己的库看起来专业，那么 Dokka 是必须学习的。

2. 安装

Dokka 作为 Gradle 和 Maven 构建系统的插件分发。没有单独的 pip 或 npm 命令，因为它是 JVM 生态系统的工具。以下是 Gradle（Kotlin DSL）的精确说明——这是最流行的方法。

Gradle（Kotlin DSL）——单模块插件

在 build.gradle.kts 中添加：

plugins {\n    id("org.jetbrains.dokka") version "1.9.20"\n}\n\ndependencies {\n    // 您的依赖\n}\n\n// 基本配置（可选）\ntasks.withType<org.jetbrains.dokka.gradle.DokkaTask>() {\n    outputDirectory.set(file("$buildDir/dokka"))\n}

Gradle（Groovy DSL）

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

Maven

<plugin>\n    <groupId>org.jetbrains.dokka</groupId>\n    <artifactId>dokka-maven-plugin</artifactId>\n    <version>1.9.20</version>\n    <executions>\n        <execution>\n            <phase>pre-site</phase>\n            <goals>\n                <goal>dokka</goal>\n            </goals>\n        </execution>\n    </executions>\n</plugin>

配置完成后，运行命令：

./gradlew dokkaHtml       # 生成 HTML\n./gradlew dokkaGfm        # 生成 Markdown（GFM）\n./gradlew dokkaJavadoc    # 生成 Javadoc 风格

3. 快速入门——最小工作示例

创建一个带有 KDoc 注释的简单 Kotlin 文件：

// src/main/kotlin/com/example/Calculator.kt\npackage com.example\n\n/**\n * 一个简单的计算器，演示 Dokka 的功能。\n *\n * @author PythonLib Team\n * @since 1.0.0\n */\nclass Calculator {\n\n    /**\n     * 将两个数相加。\n     *\n     * @param a 第一个加数\n     * @param b 第二个加数\n     * @return a 和 b 的和\n     */\n    fun add(a: Int, b: Int): Int = a + b\n\n    /**\n     * 将一个数除以另一个数。\n     *\n     * @param a 被除数\n     * @param b 除数（不能为零）\n     * @return 除法结果\n     * @throws IllegalArgumentException 如果 b == 0\n     */\n    fun divide(a: Double, b: Double): Double {\n        require(b != 0.0) { "除数不能为零" }\n        return a / b\n