Open AIDoc

日本語

简体中文
繁體中文
한국어

日本語

简体中文
繁體中文
한국어

Appearance

Maven ​

Mavenベースのプロジェクトのドキュメントを生成するには、Dokka用のMavenプラグインを使用できます。

Gradle用のDokkaプラグインと比較して、Mavenプラグインは基本的な機能のみを備えており、マルチモジュールビルドはサポートしていません。

Mavenサンプルプロジェクトを参照して、Dokkaの設定方法を試すことができます。

Dokkaの適用 ​

Dokkaを適用するには、POMファイルの plugins セクションに dokka-maven-plugin を追加する必要があります。

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

ドキュメントの生成 ​

Mavenプラグインでは、以下のゴール（goal）が提供されています。

ゴール説明
dokka:dokkaDokkaプラグインを適用してドキュメントを生成します。デフォルトは HTML 形式です。

実験的機能 ​

ゴール説明
dokka:javadocJavadoc 形式でドキュメントを生成します。
dokka:javadocJarJavadoc 形式のドキュメントを含む 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.1.0</version>
            </plugin>
        </dokkaPlugins>
    </configuration>
</plugin>

この設定で dokka:dokka ゴールを実行すると、GFM形式でドキュメントが生成されます。

Dokkaプラグインの詳細については、Dokkaプラグイン を参照してください。

javadoc.jar のビルド ​

ライブラリをリポジトリに公開する場合、ライブラリのAPIリファレンスドキュメントを含む javadoc.jar ファイルの提供が必要になることがあります。

例えば、Maven Central に公開する場合、プロジェクトと一緒に javadoc.jar を提供することが必須です。ただし、すべてのリポジトリにこのルールがあるわけではありません。

Gradle用のDokkaプラグインとは異なり、Mavenプラグインにはすぐに使用できる dokka:javadocJar ゴールが用意されています。デフォルトでは、target フォルダに Javadoc 出力形式でドキュメントが生成されます。

組み込みのゴールに満足できない場合や、出力をカスタマイズしたい場合（例えば、Javadocの代わりに HTML 形式でドキュメントを生成したい場合など）は、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>
        <suppressAnnotatedWith>
            <annotation>com.example.SuppressMe</annotation>
        </suppressAnnotatedWith>
        <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

自明な（obvious）関数を除外するかどうか。

以下の場合、関数は自明であると見なされます：

  • 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-lists が含まれます。 例えば、標準ライブラリのクラスをクリック可能にするために使用されます。

これを true に設定すると、特定の場合にビルド時間を大幅に短縮できますが、 ドキュメントの品質やユーザーエクスペリエンスが低下する可能性があります。例えば、 標準ライブラリを含む依存関係からのクラス/メンバーのリンクが解決されなくなります。

注意: 取得したファイルをローカルにキャッシュし、ローカルパスとしてDokkaに提供することができます。 externalDocumentationLinks セクションを参照してください。

デフォルト: false

sourceDirectories

解析およびドキュメント化されるソースコードのルート。 ディレクトリまたは個別の .kt / .java ファイルを指定できます。

デフォルト: {project.compileSourceRoots}

documentedVisibilities

ドキュメント化する可視性修飾子のセット。

protected/internal/private 宣言をドキュメント化したい場合や、 public 宣言を除外して内部APIのみをドキュメント化したい場合に使用できます。

パッケージごとに設定することも可能です。

デフォルト: PUBLIC

reportUndocumented

documentedVisibilities やその他のフィルタによってフィルタリングされた後、 KDocがない可視宣言（ドキュメント化されていない宣言）について警告を出すかどうか。

この設定は failOnWarning と組み合わせて使用すると効果的です。

これはパッケージレベルで上書きできます。

デフォルト: false

skipDeprecated

@Deprecated アノテーションが付いた宣言をドキュメント化するかどうか。

これはパッケージレベルで上書きできます。

デフォルト: false

skipEmptyPackages

さまざまなフィルタが適用された後、表示可能な宣言を含まないパッケージをスキップするかどうか。

例えば、skipDeprecated が true に設定されており、パッケージに非推奨の宣言しか含まれていない場合、そのパッケージは空であると見なされます。

デフォルト: true

suppressedFiles

除外（抑制）するディレクトリまたは個別のファイル。これらの宣言はドキュメント化されません。

suppressAnnotatedWith

指定されたアノテーションが付加された宣言を除外するための、アノテーション完全修飾名（FQN）のリスト。

これらのアノテーションのいずれかが付加された宣言は、生成されるドキュメントから除外されます。

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のJavadocへの外部リンクを生成するかどうか。

JDK Javadocsのバージョンは jdkVersion オプションによって決定されます。

注意: noJdkLink が false に設定されている場合、リンクは生成されます。

デフォルト: false

includes

モジュールおよびパッケージのドキュメント を含む Markdownファイルのリスト。

指定されたファイルの内容が解析され、モジュールおよびパッケージの説明としてドキュメントに埋め込まれます。

classpath

解析およびインタラクティブサンプルのためのクラスパス。

依存関係にある一部の型が自動的に解決/取得されない場合に便利です。 このオプションは .jar と .klib の両方のファイルを受け入れます。

デフォルト: {project.compileClasspathElements}

samples

@sample KDocタグ を介して参照されるサンプル関数を含むディレクトリまたはファイルのリスト。

ソースリンク設定 ​

sourceLinks 設定ブロックを使用すると、各シグネチャに特定の行番号を持つ url への source リンクを追加できます。（行番号は 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

GitHub、GitLab、Bitbucketなど、ドキュメントの読者がアクセスできるソースコードホスティングサービスのURL。この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

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>

Copyright © 2026 Open AIDoc.