Kotlin/Dokka Gradle插件使用指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00785/article/details/148575517

Kotlin/Dokka Gradle插件使用指南

dokka API documentation engine for Kotlin 项目地址: https://gitcode.com/gh_mirrors/do/dokka

Dokka是Kotlin官方提供的文档生成工具，能够为Kotlin项目自动生成API参考文档。本文将详细介绍如何在Gradle构建的项目中使用Dokka插件。

插件应用

基础应用方式

推荐使用Gradle的plugins DSL方式应用Dokka插件：

plugins {
    id("org.jetbrains.dokka") version "%dokkaVersion%"
}

对于多模块项目，需要在子模块中也应用插件：

subprojects {
    apply(plugin = "org.jetbrains.dokka")
}

注意事项

Dokka依赖Kotlin Gradle插件进行自动配置，请确保项目已应用Kotlin插件
在预编译脚本插件中使用Dokka时，需要添加Kotlin Gradle插件作为依赖

文档生成任务

单项目构建任务

Dokka支持多种输出格式，每种格式都有对应的生成任务：

| 任务名称 | 输出格式 | 说明 | |----------------|------------------------|-----------------------------| | dokkaHtml | HTML格式 | 生成标准HTML文档 | | dokkaGfm | GitHub Markdown格式 | 生成GitHub风格的Markdown文档 | | dokkaJavadoc | Javadoc格式 | 生成兼容Javadoc的文档 | | dokkaJekyll | Jekyll Markdown格式 | 生成Jekyll兼容的Markdown文档 |

默认输出目录为：build/dokka/{格式名称}

多项目构建任务

对于多模块项目，Dokka提供了特殊任务类型：

MultiModule任务：
- 为每个子模块生成独立文档
- 创建统一的目录结构
- 解析跨模块引用
- 任务示例：dokkaHtmlMultiModule
Collector任务：
- 将所有子模块文档合并为单一项目
- 任务示例：dokkaHtmlCollector
Partial任务：
- 为子模块生成中间文档
- 通常由MultiModule任务调用
- 任务示例：dokkaHtmlPartial

配置示例

单项目配置

在build.gradle.kts中配置：

tasks.dokkaHtml {
    outputDirectory.set(layout.buildDirectory.dir("docs/html"))
}

tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets.configureEach {
        documentedVisibilities.set(setOf(Visibility.PUBLIC))
    }
}

多项目配置

在根项目的build.gradle.kts中统一配置：

subprojects {
    apply(plugin = "org.jetbrains.dokka")
    
    tasks.withType<DokkaTaskPartial>().configureEach {
        dokkaSourceSets.configureEach {
            includes.from("README.md")
        }
    }
}

生成javadoc.jar

发布库到Maven仓库时，通常需要提供javadoc.jar文件。可以通过自定义任务实现：

tasks.register<Jar>("dokkaJavadocJar") {
    dependsOn(tasks.dokkaJavadoc)
    from(tasks.dokkaJavadoc.flatMap { it.outputDirectory })
    archiveClassifier.set("javadoc")
}