Dokka Gradle 配置选项

Dokka 提供了许多配置选项，用于自定义您和读者的体验。

以下是每个配置部分的详细说明和一些示例。您还可以找到应用了所有配置选项的示例。

有关为单项目和多项目构建应用配置块的更多详细信息，请参阅配置示例。

通用配置

以下是一个通用的 Dokka Gradle 插件配置示例：

使用顶层的 dokka {} DSL 配置。
在 DGP 中，您在 dokkaPublications{} 块中声明 Dokka 发布配置。
默认发布格式为 html 和 javadoc。
build.gradle.kts 文件的语法与常规 .kt 文件（例如用于 Kotlin 自定义插件的文件）不同，因为 Gradle 的 Kotlin DSL 使用了类型安全访问器。

Gradle Kotlin DSLKotlin custom pluginGradle Groovy DSL

kotlin

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

dokka {
    dokkaPublications.html {
        moduleName.set(project.name)
        moduleVersion.set(project.version.toString())
        // HTML 文档的标准输出目录
        outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
        failOnWarning.set(false)
        suppressInheritedMembers.set(false)
        suppressObviousFunctions.set(true)
        offlineMode.set(false)
        includes.from("packages.md", "extra.md")
        
        // 附加文件的输出目录
        // 当您想要更改输出目录并包含额外文件时，请使用此块而不是标准块
        outputDirectory.set(rootDir.resolve("docs/api/0.x"))
        
        // 使用 fileTree 添加多个文件
        includes.from(
            fileTree("docs") {
                include("**/*.md")
            }
        )
    }
}

有关处理文件的更多信息，请参阅 Gradle 文档。

kotlin

// CustomPlugin.kt

import org.gradle.api.Plugin
import org.gradle.api.Project
import org.jetbrains.dokka.gradle.DokkaExtension

abstract class CustomPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.apply("org.jetbrains.dokka")

        project.extensions.configure(DokkaExtension::class.java) { dokka ->
            
            dokka.moduleName.set(project.name)
            dokka.moduleVersion.set(project.version.toString())

            dokka.dokkaPublications.named("html") { publication ->
                // HTML 文档的标准输出目录
                publication.outputDirectory.set(project.layout.buildDirectory.dir("dokka/html"))
                publication.failOnWarning.set(true)
                publication.suppressInheritedMembers.set(true)
                publication.offlineMode.set(false)
                publication.suppressObviousFunctions.set(true)
                publication.includes.from("packages.md", "extra.md")

                // 附加文件的输出目录
                // 当您想要更改输出目录并包含额外文件时，请使用此块而不是标准块
                html.outputDirectory.set(project.rootDir.resolve("docs/api/0.x"))
            }
        }
    }
}

groovy

plugins {
    id 'org.jetbrains.dokka' version '2.1.0'
}

dokka {
    dokkaPublications {
        html {
            // 设置通用模块信息
            moduleName.set(project.name)
            moduleVersion.set(project.version.toString())

            // HTML 文档的标准输出目录
            outputDirectory.set(layout.buildDirectory.dir("dokka/html"))

            // 核心 Dokka 选项
            failOnWarning.set(false)
            suppressInheritedMembers.set(false)
            suppressObviousFunctions.set(true)
            offlineMode.set(false)
            includes.from(files("packages.md", "extra.md"))

            // 附加文件的输出目录
            // 当您想要更改输出目录并包含额外文件时，请使用此块而不是标准块
            outputDirectory.set(file("$rootDir/docs/api/0.x"))
        }
    }
}

moduleName

项目文档的显示名称。它出现在目录、导航、页眉和日志消息中。在多项目构建中，每个子项目的 moduleName 将用作聚合文档中其对应部分的标题。

默认值：Gradle 项目名称

moduleVersion

在生成的文档中显示的子项目版本。在单项目构建中，它被用作项目版本。在多项目构建中，在聚合文档时会使用每个子项目的 moduleVersion。

