Maven

要为基于 Maven 的项目生成文档，你可以使用 Dokka 的 Maven 插件。

与 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>

然后通过运行 dokka:dokka 和 jar:jar@dokka-jar 目标来生成文档及其 .jar 归档文件：

Bash

mvn dokka:dokka jar:jar@dokka-jar

如果你将你的库发布到 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>

跳过

是否跳过文档生成。

默认值：false

模块名称

用于指代项目/模块的显示名称。它用于目录、导航、日志记录等。

默认值：{project.artifactId}

输出目录

文档的生成目录，不分格式。

默认值：{project.basedir}/target/dokka

警告时失败

如果 Dokka 发出了警告或错误，是否使文档生成失败。此过程会先等待所有错误和警告都发出。

此设置与 reportUndocumented 配合良好。

默认值：false

抑制明显函数

是否抑制明显函数。

如果函数是以下情况，则被认为是明显的：

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

默认值：true

抑制继承成员

是否抑制在给定类中未显式覆盖的继承成员。

注意：这可以抑制 equals/hashCode/toString 等函数，但不能抑制 dataClass.componentN 和 dataClass.copy 等合成函数。为此请使用 suppressObviousFunctions。

默认值：false

离线模式

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

这包括用于生成外部文档链接的 package-list。例如，使标准库中的类可点击。

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

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

默认值：false

源代码目录

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

默认值：{project.compileSourceRoots}

文档化可见性

应文档化的可见性修饰符集。

如果你想文档化 protected/internal/private 声明，以及如果你想排除 public 声明并仅文档化内部 API，可以使用此选项。

可以按包进行配置。

默认值：PUBLIC

报告未文档化

是否发出关于可见的未文档化声明的警告，即经过 documentedVisibilities 和其他过滤器过滤后没有 KDocs 的声明。

此设置与 failOnWarning 配合良好。

这可以在包级别覆盖。

默认值：false

跳过已弃用

是否文档化使用 @Deprecated 注解的声明。

这可以在项目/模块级别覆盖。

默认值：false

跳过空包

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

例如，如果 skipDeprecated 设置为 true，并且你的包只包含已弃用的声明，则该包被视为空。

默认值：true

抑制文件

应抑制的目录或单个文件，这意味着来自这些文件的声明不会被文档化。

jdk版本

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

例如，如果你在某个 public 声明签名中使用 java.util.UUID，并且此选项设置为 8，Dokka 会为它生成一个外部文档链接到 JDK 8 Javadoc。

默认值：JDK 8

语言版本

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

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

API 版本

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

默认情况下，它从 languageVersion 推断。

无标准库链接

是否生成指向 Kotlin 标准库 API 参考文档的外部文档链接。

注意：当 noStdLibLink 设置为 false 时，链接会生成。

默认值：false

无 JDK 链接

是否生成指向 JDK Javadoc 的外部文档链接。

JDK Javadoc 的版本由 jdkVersion 选项决定。

注意：当 noJdkLink 设置为 false 时，链接会生成。

默认值：false

包含

包含模块和包文档的 Markdown 文件列表。

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

类路径

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

如果来自依赖项的某些类型未自动解析/识别，此选项会很有用。此选项接受 .jar 和 .klib 文件。

默认值：{project.compileClasspathElements}

示例

包含通过 @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>

路径

本地源代码目录的路径。路径必须是相对于当前模块根目录的相对路径。

注意：只允许基于 Unix 的路径，Windows 风格的路径将抛出错误。

网址

文档读者可以访问的源代码托管服务的 URL，例如 GitHub、GitLab、Bitbucket 等。此 URL 用于生成声明的源代码链接。

行号后缀

用于将源代码行号附加到 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。它必须包含尾部斜杠。

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

如果自动解析失败或者你想使用本地缓存的文件，请考虑设置 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>

匹配正则表达式

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

默认值：.*

抑制

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

默认值：false

文档化可见性

应文档化的可见性修饰符集。

如果你想文档化此包内的 protected/internal/private 声明，以及如果你想排除 public 声明并仅文档化内部 API，可以使用此选项。

默认值：PUBLIC

跳过已弃用

是否文档化使用 @Deprecated 注解的声明。

这可以在项目/模块级别设置。

默认值：false

报告未文档化

是否发出关于可见的未文档化声明的警告，即经过 documentedVisibilities 和其他过滤器过滤后没有 KDocs 的声明。

此设置与 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

概览

运行 Dokka

输出格式

最小化心智负担

Maven

应用 Dokka

生成文档

实验性的

其他输出格式

构建 javadoc.jar

配置示例

配置选项

通用配置

源链接配置

外部文档链接配置

包选项

完整配置

使用 Spring Boot 创建基于数据库的 RESTful Web 服务

Maven ​

应用 Dokka ​

生成文档 ​

实验性的 ​

其他输出格式 ​

构建 javadoc.jar ​

配置示例 ​

配置选项 ​

通用配置 ​

源链接配置 ​

外部文档链接配置 ​

包选项 ​

完整配置 ​

Maven

应用 Dokka

生成文档

实验性的

其他输出格式

构建 javadoc.jar

配置示例

配置选项

通用配置

源链接配置

外部文档链接配置

包选项

完整配置