Maven

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

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

Mavenの例プロジェクトにアクセスして、Dokkaを試したり、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です。

実験的機能 (Experimental)

ゴール	説明
`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

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

自明な関数を抑制するかどうか。

以下の関数は自明であるとみなされます。

equals、hashCode、toStringのように、 kotlin.Any、Kotlin.Enum、java.lang.Object、またはjava.lang.Enumから継承された関数。
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バージョン。

例えば、何らかのpublic宣言のシグネチャでjava.util.UUIDを使用しており、このオプションが8に設定されている場合、Dokkaはそれに対する JDK 8 Javadocへの外部ドキュメントリンクを生成します。

デフォルト: 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 interop

Objective-C interop

メモリマネージャー

リファレンスとヒント

JSプラットフォーム向けKotlin

概要

Dokkaを実行する

出力形式

認知複雑度の最小化

Maven

Dokkaの適用

ドキュメントの生成

実験的機能 (Experimental)

その他の出力フォーマット

javadoc.jarのビルド

設定例

設定オプション

一般的な設定

ソースリンクの設定

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

パッケージオプション

完全な設定

Spring Bootを使用してデータベースを持つRESTful Webサービスを作成する

Maven ​

Dokkaの適用 ​

ドキュメントの生成 ​

実験的機能 (Experimental) ​

その他の出力フォーマット ​

javadoc.jarのビルド ​

設定例 ​

設定オプション ​

一般的な設定 ​

ソースリンクの設定 ​

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

パッケージオプション ​

完全な設定 ​

Maven

Dokkaの適用

ドキュメントの生成

実験的機能 (Experimental)

その他の出力フォーマット

javadoc.jarのビルド

設定例

設定オプション

一般的な設定

ソースリンクの設定

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

パッケージオプション

完全な設定