默认值：Gradle 项目版本

outputDirectory

生成的文档存储的目录。

此设置适用于 dokkaGenerate 任务生成的所有文档格式（HTML、Javadoc 等）。

默认值：build/dokka/html

附加文件的输出目录

您可以为单项目和多项目构建指定输出目录并包含附加文件。对于多项目构建，请在根项目的配置中设置输出目录并包含附加文件。

failOnWarning

确定在文档生成期间出现警告时，Dokka 是否应使构建失败。该过程会等待所有错误和警告都发出后才停止。

此设置与 reportUndocumented 配合使用效果良好。

默认值：false

suppressInheritedMembers

是否隐藏在给定类中未显式重写的继承成员。

注意：这将隐藏诸如 equals、hashCode 和 toString 之类的函数，但不会隐藏合成函数，如 dataClass.componentN 和 dataClass.copy。请使用 suppressObviousFunctions 来处理后者。

默认值：false

suppressObviousFunctions

是否隐藏显而易见的函数。

如果一个函数满足以下条件，则被认为是显而易见的：

继承自 kotlin.Any、Kotlin.Enum、java.lang.Object 或 java.lang.Enum，例如 equals、hashCode、toString。
由编译器合成（生成）且没有任何文档，例如 dataClass.componentN 或 dataClass.copy。

默认值：true

offlineMode

是否通过网络解析远程文件和链接。

这包括用于生成外部文档链接的 package-list。例如，这可以让您的文档中指向标准库的类变为可点击状态。

在某些情况下，将此项设置为 true 可以显著加快构建时间，但也可能会降低用户体验。例如，无法解析来自依赖项（包括标准库）的类和成员链接。

注意：您可以将获取的文件缓存到本地，并作为本地路径提供给 Dokka。请参阅 externalDocumentationLinks 部分。

默认值：false

includes

包含子项目和软件包文档的 Markdown 文件列表。Markdown 文件必须符合要求的格式。

指定文件的内容将被解析并作为子项目和软件包描述嵌入到文档中。

有关外观及使用方式的示例，请参阅 Dokka Gradle 示例。

源集配置

Dokka 允许为 Kotlin 源集配置一些选项：

Gradle Kotlin DSLGradle Groovy DSL

kotlin

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    // ..
    // 通用配置部分
    // ..

    // 源集配置
    dokkaSourceSets {
        // 示例：仅针对 'linux' 源集的配置
        named("linux") {
            dependentSourceSets{named("native")}
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(VisibilityModifier.Public)) // 或 documentedVisibilities(VisibilityModifier.Public)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")
           
            sourceLink {
                // 源链接部分
            }
            perPackageOption {
                // 软件包选项部分
            }
            externalDocumentationLinks {
                // 外部文档链接部分
            }
        }
    }
}

groovy

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    // ..
    // 通用配置部分
    // ..

    dokkaSourceSets {
        // 示例：仅针对 'linux' 源集的配置
        named("linux") {
            dependentSourceSets { named("native") }
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([VisibilityModifier.Public] as Set) // 或 documentedVisibilities(VisibilityModifier.Public)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                // 源链接部分
            }
            perPackageOption {
                // 软件包选项部分
            }
            externalDocumentationLinks {
                // 外部文档链接部分
            }
        }
    }
}

suppress

生成文档时是否应跳过此源集。

默认值：false

displayName

用于引用此源集的显示名称。

该名称既用于外部（例如，作为文档读者可见的源集名称），也用于内部（例如，用于 reportUndocumented 的日志消息）。

默认情况下，该值是从 Kotlin Gradle 插件提供的信息中推断出来的。

documentedVisibilities

定义 Dokka 在生成的文档中应包含哪些可见性修饰符。

如果您想要记录 protected、internal 和 private 声明，或者如果您想要排除 public 声明并仅记录内部 API，请使用此项。

此外，您可以使用 Dokka 的 documentedVisibilities() 函数来添加记录的可见性。

