Maven

欲為基於 Maven 的專案生成文件，您可以使用 Dokka 的 Maven 外掛程式。

NOTE

相較於 Dokka 的 Gradle 外掛程式，Maven 外掛程式僅提供基本功能，不支援多模組建構。

您可以透過造訪我們的 Maven 範例專案來試用 Dokka，並了解如何在 Maven 專案中配置它。

應用 Dokka

欲應用 Dokka，您需要將 dokka-maven-plugin 加入您的 POM 檔案的 plugins 區段：

xml

<build>
    <plugins>
        <plugin>
            <groupId>org.jetbrains.dokka</groupId>
            <artifactId>dokka-maven-plugin</artifactId>
            <version>2.0.0</version>
            <executions>
                <execution>
                    <phase>pre-site</phase>
                    <goals>
                        <goal>dokka</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

生成文件

Maven 外掛程式提供了以下目標：

目標	描述
`dokka:dokka`	使用 Dokka 外掛程式生成文件。預設為 HTML 格式。

實驗性

目標	描述
`dokka:javadoc`	以 Javadoc 格式生成文件。
`dokka:javadocJar`	生成一個包含 Javadoc 格式文件的 `javadoc.jar` 檔案。

其他輸出格式

預設情況下，Dokka 的 Maven 外掛程式會以 HTML 輸出格式建構文件。

所有其他輸出格式都以 Dokka 外掛程式的形式實現。為了生成所需格式的文件，您必須將其作為 Dokka 外掛程式添加到配置中。

例如，要使用實驗性的 GFM 格式，您必須添加 gfm-plugin 構件：

xml

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <dokkaPlugins>
            <plugin>
                <groupId>org.jetbrains.dokka</groupId>
                <artifactId>gfm-plugin</artifactId>
                <version>2.0.0</version>
            </plugin>
        </dokkaPlugins>
    </configuration>
</plugin>

透過此配置，執行 dokka:dokka 目標會生成 GFM 格式的文件。

要了解更多關於 Dokka 外掛程式的資訊，請參閱 Dokka 外掛程式。

建構 javadoc.jar

如果您想將您的程式庫發佈到儲存庫，您可能需要提供一個包含您程式庫 API 參考文件的 javadoc.jar 檔案。

例如，如果您想發佈到 Maven Central，您必須連同您的專案一起提供一個 javadoc.jar。然而，並非所有儲存庫都有此規定。

與 Dokka 的 Gradle 外掛程式不同的是，Maven 外掛程式隨附一個隨時可用的 dokka:javadocJar 目標。預設情況下，它會在 target 資料夾中生成 Javadoc 輸出格式的文件。

如果您不滿意內建目標或想自訂輸出（例如，您想生成 HTML 格式的文件而非 Javadoc），可以透過添加帶有以下配置的 Maven JAR 外掛程式來實現類似行為：

xml

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>3.3.0</version>
    <executions>
        <execution>
            <goals>
                <goal>test-jar</goal>
            </goals>
        </execution>
        <execution>
            <id>dokka-jar</id>
            <phase>package</phase>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <classifier>dokka</classifier>
                <classesDirectory>${project.build.directory}/dokka</classesDirectory>
                <skipIfEmpty>true</skipIfEmpty>
            </configuration>
        </execution>
    </executions>
</plugin>

文件及其 .jar 歸檔可以透過執行 dokka:dokka 和 jar:jar@dokka-jar 目標來生成：

Bash

mvn dokka:dokka jar:jar@dokka-jar

TIP

如果您將您的程式庫發佈到 Maven Central，您可以使用像 javadoc.io 這樣的服務，免費且無需任何設置地託管您程式庫的 API 文件。它直接從 javadoc.jar 中獲取文件頁面。它與 HTML 格式配合良好，如此範例所示。

配置範例

Maven 的外掛程式配置區塊可用於配置 Dokka。

這是一個基本配置範例，僅更改文件的輸出位置：

xml

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <outputDir>${project.basedir}/target/documentation/dokka</outputDir>
    </configuration>
</plugin>

配置選項

Dokka 有許多配置選項，可以客製化您和讀者的體驗。

下方是一些範例以及每個配置區段的詳細描述。您也可以在頁面底部找到一個應用了所有配置選項的範例。

一般配置

