1.Dokka是什么
Kotlin的文档生成工具。支持kotlin和Java混合开发的项目，及多种格式的输出 (html,javadoc,markdown)，可以为Java和Kotlin输出代码文档。
2. Dokka的引入
关于Dokka的最新版本，请移步 官方文档。
方式1. 使用plugins方式
在 想要引入 dokka功能的模块build.gradle中添加：
plugins {
id("org.jetbrains.dokka") version "1.6.10"
}
方式2：使用apply plugin方式：
在项目根目录的build.gradle文件中的buildscript属性中加入：
dependencies {
classpath "org.jetbrains.dokka:dokka-gradle-plugin:1.6.10"
}
在 想要引入 dokka功能的模块build.gradle中添加：
apply plugin: 'org.jetbrains.dokka'
注：Dokka的引入需要放在com.android.library 和 kotlin-android之后
3. Dokka的配置
可根据自己的需要进行选择，以下为示例：
dokkaHtml {
outputDirectory.set(buildDir.resolve("dokka"))
// 设置输出的最终Module名称
moduleName.set("moduleName")
// 使用默认值或设置为自定义路径来缓存目录
// 启用软件包列表缓存
// 当此设置为默认值时，缓存存储在 $USER_HOME/.cache/dokka
cacheRoot.set(file("default"))
// 抑制类似函数toString 或者 equals. 默认 true
suppressObviousFunctions.set(false)
// 抑制继承成员, 在当前类中不会描述继承成员
// 如果你只想抑制toString/equals, 而不抑制data class的compnentN可以使用suppressObviousFunctions
// 默认 false
suppressInheritedMembers.set(true)
// 设置为离线模式, 仅本地访问
offlineMode.set(false)
dokkaSourceSets {
configureEach { //或者可以设置名称, 对于单一平台默认的sourceSet是 `main` and `test`
// Used when configuring source sets manually for declaring which source sets this one depends on
dependsOn("otherSourceSetName")
// Used to remove a source set from documentation, test source sets are suppressed by default
suppress.set(false)
// 是否包含非public的成员
includeNonPublic.set(false)
// 不输出废弃成员, 适用于全局, 可以覆写包选项
skipDeprecated.set(false)
// 对于未注释文档的警告warring. 适用全局, 可以覆写包选项
reportUndocumented.set(true)
// 对于空的package不创建index索引
skipEmptyPackages.set(true)
// 将最终显示输出的名称
displayName.set("JVM")
// 构建代码分析的平台
platform.set(org.jetbrains.dokka.Platform.jvm)
// 将文件手动添加到类路径中
// This property does not override the classpath collected automatically but appends to it
classpath.from(file("libs/dependency.jar"))
// List of files with module and package documentation
// https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation
includes.from("packages.md", "extra.md")
// 包含示例代码的文件列表 (被 @sample 标签使用的引用)
samples.from("samples/basic.kt", "samples/advanced.kt")
// 资源根目录, 默认是 sourceRoots
sourceRoots.from(file("src"))
// 指定源代码路径, 如果提供会将声明链接上源代码
sourceLink {
// 基于Unix的相对路径 (where you execute gradle respectively).
localDirectory.set(file("src/main/kotlin"))
// 源码网址
remoteUrl.set(java.net.URL(
"https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin"))
// 将行号附着到URL后缀. Use #L for GitHub
remoteLineSuffix.set("#L")
}
// 链接到JDK8文档
jdkVersion.set(8)
// 禁用在线 kotlin-stdlib 文档
noStdlibLink.set(false)
// 禁用在线JDK文档
noJdkLink.set(false)
// 禁用在线Android文档 (只在Android项目有效)
noAndroidSdkLink.set(false)
// 允许链接到项目依赖库的文档 (由Javadoc或者Dokka生成的依赖文档)
// 重复链接
externalDocumentationLink {
// 生成的文档根目录URL. 必须斜杠结尾
url.set(URL("https://example.com/docs/"))
// 如果软件包列表不是位于标准位置
// packageListUrl = URL("file:///home/user/localdocs/package-list")
}
// 指定某个包下定制规则
perPackageOption {
matchingRegex.set("kotlin($|\\.).*") // will match kotlin and all sub-packages of it
// 全部可选, 以下是默认选择:
skipDeprecated.set(false)
reportUndocumented.set(true) // Emit warnings about not documented members
includeNonPublic.set(false)
}
// 抑制指定的package
perPackageOption {
matchingRegex.set(""".*\.internal.*""") // will match all .internal packages and sub-packages
suppress.set(true)
}
// 是否包含文档生成文件, 例如buildDir. 默认不包含
suppressGeneratedFiles.set(false)
}
// Configures a plugin separately from the global configuration
pluginConfiguration<PluginClass, ConfigurationClass>{
// values
}
}
}
4. Dokka的使用
- 在项目右侧
Gradle中，选择想要生成文档的模块，在Tasks - documentation下选择想要生成的KDoc类型，并执行。 - 以
dokkaHtml为例，生成的KDoc会存储在项目—>所选模块—>build—>dokka(build.gradle中配置生成文件夹)—>html中。 - 如果
Gradle下没有Tasks，可参考 解决方法
生成KDoc
5. Dokka语法
请移步 官方文档，内有各个属性的详细介绍
注：对于常量类型，直接在变量上方注释即可在文档中自动生成。
/***
* 对变量的注释
*/
const val URL = ""
5. 参考文档：
https://book.kotlincn.net/text/kotlin-doc.html
https://juejin.cn/post/7018004705804550180
https://juejin.cn/post/6969484426958864414
https://www.jianshu.com/p/406a7bcfb38c
https://blog.csdn.net/eieihihi/article/details/111990496
