Kotlin 文档注释的生成-Dokka 1.6.0
1.介绍
我们如果是进行SDK或者API的提供者。那么当编写过多的代码之后。需要提供规范的API帮助文档。
Kotlin和java类似，提供了一个Kdoc的工具帮助进行注释文档的生成。
注意：生成的前提条件是在源代码中规范的进行了文档注释
2.规则
API帮助文档是要给别人看的，一般是非私有的属性和函数以及类和接口等提供文档注释。
而私有化的接口等，主要是内部使用的可以不用文档注释
3.注释
什么是文档注释呢？在Kotlin的语法中注释分为三种：
- 单行注释：使用
//在行首进行添加。一般是给看得到源码的人阅读的 - 多行注释：使用
/*...*/进行注释。一般是给看得到源码的人阅读的 - 文档注释：使用
/**...*/进行注释。一般是给看不到源码的人阅读的。
注释的标准和java是一样的。
例如类文档注释：
/**
*版权所有：xxxxxx
*许可信息查看：xxxxx
* 描述
* 实现的功能介绍
*历史版本：
* 2020-08-23 ：xxxx
*
*/
等等信息
4.标签注解
我们在使用注释的过程中，会添加各种的标签例如：@author,@return,@param 等
下面就来介绍一些常用标签的意义。
| 标签 | 描述 |
|---|---|
@author | 作者 |
@Deprecated | 标注类，接口或者函数等已经废弃，之后可能被清理 |
@param | 说明函数入参 |
@return | 说明函数返回值，也就是出参 |
@see identifier | 参考另一个对象的链接。通常后面跟着路径 |
@exception | 说明函数所抛出的异常类，通常会携带异常类名称 |
@throws | 和@exception是一样的 |
@version | 标注类或者接口的版本 |
当然，系统还有很多标签注解。上面只是列了一些常见的几种。
5.生成注释文档
Kotlin的注释文档生成需要使用一个Dokka的工具进行：https://github.com/Kotlin/dokka
Dokka支持java和Kotlin混合项目生成KDoc文档。
Dokka生成之后支持四种模式：
html- 默认导出的就是html文档javadoc- 你如果喜欢javadoc的风格，也可以导出为javadoc风格gfm- GitHub flavored markdownjekyll- Jekyll compatible markdown
后两种就是github 和jekyll的 markdown风格了
5.1 命令行模式
如果我们想直接通过命令行生成注释。那么只要下载dokka-cli包就可以了
https://mvnrepository.com/artifact/org.jetbrains.dokka/dokka-cli
然后在cmmmand 中执行：java -jar dokka-cli.jar <你的koltin项目代码目录>
5.2 采用Gradle集成方案
dokka支持Gradle。我们可以直接在idea中配置gradle。下面介绍在Android Studio中的配置方法
1.在项目project 的build.gradle中，添加插件
buildscript {
dependencies {
classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlin_version}")
classpath("org.jetbrains.dokka:dokka-gradle-plugin:1.6.0")
}
}
repositories {
mavenCentral()
}
如果插件下载速度比较慢，建议可以使用阿里的镜像库：https://zinyan.com/?p=75 我的这篇文章有介绍如何替换。
然后在项目的build.gradle之中添加
plugins {
id 'com.android.library'
id 'kotlin-android'
//添加下面的这个
id 'org.jetbrains.dokka'
}
android {
compileSdkVersion 30
buildToolsVersion "30.0.3"
···
dokkaHtml.configure {
dokkaSourceSets {
named("main") {
noAndroidSdkLink.set(false)
}
}
}
}
然后我们可以通过 gradle 面板中的 documentation
指令进行执行，就可以生成指定的注释了。
生成的速度会有点慢，稍微给点耐心慢慢等待。
生成后的注释文档 在app/build/dokka 文件夹下。
评论区