使用Dokka为Kotlin代码生成KDoc

Posted 2023-03-25

参考技术A Dokka是Kotlin的文档引擎，执行与Java的javadoc相同的功能。就像Kotlin本身一样，Dokka完全支持Java / Kotlin混合语言项目。

Dokka目前使用的还是比较少的,官方给的demo也是使用 build.gradle.kts 文件,这是采用了 Gradle Script Kotlin 的替代 Groovy 配置 build.gradle 的一种新的方式,而国内的大多数项目目前还是以 Groovy 为主,所以接下来的配置方式,主要以 Groovy 为主

如果想要配置 Kotlin Script 的方式可以参考 官方例子

第一步引入dokka

最简单配置方式

这里只设置了dokka输出目录,这里我们在根目录下生成了 dokkadocs 目录存放我们的生成的文档

当然,这种简单的方式,在实际开发中没有办法满足我们一些扩展需求,我们需要更多dokka的配置选项

我们可以选择 android 增加我们的所需要的配置项:

根据上面的我们已经完成Dokka的基础配置

(1)就像JavaDoc一样，KDoc注释以开头/* 和结尾 /。注释的每一行都可以以星号开头，该星号不被视为注释内容的一部分。
(2)按照规定，文档文本的第一段（直到第一个空白行的文本块）是元素的摘要描述，而后面的文本是详细描述。
(3)每个块标记都以新行开头，并以@字符开头。

记录函数的值参数或类，属性或函数的类型参数。为了更好地将参数名称与描述分开，可以根据需要将参数名称括在方括号中。因此，以下两种语法是等效的：

记录函数的返回值。

记录类的主要构造函数。

记录扩展功能的接收者。

记录具有指定名称的类的属性。此标记可用于记录在主构造函数中声明的属性，在该构造函数中，在属性定义之前直接放置doc注释会很尴尬。

记录可以由方法引发的异常。由于Kotlin没有检查异常，因此也不希望记录所有可能的异常，但是当它为类的用户提供有用的信息时，您仍然可以使用此标记。

将具有指定限定名称的函数主体嵌入到当前元素的文档中，以显示如何使用该元素的示例。

将指向指定类或方法的链接添加到文档的“另请参见”块。

指定要记录的元素的作者。

指定引入了要记录的元素的软件版本。

从生成的文档中排除元素。可以用于那些不是模块官方API一部分但仍然必须在外部可见的元素。

这里我们看一个使用示例:

这里面有种文档的方式,根据自己需要右键点击 run 就可以了

命令也有四种生成文档的方式,这里我们以dokkahtml为例执行命令:

参考文档

https://kotlin.github.io/dokka/1.4.20/
https://github.com/Kotlin/dokka
https://kotlinlang.org/docs/reference/kotlin-doc.html