xml

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <!--  ...  -->
    <configuration>
        <skip>false</skip>
        <moduleName>${project.artifactId}</moduleName>
        <outputDir>${project.basedir}/target/documentation</outputDir>
        <failOnWarning>false</failOnWarning>
        <suppressObviousFunctions>true</suppressObviousFunctions>
        <suppressInheritedMembers>false</suppressInheritedMembers>
        <offlineMode>false</offlineMode>
        <sourceDirectories>
            <dir>${project.basedir}/src</dir>
        </sourceDirectories>
        <documentedVisibilities>
            <visibility>PUBLIC</visibility>
            <visibility>PROTECTED</visibility>
        </documentedVisibilities>
        <reportUndocumented>false</reportUndocumented>
        <skipDeprecated>false</skipDeprecated>
        <skipEmptyPackages>true</skipEmptyPackages>
        <suppressedFiles>
            <file>/path/to/dir</file>
            <file>/path/to/file</file>
        </suppressedFiles>
        <jdkVersion>8</jdkVersion>
        <languageVersion>1.7</languageVersion>
        <apiVersion>1.7</apiVersion>
        <noStdlibLink>false</noStdlibLink>
        <noJdkLink>false</noJdkLink>
        <includes>
            <include>packages.md</include>
            <include>extra.md</include>
        </includes>
        <classpath>${project.compileClasspathElements}</classpath>
        <samples>
            <dir>${project.basedir}/samples</dir>
        </samples>
        <sourceLinks>
            <!-- Separate section -->
        </sourceLinks>
        <externalDocumentationLinks>
            <!-- Separate section -->
        </externalDocumentationLinks>
        <perPackageOptions>
            <!-- Separate section -->
        </perPackageOptions>
    </configuration>
</plugin>

skip

是否跳過文件生成。

預設值：false

moduleName

用於指稱專案/模組的顯示名稱。它用於目錄、導航、日誌等。

預設值：{project.artifactId}

outputDir

生成文件的目錄，不論格式如何。

預設值：{project.basedir}/target/dokka

failOnWarning

如果 Dokka 發出警告或錯誤，是否讓文件生成失敗。此過程會先等待所有錯誤和警告都發出。

此設定與 reportUndocumented 配合良好。

預設值：false

suppressObviousFunctions

是否抑制顯而易見的函數。

如果函數符合以下條件，則被視為顯而易見：

繼承自 kotlin.Any、Kotlin.Enum、java.lang.Object 或 java.lang.Enum，例如 equals、hashCode、toString。
合成的（由編譯器生成）且沒有任何文件，例如 dataClass.componentN 或 dataClass.copy。

預設值：true

suppressInheritedMembers

是否抑制在給定類別中未明確覆寫的繼承成員。

注意：這可以抑制諸如 equals/hashCode/toString 之類的函數，但不能抑制諸如 dataClass.componentN 和 dataClass.copy 之類的合成函數。請為此使用 suppressObviousFunctions。

預設值：false

offlineMode

是否透過您的網路解析遠端檔案/連結。

這包括用於生成外部文件連結的 package-list。例如，使標準程式庫中的類別可點擊。

將其設定為 true 在某些情況下可以顯著加快建構時間，但也可能降低文件品質和使用者體驗。例如，透過不解析來自您的依賴項（包括標準程式庫）的類別/成員連結。

注意：您可以將擷取的檔案本地快取並將其作為本地路徑提供給 Dokka。請參閱 externalDocumentationLinks 區段。

預設值：false

sourceDirectories

要分析和記錄的原始碼根目錄。可接受的輸入是目錄和單個 .kt / .java 檔案。

預設值：{project.compileSourceRoots}

documentedVisibilities

應被記錄的可見性修飾符集合。

如果您想記錄 protected/internal/private 宣告，以及如果您想排除 public 宣告並只記錄內部 API，則可以使用此選項。

可以按每個套件進行配置。

預設值：PUBLIC

reportUndocumented

是否發出關於可見的未記錄宣告的警告，即經過 KDoc 過濾後 documentedVisibilities 和其他過濾器過濾後沒有 KDoc 的宣告。

此設定與 failOnWarning 配合良好。

這可以在套件層級覆寫。

預設值：false

skipDeprecated

是否記錄帶有 @Deprecated 註解的宣告。

這可以在套件層級覆寫。

預設值：false

skipEmptyPackages

是否跳過在應用各種過濾器後不包含任何可見宣告的套件。

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

預設值：true

suppressedFiles

應被抑制的目錄或單個檔案，這表示其中的宣告不會被記錄。

jdkVersion

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

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

預設值：JDK 8

languageVersion

用於設置分析和 @sample 環境的 Kotlin 語言版本。

預設情況下，使用 Dokka 內嵌編譯器可用的最新語言版本。

apiVersion

用於設置分析和 @sample 環境的 Kotlin API 版本。

預設情況下，它從 languageVersion 推斷。