可以为每个单独的软件包配置此项。

默认值：VisibilityModifier.Public

reportUndocumented

是否对可见的未记录声明（即经过 documentedVisibilities 和其他过滤器过滤后没有 KDoc 的声明）发出警告。

此设置与 failOnWarning 配合使用效果良好。

可以为每个单独的软件包配置此项。

默认值：false

skipEmptyPackages

在应用各种过滤器后，是否跳过不包含可见声明的软件包。

例如，如果 skipDeprecated 设置为 true 且您的软件包仅包含已弃用的声明，则该软件包将被视为空。

默认值：true

skipDeprecated

是否记录带有 @Deprecated 注解的声明。

可以为每个单独的软件包配置此项。

默认值：false

suppressGeneratedFiles

是否记录生成的文件。

生成的文件预计位于 {project}/{buildDir}/generated 目录下。

如果设置为 true，它会有效地将该目录中的所有文件添加到 suppressedFiles 选项中，以便您可以手动配置它。

默认值：true

suppressAnnotatedWith

用于隐藏带有所述注解的声明的注解完全限定名 (FQN) 集合。

任何带有所列注解之一的声明都将从生成的文档中排除。

jdkVersion

为 Java 类型生成外部文档链接时要使用的 JDK 版本。

例如，如果您在某些公共声明签名中使用 java.util.UUID，且此选项设置为 8，Dokka 会为其生成指向 JDK 8 Javadoc 的外部文档链接。

默认值：8

languageVersion

用于设置分析和 @sample 环境的 Kotlin 语言版本。

默认情况下，使用 Dokka 内置编译器可用的最新语言版本。

apiVersion

用于设置分析和 @sample 环境的 Kotlin API 版本。

默认情况下，它是从 languageVersion 推断出来的。

sourceRoots

要分析和记录的源代码根目录。可接受的输入是目录以及单个 .kt 和 .java 文件。

默认情况下，源根目录是从 Kotlin Gradle 插件提供的信息中推断出来的。

classpath

用于分析和交互式示例的类路径。

如果某些来自依赖项的类型无法自动解析或识别，这会非常有用。

此选项接受 .jar 和 .klib 文件。

默认情况下，类路径是从 Kotlin Gradle 插件提供的信息中推断出来的。

samples

包含通过 @sample KDoc 标记引用的示例函数的目录或文件列表。

源链接配置

配置源链接，以帮助读者在远程仓库中查找每个声明的源代码。请使用 dokkaSourceSets.main {} 块进行此配置。

sourceLinks {} 配置块允许您向每个签名添加一个 source 链接，该链接指向带有特定行号的 remoteUrl。行号可以通过设置 remoteLineSuffix 来配置。

有关示例，请参阅 kotlinx.coroutines 中 count() 函数的文档。

build.gradle.kts 文件的语法与常规 .kt 文件（例如用于自定义 Gradle 插件的文件）不同，因为 Gradle 的 Kotlin DSL 使用了类型安全访问器：

Gradle Kotlin DSLKotlin custom pluginGradle Groovy DSL

kotlin

// build.gradle.kts

dokka {
    dokkaSourceSets.main {
        sourceLink {
            localDirectory.set(file("src/main/kotlin"))
            remoteUrl("https://github.com/your-repo")
            remoteLineSuffix.set("#L")
        }
    }
}

kotlin

// CustomPlugin.kt

import org.gradle.api.Plugin
import org.gradle.api.Project
import org.jetbrains.dokka.gradle.DokkaExtension

abstract class CustomPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.apply("org.jetbrains.dokka")
        project.extensions.configure(DokkaExtension::class.java) { dokka ->
            dokka.dokkaSourceSets.named("main") { dss ->
                dss.includes.from("README.md")
                dss.sourceLink {
                    it.localDirectory.set(project.file("src/main/kotlin"))
                    it.remoteUrl("https://example.com/src")
                    it.remoteLineSuffix.set("#L")
                }
            }
        }
    }
}

