1. 概述
本文将介绍如何使用 Dokka 为 Kotlin 项目生成文档。Dokka 是 Kotlin 官方推出的文档生成引擎，支持生成 HTML、Markdown、PDF 等多种格式的 API 文档。
文章前半部分将介绍如何在 Maven 和 Gradle 项目中集成 Dokka；中间部分会讲解 Dokka 的输入输出格式和常用配置项；最后我们通过一个示例展示 Dokka 生成的文档效果。
2. 如何在项目中集成并运行 Dokka
Dokka 支持 Maven 和 Gradle 构建系统。一般来说，Maven 插件功能较少，如果需要更多定制，推荐使用 命令行接口 生成文档，而不是集成到构建流程中。
2.1 使用 Maven 集成 Dokka
在 Maven 项目中，只需在 pom.xml 文件中添加 dokka-maven-plugin 插件即可：
<build>
<plugins>
<plugin>
<groupId>org.jetbrains.dokka</groupId>
<artifactId>dokka-maven-plugin</artifactId>
<version>1.7.20</version>
<executions>
<execution>
<phase>pre-site</phase>
<goals>
<goal>dokka</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
然后运行以下命令生成文档：
$ mvn dokka:dokka
默认输出路径为：{project.basedir}/target/dokka
2.2 使用 Gradle 集成 Dokka
对于 Gradle 项目，可以在 build.gradle.kts 文件中添加如下插件配置：
plugins {
id("org.jetbrains.dokka") version "1.7.20"
}
然后运行以下命令生成 HTML 格式的文档：
$ gradle dokkaHtml
默认输出路径为：{project}/{buildDir}/html
3. 输入输出格式与常用配置项
Dokka 支持 Java 与 Kotlin 混合项目的文档生成，输入格式包括 JavaDoc 和 KDoc，输出支持 HTML、Markdown 和标准 Javadoc HTML。
以下是几个常用的配置项（适用于 Gradle 和 Maven 插件）：
✅ sourceRoots
指定要分析的源码目录，可用于排除某些文件夹。
✅ suppressObviousFunctions
是否隐藏明显函数（如 getter、setter 等），减少冗余内容。
✅ jdkVersion
生成 Java 类型外部文档链接时使用的 JDK 版本。
更多配置细节可参考官方文档：
- Gradle 配置：Dokka Gradle 文档
- Maven 配置：Dokka Maven 文档
4. 示例文档展示
下面我们以一个 Kotlin 类 Blog 为例，展示 Dokka 生成的文档效果。
/**
* A blog of *articles*.
*
* This class it's just a documentation example.
*
* @param T the type of article in this blog.
* @property name the name of this article.
* @constructor Creates an empty blog.
*/
class Blog<T>(val name: String) {
/**
* The variable containing the articles.
*/
private var articles: MutableList<T> = mutableListOf()
/**
* Adds an [article] to this blog.
* @return the new number of articles of the blog.
*/
fun add(article: T): Int {
articles.add(article)
return articles.size
}
/**
* Remove an [article] to this blog.
* @return the new number of articles of the blog.
*/
fun remove(article: T): Int {
articles.remove(article)
return articles.size
}
}
运行 Dokka 后，会生成如下格式清晰、易于阅读的 HTML 文档：
生成的 HTML 页面风格简洁，支持通过自定义 CSS 文件进行主题样式定制，详见 Dokka 官方文档：Dokka Frontend 配置
5. 总结
本文介绍了 Dokka 的基本用法，包括如何在 Maven 和 Gradle 项目中集成 Dokka，支持的输入输出格式，以及常用配置项。最后我们通过一个 Kotlin 类展示了 Dokka 生成文档的实际效果。
所有示例代码都可以在 GitHub 上找到。
✅ Dokka 是 Kotlin 项目中非常实用的文档生成工具，尤其适合需要多语言支持（Java + Kotlin）的项目。
⚠️ 如果你有复杂的文档定制需求，建议使用 CLI 方式生成文档，而不是依赖构建插件。