使用Dokka为kotlin自动生成代码文档

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{
            // 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