废话

Dokka 是 Kotlin 的 API 文档引擎，并且支持java。输出格式也多样：

自己风格的现代HTML 格式
多种风格的Markdown
Java 的Javadoc HTML。

废话到此为止了哈，想看更多介绍移步官网。

下面开始我们正式使用之旅吧。

前期准备

1.对代码进行注释。

既然是文档生成，首先肯定要先对类和方法进行文档注释啦（要不然根据什么生成文档~~），但是as中kotlin代码貌似不像java那样可以直接使用/**回车就能生成方法的参数。

这时候就需要装一个kotlin注释插件了kdoc-generator,它能让你在kotlin代码中使用/**正常生成参数和返回值等数据。至于注释怎么写就自己看官网吧。

2.添加依赖和配置

细心的同学应该也看到了官网上是有说明的（继续引用😜）Get started with Dokka

那就直接上代码吧，在要生成文档的module的build.gralde中：

plugins {
    ...
    id 'org.jetbrains.dokka' version '1.8.20'//引入插件
}

dokkaHtml {//配置参数
    outputDirectory = file("$buildDir/docs")//输出地址
    suppressInheritedMembers.set(true)//抑制父类的方法
    offlineMode.set(true)//是否离线模式
    dokkaSourceSets.configureEach {
            perPackageOption{
                matchingRegex.set("com.test.(activity|broadcast|services|enums|constants).*")//需要隐藏的模块
                suppress.set(true)
            }
            externalDocumentationLink {
                url.set(new URL("https://kotlinlang.org/api/latest/jvm/stdlib/"))
                packageListUrl.set(file("D:/package-list").toURL())//配置本地的package-list，这个package-list文件需要自行下载放到模块目录下，你也可以放到其他地方
            }
        }
    // 配置其他选项...
}

这些是我配置时使用到的一些参数，更多其他参数可以参考文档

3.生成文档

生成文档就更简单啦，直接一个命令./gradlew dokkaHtml就搞定啦，当然其他类型的文档也是类似的：

./gradlew dokkaHtml
./gradlew dokkaGfm
./gradlew dokkaJekyll
./gradlew dokkaJavadoc

4.文档效果

最后来一张图展示呈现的效果吧。

5.遇到的问题

最后总结一下遇到的问题。

1.依赖下载慢问题，这个问题好说，直接手动下载然后放到缓存目录即可，可参考之前文章

2.package-list下载失败：

Failed to download package-list from https://developer.android.com/reference/kotlin/package-list, this might suggest that remote resource is not available, module is empty or dokka output got corrupted

这个问题有两种方式解决：

设置离线模式：这种方式其实上面配置就有配置

offlineMode.set(false)

packageListUrl.set(file("D:/package-list").toURL())
配置gradle代理：

下载失败是连接不上外网，导致的失败，那就让gradle连接上外网就可以了（前提是有科学方法）：
- 在C:\Users\---\.gradle目录下创建gradle.properties文件，里面添加代理配置：
```
systemProp.https.proxyHost=127.0.0.1
systemProp.https.proxyPort=8080
systemProp.https.proxyUser=userid
systemProp.https.proxyPassword=password
systemProp.https.nonProxyHosts=*.nonproxyrepos.com|localhost
```

3.生成的文档无法显示左侧菜单和搜索

就像下面这样的效果：

这主要是前端跨域报错了，不支持跨域访问文件，打开F12你就能看到报错了：

这个文档是没问题的，只要部署到服务器后用http访问就好了。

本地临时部署也简单，先下载一个nodejs再用npm install -g http-server 安装一个http-server 这样在你文档根目录下运行npx http-server这个服务，不出意外的话就可以用http来访问了。

Dokka生成api文档KDoc

废话