noStdlibLink

是否生成指向 Kotlin 標準程式庫 API 參考文件的外部文件連結。

注意：當 noStdLibLink 設定為 false 時，連結會生成。

預設值：false

noJdkLink

是否生成指向 JDK Javadocs 的外部文件連結。

JDK Javadocs 的版本由 jdkVersion 選項決定。

注意：當 noJdkLink 設定為 false 時，連結會生成。

預設值：false

includes

包含模組和套件文件的 Markdown 檔案列表。

指定檔案的內容會被解析並嵌入到文件中作為模組和套件描述。

classpath

用於分析和互動式範例的 classpath。

如果來自依賴項的某些型別未自動解析/拾取，此選項會很有用。此選項接受 .jar 和 .klib 檔案。

預設值：{project.compileClasspathElements}

samples

包含透過 @sample KDoc 標籤引用之範例函數的目錄或檔案列表。

原始碼連結配置

sourceLinks 配置區塊允許您為每個簽名添加一個 source 連結，該連結指向帶有特定行號的 url。（行號可以透過設定 lineSuffix 來配置）。

這有助於讀者找到每個宣告的原始碼。

例如，請參閱 kotlinx.coroutines 中 count() 函數的文件。

xml

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <!--  ...  -->
    <configuration>
        <sourceLinks>
            <link>
                <path>src</path>
                <url>https://github.com/kotlin/dokka/tree/master/src</url>
                <lineSuffix>#L</lineSuffix>
            </link>
        </sourceLinks>
    </configuration>
</plugin>

path

本地原始碼目錄的路徑。該路徑必須相對於當前模組的根目錄。

注意：僅允許基於 Unix 的路徑，Windows 風格的路徑將拋出錯誤。

url

文件讀者可以訪問的原始碼託管服務的 URL，例如 GitHub、GitLab、Bitbucket 等。此 URL 用於生成宣告的原始碼連結。

lineSuffix

用於將原始碼行號附加到 URL 的後綴。這有助於讀者不僅導航到檔案，還能導航到宣告的特定行號。

數字本身會附加到指定的後綴。例如，如果此選項設定為 #L 且行號為 10，則結果 URL 後綴為 #L10。

常用服務使用的後綴：

GitHub：#L
GitLab：#L
Bitbucket：#lines-

外部文件連結配置

externalDocumentationLinks 區塊允許創建指向您依賴項的外部託管文件的連結。

例如，如果您使用 kotlinx.serialization 中的型別，預設情況下它們在您的文件中是不可點擊的，如同它們未解析一樣。然而，由於 kotlinx.serialization 的 API 參考文件由 Dokka 建構並發佈在 kotlinlang.org 上，您可以為其配置外部文件連結。從而允許 Dokka 為程式庫中的型別生成連結，使其成功解析並可點擊。

預設情況下，Kotlin 標準程式庫和 JDK 的外部文件連結已配置。

xml

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <!--  ...  -->
    <configuration>
        <externalDocumentationLinks>
            <link>
                <url>https://kotlinlang.org/api/kotlinx.serialization/</url>
                <packageListUrl>file:/${project.basedir}/serialization.package.list</packageListUrl>
            </link>
        </externalDocumentationLinks>
    </configuration>
</plugin>

url

要連結到的文件的根 URL。它必須包含一個尾隨斜線。

Dokka 會盡力自動查找給定 URL 的 package-list，並將宣告連結在一起。

如果自動解析失敗或您想使用本地快取檔案，請考慮設定 packageListUrl 選項。

packageListUrl

package-list 的確切位置。這是依賴 Dokka 自動解析它的替代方案。

套件列表包含有關文件和專案本身的信息，例如模組和套件名稱。

這也可以是本地快取檔案，以避免網路呼叫。

套件選項

perPackageOptions 配置區塊允許為由 matchingRegex 匹配的特定套件設定一些選項。

xml

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <!--  ...  -->
    <configuration>
        <perPackageOptions>
            <packageOptions>
                <matchingRegex>.*api.*</matchingRegex>
                <suppress>false</suppress>
                <reportUndocumented>false</reportUndocumented>
                <skipDeprecated>false</skipDeprecated>
                <documentedVisibilities>
                    <visibility>PUBLIC</visibility>
                    <visibility>PRIVATE</visibility>
                    <visibility>PROTECTED</visibility>
                    <visibility>INTERNAL</visibility>
                    <visibility>PACKAGE</visibility>
                </documentedVisibilities>
            </packageOptions>
        </perPackageOptions>
    </configuration>
</plugin>

matchingRegex

用於匹配套件的正規表達式。