groovy

dokka {
    dokkaSourceSets {
        main {
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(new URI("https://github.com/your-repo"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

localDirectory

本地源 directory 的路径。路径必须相对于当前项目的根目录。

remoteUrl

文档读者可以访问的源代码托管服务的 URL，例如 GitHub、GitLab、Bitbucket 或任何为源文件提供稳定 URL 的托管服务。此 URL 用于生成声明的源代码链接。

remoteLineSuffix

用于在 URL 后追加源代码行号的后缀。这有助于读者不仅导航到文件，还可以导航到声明的具体行号。

数字本身会追加到指定的后缀之后。例如，如果此选项设置为 #L 且行号为 10，则生成的 URL 后缀为 #L10。

常用服务使用的后缀：

GitHub: #L
GitLab: #L
Bitbucket: #lines-

默认值：#L

软件包选项

perPackageOption 配置块允许为由 matchingRegex 匹配的特定软件包设置一些选项：

Gradle Kotlin DSLGradle Groovy DSL

kotlin

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    dokkaPublications.html {
        dokkaSourceSets.configureEach {
            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set(setOf(VisibilityModifier.Public)) // 或 documentedVisibilities(VisibilityModifier.Public)
            }
        }
    }
}

groovy

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    dokkaPublications {
        html {
            dokkaSourceSets.configureEach {
                perPackageOption {
                    matchingRegex.set(".*api.*")
                    suppress.set(false)
                    skipDeprecated.set(false)
                    reportUndocumented.set(false)
                    documentedVisibilities.set([VisibilityModifier.Public] as Set)
                }
            }
        }
    }
}

matchingRegex

用于匹配软件包的正则表达式。

默认值：.*

suppress

生成文档时是否应跳过该软件包。

默认值：false

skipDeprecated

是否记录带有 @Deprecated 注解的声明。

可以在源集级别配置此项。

默认值：false

reportUndocumented

是否对可见的未记录声明（即经过 documentedVisibilities 和其他过滤器过滤后没有 KDoc 的声明）发出警告。

此设置与 failOnWarning 配合使用效果良好。

可以在源集级别配置此项。

默认值：false

documentedVisibilities

定义 Dokka 在生成的文档中应包含哪些可见性修饰符。

如果您想要记录此软件包内的 protected、internal 和 private 声明，以及如果您想要排除 public 声明并仅记录内部 API，请使用此项。

此外，您可以使用 Dokka 的 documentedVisibilities() 函数来添加记录的可见性。

可以在源集级别配置此项。

默认值：VisibilityModifier.Public

外部文档链接配置

externalDocumentationLinks {} 块允许创建指向依赖项外部托管文档的链接。

例如，如果您正在使用来自 kotlinx.serialization 的类型，默认情况下它们在您的文档中是不可点击的，就好像它们未解析一样。然而，由于 kotlinx.serialization 的 API 参考文档是由 Dokka 构建并发布在 kotlinlang.org 上的，您可以为其配置外部文档链接。这允许 Dokka 为该库中的类型生成链接，使它们能够成功解析并可点击。

默认情况下，已经配置了 Kotlin 标准库、JDK、Android SDK 和 AndroidX 的外部文档链接。

使用 register() 方法注册外部文档链接以定义每个链接。externalDocumentationLinks API 使用此方法来符合 Gradle DSL 约定：

Gradle Kotlin DSLGradle Groovy DSL

kotlin

dokka {
    dokkaSourceSets.configureEach {
        externalDocumentationLinks.register("example-docs") {
            url("https://example.com/docs/")
            packageListUrl("https://example.com/docs/package-list")
        }
    }
}

groovy

dokka {
    dokkaSourceSets.configureEach {
        externalDocumentationLinks.register("example-docs") {
            url.set(new URI("https://example.com/docs/"))
            packageListUrl.set(new URI("https://example.com/docs/package-list"))
        }
    }
}

url

要链接到的文档的根 URL。它必须包含结尾斜杠。

Dokka 会尽力为指定的 URL 自动查找 package-list，并将声明链接在一起。

如果自动解析失败，或者如果您想使用本地缓存的文件，请考虑设置 packageListUrl 选项。

packageListUrl

package-list 的确切位置。这是依赖 Dokka 自动解析之外的一种替代方案。

软件包列表包含有关文档和项目本身的信息，例如子项目和软件包名称。

这也可以是本地缓存的文件，以避免网络调用。

完整配置

在下方，您可以查看同时应用了所有可能配置选项的情况：

Gradle Kotlin DSLGradle Groovy DSL

kotlin

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

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

dokka {
    dokkaPublications.html {
        moduleName.set(project.name)
        moduleVersion.set(project.version.toString())
        outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
        failOnWarning.set(false)
        suppressInheritedMembers.set(false)
        suppressObviousFunctions.set(true)
        offlineMode.set(false)
        includes.from("packages.md", "extra.md")
   }

    dokkaSourceSets {
        // 示例：仅针对 'linux' 源集的配置
        named("linux") {
            dependentSourceSets{named("native")}
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(VisibilityModifier.Public)) // 或 documentedVisibilities(VisibilityModifier.Public)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl("https://example.com/src")
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLinks {
                url = URL("https://example.com/docs/")
                packageListUrl = File("/path/to/package-list").toURI().toURL()
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set(
                    setOf(
                        VisibilityModifier.Public,
                        VisibilityModifier.Private,
                        VisibilityModifier.Protected,
                        VisibilityModifier.Internal,
                        VisibilityModifier.Package
                    )
                )
            }
        }
    }
}

groovy

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

plugins {
    id 'org.jetbrains.dokka' version '2.1.0'
}

dokka {
    dokkaPublications {
        html {
            moduleName.set(project.name)
            moduleVersion.set(project.version.toString())
            outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
            failOnWarning.set(false)
            suppressInheritedMembers.set(false)
            suppressObviousFunctions.set(true)
            offlineMode.set(false)
            includes.from("packages.md", "extra.md")
        }
    }

    dokkaSourceSets {
        // 示例：仅针对 'linux' 源集的配置
        named("linux") {
            dependentSourceSets { named("native") }
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([VisibilityModifier.Public] as Set)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(new URI("https://example.com/src"))
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLinks {
                url.set(new URI("https://example.com/docs/"))
                packageListUrl.set(new File("/path/to/package-list").toURI().toURL())
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set([
                        VisibilityModifier.Public,
                        VisibilityModifier.Private,
                        VisibilityModifier.Protected,
                        VisibilityModifier.Internal,
                        VisibilityModifier.Package
                ] as Set)
            }
        }
    }
}

构建器

特殊类与接口

属性

使用 Kotlin 和 Spring Boot 创建 Web 应用

Kotlin/JS

WebAssembly (Wasm)

内存管理器

最小化心智负担

Dokka

运行 Dokka

输出格式

Java 到 Kotlin 迁移指南

Swift/Objective-C 互操作

C 互操作

Kotlin Notebook 入门

使用数据源

数据可视化

集合

检索

操作与操作符

Kotlin 2.2.x

Kotlin 2.1.x

Kotlin 2.0.x

Kotlin 1.9.x

Kotlin 1.8.x

Kotlin 1.7.x

Kotlin 1.6.x

Kotlin 1.5.x

Kotlin 1.4.x

Kotlin 1.3.x

Dokka Gradle 配置选项

通用配置

源集配置

源链接配置

软件包选项

外部文档链接配置

完整配置

运行 Dokka

输出格式

检索

操作与操作符

Dokka Gradle 配置选项 ​

通用配置 ​

源集配置 ​

源链接配置 ​

软件包选项 ​

外部文档链接配置 ​

完整配置 ​

Dokka Gradle 配置选项

通用配置

源集配置

源链接配置

软件包选项

外部文档链接配置

完整配置