Maven

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

NOTE

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

Dokkaを試してMavenプロジェクト向けにどのように設定できるかを確認するには、Mavenサンプルプロジェクトをご覧ください。

Dokkaを適用する

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

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出力形式でドキュメントを生成します。

組み込みゴールに満足しない場合や、出力をカスタマイズしたい場合（例えば、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>

ドキュメントとそれに対応する.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

ネットワーク経由でリモートファイル/リンクを解決するかどうか。

これには、外部ドキュメントリンクを生成するために使用されるパッケージリストが含まれます。例えば、標準ライブラリのクラスをクリック可能にするためです。

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

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

デフォルト: false

sourceDirectories

分析およびドキュメント化されるソースコードルート。ディレクトリと個々の.kt / .javaファイルが入力として受け入れられます。

デフォルト: {project.compileSourceRoots}

documentedVisibilities

ドキュメント化されるべき可視性修飾子のセットです。

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

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

デフォルト: PUBLIC

reportUndocumented

documentedVisibilitiesやその他のフィルターによってフィルタリングされた後、可視でKDocsのない宣言、つまり未ドキュメント化された宣言について警告を発するかどうか。

この設定は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のJavadocへの外部ドキュメントリンクを生成するかどうか。

JDK Javadocのバージョンは、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

この設定は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のビルド

設定例

設定オプション

一般設定

ソースリンク設定

外部ドキュメントリンク設定

パッケージオプション

完全な設定