侧边栏壁纸
博主头像
Z同学博主等级

工作磨平激情前,坚持技术的热忱。 欢迎光临Z同学的技术小站。 分享最新的互联网知识。

  • 累计撰写 274 篇文章
  • 累计创建 55 个标签
  • 累计收到 74 条评论

Kotlin 文档注释的生成-Dokka 1.6.0

Z同学
2021-12-09 / 3 评论 / 1 点赞 / 325 阅读 / 1,944 字
温馨提示:
本文最后更新于 2022-03-09,若内容或图片失效,请留言反馈。部分素材来自网络,若不小心影响到您的利益,请联系我们删除。

Kotlin 文档注释的生成-Dokka 1.6.0

1.介绍

我们如果是进行SDK或者API的提供者。那么当编写过多的代码之后。需要提供规范的API帮助文档。

Kotlin和java类似,提供了一个Kdoc的工具帮助进行注释文档的生成。

注意:生成的前提条件是在源代码中规范的进行了文档注释

2.规则

API帮助文档是要给别人看的,一般是非私有的属性和函数以及类和接口等提供文档注释。

而私有化的接口等,主要是内部使用的可以不用文档注释

3.注释

什么是文档注释呢?在Kotlin的语法中注释分为三种:

  1. 单行注释:使用 //在行首进行添加。一般是给看得到源码的人阅读的
  2. 多行注释:使用/*...*/ 进行注释。一般是给看得到源码的人阅读的
  3. 文档注释:使用/**...*/ 进行注释。一般是给看不到源码的人阅读的。

注释的标准和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 markdown
  • jekyll - 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

指令进行执行,就可以生成指定的注释了。

image.png

生成的速度会有点慢,稍微给点耐心慢慢等待。

生成后的注释文档 在app/build/dokka 文件夹下。

1

评论区