預設值：.*

suppress

生成文件時是否應跳過此套件。

預設值：false

documentedVisibilities

應被記錄的可見性修飾符集合。

如果您想記錄此套件中的 protected/internal/private 宣告，以及如果您想排除 public 宣告並只記錄內部 API，則可以使用此選項。

預設值：PUBLIC

skipDeprecated

是否記錄帶有 @Deprecated 註解的宣告。

這可以在專案/模組層級設定。

預設值：false

reportUndocumented

是否發出關於可見的未記錄宣告的警告，即經過 KDoc 過濾後 documentedVisibilities 和其他過濾器過濾後沒有 KDoc 的宣告。

此設定與 failOnWarning 配合良好。

預設值：false

完整配置

下方您可以看到所有可能的配置選項同時應用。

xml

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <!--  ...  -->
    <configuration>
        <skip>false</skip>
        <moduleName>${project.artifactId}</moduleName>
        <outputDir>${project.basedir}/target/documentation</outputDir>
        <failOnWarning>false</failOnWarning>
        <suppressObviousFunctions>true</suppressObviousFunctions>
        <suppressInheritedMembers>false</suppressInheritedMembers>
        <offlineMode>false</offlineMode>
        <sourceDirectories>
            <dir>${project.basedir}/src</dir>
        </sourceDirectories>
        <documentedVisibilities>
            <visibility>PUBLIC</visibility>
            <visibility>PRIVATE</visibility>
            <visibility>PROTECTED</visibility>
            <visibility>INTERNAL</visibility>
            <visibility>PACKAGE</visibility>
        </documentedVisibilities>
        <reportUndocumented>false</reportUndocumented>
        <skipDeprecated>false</skipDeprecated>
        <skipEmptyPackages>true</skipEmptyPackages>
        <suppressedFiles>
            <file>/path/to/dir</file>
            <file>/path/to/file</file>
        </suppressedFiles>
        <jdkVersion>8</jdkVersion>
        <languageVersion>1.7</languageVersion>
        <apiVersion>1.7</apiVersion>
        <noStdlibLink>false</noStdlibLink>
        <noJdkLink>false</noJdkLink>
        <includes>
            <include>packages.md</include>
            <include>extra.md</include>
        </includes>
        <classpath>${project.compileClasspathElements}</classpath>
        <samples>
            <dir>${project.basedir}/samples</dir>
        </samples>
        <sourceLinks>
            <link>
                <path>src</path>
                <url>https://github.com/kotlin/dokka/tree/master/src</url>
                <lineSuffix>#L</lineSuffix>
            </link>
        </sourceLinks>
        <externalDocumentationLinks>
            <link>
                <url>https://kotlinlang.org/api/core/kotlin-stdlib/</url>
                <packageListUrl>file:/${project.basedir}/stdlib.package.list</packageListUrl>
            </link>
        </externalDocumentationLinks>
        <perPackageOptions>
            <packageOptions>
                <matchingRegex>.*api.*</matchingRegex>
                <suppress>false</suppress>
                <reportUndocumented>false</reportUndocumented>
                <skipDeprecated>false</skipDeprecated>
                <documentedVisibilities>
                    <visibility>PUBLIC</visibility>
                    <visibility>PRIVATE</visibility>
                    <visibility>PROTECTED</visibility>
                    <visibility>INTERNAL</visibility>
                    <visibility>PACKAGE</visibility>
                </documentedVisibilities>
            </packageOptions>
        </perPackageOptions>
    </configuration>
</plugin>

基本类型

構建器

Spring

使用 Spring Boot 建立 RESTful Web 服務和資料庫

Java 到 Kotlin 遷移指南

C 互操作

Objective-C 互操作

內存管理器

參考與技巧

適用於 JS 平台的 Kotlin

Gradle

執行 Dokka

輸出格式

Maven

應用 Dokka

生成文件

實驗性

其他輸出格式

建構 javadoc.jar

配置範例

配置選項

一般配置

原始碼連結配置

外部文件連結配置

套件選項

完整配置

使用 Spring Boot 建立 RESTful Web 服務和資料庫

Maven ​

應用 Dokka ​

生成文件 ​

實驗性 ​

其他輸出格式 ​

建構 javadoc.jar ​

配置範例 ​

配置選項 ​

一般配置 ​

原始碼連結配置 ​

外部文件連結配置 ​

套件選項 ​

完整配置 ​

Maven

應用 Dokka

生成文件

實驗性

其他輸出格式

建構 javadoc.jar

配置範例

配置選項

一般配置

原始碼連結配置

外部文件連結配置

套件選項

完整配置