1. 概述
KDoc 是 Kotlin 官方推荐的代码文档格式，可看作是 Javadoc 的扩展版本，专门支持 Kotlin 语言特有的语法结构。
本文将介绍 KDoc 的基本用法、优势以及如何高效地在项目中使用它。我们还会探讨几种常见的文档编写方式，帮助你在团队协作和维护性上少踩坑。
2. 理解 KDoc
KDoc 的核心设计融合了 Javadoc 的块标签语法 和 Markdown 的行内标记语法，兼具结构化与可读性。
✅ 关键点：
- Kotlin 编译器能识别 KDoc 语法
- 配合 Dokka 工具，可生成 HTML、PDF 等多种格式的文档
- 统一的文档风格有助于提升代码可读性和团队协作效率
⚠️ 注意：虽然写法类似 Javadoc，但 KDoc 支持 Markdown 渲染，因此你可以使用 *斜体*、**加粗** 等语法增强表达力。
3. 如何使用 KDoc
KDoc 注释以 /** 开始，*/ 结束，每行前的 * 不属于内容部分（仅用于排版）。根据约定：
- 第一个空行前的内容为 摘要描述
- 后续内容为 详细说明
3.1 示例类
下面是一个 Blog 类的完整 KDoc 示例，包含泛型、属性、构造函数、方法和引用等常见元素：
/**
* A blog of *articles*.
*
* This class is just a **documentation example**.
*
* @param T the type of article in this blog.
* @property name the name of this blog.
* @constructor creates an empty blog.
* @see com.baeldung.kdoc.TitledArticle
* @sample com.baeldung.kdoc.blogSample
*/
class Blog<T>(private val name: String) {
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
}
}
/**
* An article with a title.
*
* @property title the title of this article.
* @constructor creates an article with a title.
*/
data class TitledArticle(private val title: String)
private fun blogSample() {
val blog = Blog<TitledArticle>("Baeldung on Kotlin")
val blogCount = blog.add(TitledArticle("An Introduction to KDoc"))
}
📌 要点解析：
- 使用
[article]可自动链接到参数名，这是 KDoc 特有的 Markdown 扩展 @see提供相关类的跳转链接，便于阅读者快速定位@sample引入实际调用示例，极大提升文档实用性 —— 这个功能很多人不知道，但特别实用！
3.2 常用块标签（Block Tags）
KDoc 的块标签以 @ 开头，必须写在被注释元素的上方。以下是开发中最常用的标签清单：
| 标签 | 用途 |
|---|---|
@param |
描述函数或构造函数的参数 |
@return |
说明返回值含义 |
@throws / @exception |
声明可能抛出的异常类型 |
@receiver |
用于扩展函数，描述接收者对象 |
@property |
文档化类或接口中的属性 |
@constructor |
描述构造函数行为 |
@see |
关联其他类或方法，增强导航性 |
@sample |
内嵌代码示例，强烈建议多用 |
@since |
标记该元素从哪个版本引入 |
@suppress |
忽略特定编译警告 |
@author |
标注作者信息（虽不强制，但在开源项目中有价值） |
❌ 常见误区：
不要滥用 @author，尤其在公司内部项目中容易引发“甩锅文化”。更推荐通过 Git 提交记录追溯责任人。
✅ 推荐实践：
结合 CI 流程使用 Dokka 自动生成文档，并部署到内部 Wiki 或静态站点，让文档真正“活”起来。
4. 总结
KDoc 凭借其对 Javadoc 语法的兼容性和对 Markdown 的良好支持，成为 Kotlin 项目中不可或缺的文档工具。
它不仅能让 IDE 更好地提示代码意图，还能通过 Dokka 输出高质量外部文档。合理使用 @param、@return、尤其是 @sample 这类标签，可以显著提升代码的可维护性和新人上手速度。
📌 最后提醒：写文档不是形式主义，而是对自己和同事的时间负责。别等到接手人骂你“没文档”时才后悔没早点规范使用 KDoc。