Dokka Gradle 配置選項

Dokka 提供許多配置選項來建立您與讀者的體驗。

以下是每個配置區塊的詳細說明與一些範例。您也可以找到套用了所有配置選項的範例。

有關為單專案與多專案組建套用配置區塊的更多詳細資訊，請參閱配置範例。

一般配置

以下是一般 Dokka Gradle 外掛程式配置的範例：

使用最上層的 dokka {} DSL 配置。
在 DGP 中，您在 dokkaPublications{} 區塊中宣告 Dokka 發佈配置。
預設發佈為 html 與 javadoc。
build.gradle.kts 檔案的語法與一般 .kt 檔案（例如用於 Kotlin 自訂外掛程式的檔案）有所不同，因為 Gradle 的 Kotlin DSL 使用型別安全存取子。

Gradle Kotlin DSLKotlin 自訂外掛程式Gradle 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 與其他篩選器篩選後，沒有 KDocs 的宣告。

此設定與 failOnWarning 配合良好。

這可以為每個個別套件進行配置。

預設值：false

skipEmptyPackages

在套用各種篩選器後，是否略過不含任何可見宣告的套件。

例如，如果 skipDeprecated 設定為 true 且您的套件僅包含已棄用的宣告，則該套件會被視為空。

預設值：true

skipDeprecated

是否為標註有 @Deprecated 的宣告編寫文件。

這可以為每個個別套件進行配置。

預設值：false

suppressGeneratedFiles

是否為產生的檔案編寫文件。

產生的檔案預期存在於 {project}/{buildDir}/generated 目錄下。

如果設定為 true，它實際上會將該目錄中的所有檔案新增到 suppressedFiles 選項中，以便您可以手動配置。

預設值：true

suppressAnnotatedWith

一組用於隱藏標註有特定註解之宣告的註解完全限定名稱 (FQNs)。

任何標註有這些註解之一的宣告都會從產生的文件中排除。

jdkVersion

為 Java 型別產生外部文件連結時要使用的 JDK 版本。

例如，如果您在某些公共宣告簽章中使用 java.util.UUID，且此選項設定為 8，Dokka 會為其產生指向 JDK 8 Javadocs 的外部文件連結。

預設值：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 自訂外掛程式Gradle 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

本機原始碼目錄的路徑。路徑必須相對於目前專案的根目錄。

remoteUrl

文件讀者可以存取的原始碼代管服務網址，例如 GitHub、GitLab、Bitbucket，或任何提供原始碼檔案穩定網址的代管服務。此網址用於產生宣告的原始碼連結。

remoteLineSuffix

用於在網址後附加原始碼行號的後綴。這有助於讀者導覽到檔案，甚至導覽到宣告的特定行號。

數字本身會被附加到指定的後綴。例如，如果此選項設定為 #L 且行號為 10，產生的網址後綴為 #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 與其他篩選器篩選後，沒有 KDocs 的宣告。

此設定與 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

要連結到的文件的根網址。它必須包含尾隨斜槓。

Dokka 會盡力自動尋找給定網址的 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 配置選項

一般配置

原始碼集配置

原始碼連結配置

套件選項

外部文件連結配置

完整配置