Gradle

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

このプラグインにはプロジェクトの基本的な自動設定が付属しており、ドキュメント生成のための便利なGradleタスクがあり、出力をカスタマイズするための豊富な設定オプションが提供されています。

当社のGradleサンプルプロジェクトにアクセスすると、Dokkaを試してさまざまなプロジェクトでどのように設定できるかを確認できます。

Dokkaの適用

Dokka用Gradleプラグインを適用する推奨される方法は、plugins DSLを使用することです。

KotlinGroovy

kotlin

plugins {
    id("org.jetbrains.dokka") version "2.0.0"
}

groovy

plugins {
    id 'org.jetbrains.dokka' version '2.0.0'
}

マルチプロジェクトビルドをドキュメント化する場合、サブプロジェクト内でもDokka用Gradleプラグインを適用する必要があります。そのためには、allprojects {}またはsubprojects {}のGradle設定を使用できます。

Gradle Kotlin DSLGradle Groovy DSL

kotlin

subprojects {
    apply(plugin = "org.jetbrains.dokka")
}

groovy

subprojects {
    apply plugin: 'org.jetbrains.dokka'
}

Dokkaをどこに適用すればよいか不明な場合は、設定例を参照してください。

内部では、DokkaはKotlin Gradleプラグインを使用して、ドキュメントを生成するソースセットの自動設定を実行します。Kotlin Gradleプラグインを適用するか、ソースセットを手動で設定してください。

Dokkaをプリコンパイルされたスクリプトプラグインで使用している場合、適切に動作させるためにはKotlin Gradleプラグインを依存関係として追加する必要があります。

何らかの理由でplugins DSLを使用できない場合は、プラグインを適用する従来の（レガシーな）方法を使用できます。

ドキュメントの生成

Dokka用Gradleプラグインには、HTML、Markdown、Javadocの出力フォーマットが組み込まれています。これにより、シングルプロジェクトおよびマルチプロジェクトビルドの両方のドキュメントを生成するための多数のタスクが追加されます。

シングルプロジェクトビルド

シンプルでシングルプロジェクトのアプリケーションやライブラリのドキュメントをビルドするには、以下のタスクを使用します。

タスク	説明
`dokkaHtml`	HTML形式でドキュメントを生成します。

実験的フォーマット

タスク	説明
`dokkaGfm`	GitHub Flavored Markdown形式でドキュメントを生成します。
`dokkaJavadoc`	Javadoc形式でドキュメントを生成します。
`dokkaJekyll`	Jekyll互換Markdown形式でドキュメントを生成します。

デフォルトでは、生成されたドキュメントはプロジェクトのbuild/dokka/{format}ディレクトリにあります。出力場所は、他にも設定できます。

マルチプロジェクトビルド

マルチプロジェクトビルドのドキュメント化では、ドキュメントを生成したいサブプロジェクト内、およびその親プロジェクトでもDokka用Gradleプラグインを適用していることを確認してください。

MultiModuleタスク

MultiModuleタスクは、Partialタスクを介して各サブプロジェクトのドキュメントを個別に生成し、すべての出力を収集して処理し、共通の目次と解決済みのプロジェクト間参照を含む完全なドキュメントを生成します。

Dokkaは、親プロジェクト用に以下のタスクを自動的に作成します。

タスク	説明
`dokkaHtmlMultiModule`	HTML出力形式でマルチモジュールドキュメントを生成します。

実験的フォーマット（マルチモジュール）

タスク	説明
`dokkaGfmMultiModule`	GitHub Flavored Markdown出力形式でマルチモジュールドキュメントを生成します。
`dokkaJekyllMultiModule`	Jekyll互換Markdown出力形式でマルチモジュールドキュメントを生成します。

Javadoc出力フォーマットにはMultiModuleタスクがありませんが、代わりにCollectorタスクを使用できます。

デフォルトでは、すぐに使用できるドキュメントは{parentProject}/build/dokka/{format}MultiModuleディレクトリの下にあります。

MultiModuleの成果物

次の構造を持つプロジェクトが与えられた場合：

text

.
└── parentProject/
    ├── childProjectA/
    │   └── demo/
    │       └── ChildProjectAClass
    └── childProjectB/
        └── demo/
            └── ChildProjectBClass

dokkaHtmlMultiModuleを実行すると、これらのページが生成されます。

Screenshot for output of dokkaHtmlMultiModule task

詳細については、マルチモジュールプロジェクトの例を参照してください。

Collectorタスク

MultiModuleタスクと同様に、各親プロジェクトに対してCollectorタスク（dokkaHtmlCollector、dokkaGfmCollector、dokkaJavadocCollector、dokkaJekyllCollector）が作成されます。

Collectorタスクは、各サブプロジェクトの対応するシングルプロジェクトタスク（例：dokkaHtml）を実行し、すべての出力を単一の仮想プロジェクトに結合します。

結果として得られるドキュメントは、すべてのサブプロジェクトからの宣言を含む単一プロジェクトビルドであるかのように見えます。

マルチプロジェクトビルドのJavadocドキュメントを作成する必要がある場合は、dokkaJavadocCollectorタスクを使用してください。

Collectorの成果物

次の構造を持つプロジェクトが与えられた場合：

text

.
└── parentProject/
    ├── childProjectA/
    │   └── demo/
    │       └── ChildProjectAClass
    └── childProjectB/
        └── demo/
            └── ChildProjectBClass

dokkaHtmlCollectorを実行すると、これらのページが生成されます。

Screenshot for output of dokkaHtmlCollector task

詳細については、マルチモジュールプロジェクトの例を参照してください。

Partialタスク

各サブプロジェクトに対して、Partialタスク（dokkaHtmlPartial、dokkaGfmPartial、dokkaJekyllPartial）が作成されます。

これらのタスクは単独で実行されることを意図しておらず、親のMultiModuleタスクによって呼び出されます。

ただし、サブプロジェクトのDokkaをカスタマイズするためにPartialタスクを設定できます。

Partialタスクによって生成された出力には、未解決のHTMLテンプレートと参照が含まれているため、親のMultiModuleタスクによる後処理なしでは単独で使用できません。

単一のサブプロジェクトのみのドキュメントを生成したい場合は、シングルプロジェクトタスクを使用してください（例：:subprojectName:dokkaHtml）。

javadoc.jarのビルド

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

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

Dokka用Gradleプラグインは、このための標準的な方法を提供していませんが、カスタムGradleタスクで実現できます。HTML形式でドキュメントを生成するためのタスクと、Javadoc形式でドキュメントを生成するためのタスクの2つです。

KotlinGroovy

kotlin

tasks.register<Jar>("dokkaHtmlJar") {
    dependsOn(tasks.dokkaHtml)
    from(tasks.dokkaHtml.flatMap { it.outputDirectory })
    archiveClassifier.set("html-docs")
}

tasks.register<Jar>("dokkaJavadocJar") {
    dependsOn(tasks.dokkaJavadoc)
    from(tasks.dokkaJavadoc.flatMap { it.outputDirectory })
    archiveClassifier.set("javadoc")
}

groovy

tasks.register('dokkaHtmlJar', Jar.class) {
    dependsOn(dokkaHtml)
    from(dokkaHtml)
    archiveClassifier.set("html-docs")
}

tasks.register('dokkaJavadocJar', Jar.class) {
    dependsOn(dokkaJavadoc)
    from(dokkaJavadoc)
    archiveClassifier.set("javadoc")
}

ライブラリをMaven Centralに公開する場合、javadoc.ioのようなサービスを利用して、無料でセットアップなしでライブラリのAPIドキュメントをホストできます。このサービスはjavadoc.jarから直接ドキュメントページを取得します。これは、この例で示されているように、HTML形式とうまく連携します。

設定例

お持ちのプロジェクトの種類によって、Dokkaの適用方法や設定方法はわずかに異なります。ただし、設定オプション自体は、プロジェクトの種類に関係なく同じです。

プロジェクトのルートに単一のbuild.gradle.ktsまたはbuild.gradleファイルがあるシンプルでフラットなプロジェクトについては、シングルプロジェクト設定を参照してください。

サブプロジェクトと複数のネストされたbuild.gradle.ktsまたはbuild.gradleファイルを持つより複雑なビルドについては、マルチプロジェクト設定を参照してください。

シングルプロジェクト設定

シングルプロジェクトビルドは通常、プロジェクトのルートに1つのbuild.gradle.ktsまたはbuild.gradleファイルしかなく、典型的に以下の構造を持っています。

KotlinGroovy

シングルプラットフォーム:

text

.
├── build.gradle.kts
└── src/
    └── main/
        └── kotlin/
            └── HelloWorld.kt

マルチプラットフォーム:

text

.
├── build.gradle.kts
└── src/
    ├── commonMain/
    │   └── kotlin/
    │       └── Common.kt
    ├── jvmMain/
    │   └── kotlin/
    │       └── JvmUtils.kt
    └── nativeMain/
        └── kotlin/
            └── NativeUtils.kt

シングルプラットフォーム:

text

.
├── build.gradle
└── src/
    └── main/
        └── kotlin/
            └── HelloWorld.kt

マルチプラットフォーム:

text

.
├── build.gradle
└── src/
    ├── commonMain/
    │   └── kotlin/
    │       └── Common.kt
    ├── jvmMain/
    │   └── kotlin/
    │       └── JvmUtils.kt
    └── nativeMain/
        └── kotlin/
            └── NativeUtils.kt

このようなプロジェクトでは、ルートのbuild.gradle.ktsまたはbuild.gradleファイルでDokkaとその設定を適用する必要があります。

タスクと出力フォーマットは個別に設定できます。

KotlinGroovy

./build.gradle.kts内:

kotlin

plugins {
    id("org.jetbrains.dokka") version "2.0.0"
}

tasks.dokkaHtml {
    outputDirectory.set(layout.buildDirectory.dir("documentation/html"))
}

tasks.dokkaGfm {
    outputDirectory.set(layout.buildDirectory.dir("documentation/markdown"))
}

./build.gradle内:

groovy

plugins {
    id 'org.jetbrains.dokka' version '2.0.0'
}

dokkaHtml {
    outputDirectory.set(file("build/documentation/html"))
}

dokkaGfm {
    outputDirectory.set(file("build/documentation/markdown"))
}

または、すべてのタスクと出力フォーマットを同時に設定することもできます。

KotlinGroovy

./build.gradle.kts内:

kotlin

import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.gradle.DokkaTaskPartial
import org.jetbrains.dokka.DokkaConfiguration.Visibility

plugins {
    id("org.jetbrains.dokka") version "2.0.0"
}

// Configure all single-project Dokka tasks at the same time,
// such as dokkaHtml, dokkaJavadoc and dokkaGfm.
// dokkaHtml、dokkaJavadoc、dokkaGfmなど、
// すべてのシングルプロジェクトDokkaタスクを同時に設定します。
tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets.configureEach {
        documentedVisibilities.set(
            setOf(
                Visibility.PUBLIC,
                Visibility.PROTECTED,
            )
        )

        perPackageOption {
            matchingRegex.set(".*internal.*")
            suppress.set(true)
        }
    }
}

./build.gradle内:

groovy

import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.gradle.DokkaTaskPartial
import org.jetbrains.dokka.DokkaConfiguration.Visibility

plugins {
    id 'org.jetbrains.dokka' version '2.0.0'
}

// Configure all single-project Dokka tasks at the same time,
// such as dokkaHtml, dokkaJavadoc and dokkaGfm.
// dokkaHtml、dokkaJavadoc、dokkaGfmなど、
// すべてのシングルプロジェクトDokkaタスクを同時に設定します。
tasks.withType(DokkaTask.class) {
    dokkaSourceSets.configureEach {
        documentedVisibilities.set([
                Visibility.PUBLIC,
                Visibility.PROTECTED
        ])

        perPackageOption {
            matchingRegex.set(".*internal.*")
            suppress.set(true)
        }
    }
}

マルチプロジェクト設定

Gradleのマルチプロジェクトビルドは、構造と設定がより複雑です。通常、複数のネストされたbuild.gradle.ktsまたはbuild.gradleファイルを持ち、典型的に以下の構造を持っています。

KotlinGroovy

text

.
├── build.gradle.kts
├── settings.gradle.kts
├── subproject-A/
│   ├── build.gradle.kts
│   └── src/
│       └── main/
│           └── kotlin/
│               └── HelloFromA.kt
└── subproject-B/
    ├── build.gradle.kts
    └── src/
        └── main/
            └── kotlin/
                └── HelloFromB.kt

text

.
├── build.gradle
├── settings.gradle
├── subproject-A/
│   ├── build.gradle
│   └── src/
│       └── main/
│           └── kotlin/
│               └── HelloFromA.kt
└── subproject-B/
    ├── build.gradle
    └── src/
        └── main/
            └── kotlin/
                └── HelloFromB.kt

この場合、Dokkaの適用と設定には複数の方法があります。

サブプロジェクト設定

マルチプロジェクトビルドでサブプロジェクトを設定するには、Partialタスクを設定する必要があります。

ルートのbuild.gradle.ktsまたはbuild.gradleファイルで、Gradleのallprojects {}またはsubprojects {}設定ブロックを使用して、すべてのサブプロジェクトを同時に設定できます。

KotlinGroovy

ルートの./build.gradle.kts内:

kotlin

import org.jetbrains.dokka.gradle.DokkaTaskPartial

plugins {
    id("org.jetbrains.dokka") version "2.0.0"
}

subprojects {
    apply(plugin = "org.jetbrains.dokka")

    // configure only the HTML task
    // HTMLタスクのみを設定
    tasks.dokkaHtmlPartial {
        outputDirectory.set(layout.buildDirectory.dir("docs/partial"))
    }

    // configure all format tasks at once
    // すべてのフォーマットタスクを一度に設定
    tasks.withType<DokkaTaskPartial>().configureEach {
        dokkaSourceSets.configureEach {
            includes.from("README.md")
        }
    }
}

ルートの./build.gradle内:

groovy

import org.jetbrains.dokka.gradle.DokkaTaskPartial

plugins {
    id 'org.jetbrains.dokka' version '2.0.0'
}

subprojects {
    apply plugin: 'org.jetbrains.dokka'

    // configure only the HTML task
    // HTMLタスクのみを設定
    dokkaHtmlPartial {
        outputDirectory.set(file("build/docs/partial"))
    }

    // configure all format tasks at once
    // すべてのフォーマットタスクを一度に設定
    tasks.withType(DokkaTaskPartial.class) {
        dokkaSourceSets.configureEach {
            includes.from("README.md")
        }
    }
}

または、サブプロジェクト内で個別にDokkaを適用および設定することもできます。

例えば、subproject-Aサブプロジェクトのみに特定の設定を適用するには、./subproject-A/build.gradle.kts内に以下のコードを適用する必要があります。

KotlinGroovy

./subproject-A/build.gradle.kts内:

kotlin

apply(plugin = "org.jetbrains.dokka")

// configuration for subproject-A only.
// subproject-Aのみの設定。
tasks.dokkaHtmlPartial {
    outputDirectory.set(layout.buildDirectory.dir("docs/partial"))
}

./subproject-A/build.gradle内:

groovy

apply plugin: 'org.jetbrains.dokka'

// configuration for subproject-A only.
// subproject-Aのみの設定。
dokkaHtmlPartial {
    outputDirectory.set(file("build/docs/partial"))
}

親プロジェクト設定

すべてのドキュメントにわたって普遍的であり、サブプロジェクトに属さないものを設定したい場合、つまり親プロジェクトのプロパティである場合は、MultiModuleタスクを設定する必要があります。

例えば、HTMLドキュメントのヘッダーで使用されるプロジェクトの名前を変更したい場合は、ルートのbuild.gradle.ktsまたはbuild.gradleファイル内に以下を適用する必要があります。

KotlinGroovy

ルートの./build.gradle.ktsファイル内:

kotlin

plugins {
    id("org.jetbrains.dokka") version "2.0.0"
}

tasks.dokkaHtmlMultiModule {
    moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER")
}

ルートの./build.gradleファイル内:

groovy

plugins {
    id 'org.jetbrains.dokka' version '2.0.0'
}

dokkaHtmlMultiModule {
    moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER")
}

設定オプション

Dokkaには、あなたと読者の体験をカスタマイズするための多くの設定オプションがあります。

以下に、各設定セクションの例と詳細な説明を示します。ページの下部には、すべての設定オプションが適用された例も記載されています。

設定ブロックをどこに、どのように適用するかについては、設定例を参照してください。

一般的な設定

ソースセットやパッケージに関係なく、任意のDokkaタスクの一般的な設定例を以下に示します。

KotlinGroovy

kotlin

import org.jetbrains.dokka.gradle.DokkaTask

// Note: To configure multi-project builds, you need
//       to configure Partial tasks of the subprojects.
//       See "Configuration example" section of documentation.
// 注: マルチプロジェクトビルドを設定するには、
//     サブプロジェクトのPartialタスクを設定する必要があります。
//     ドキュメントの「設定例」セクションを参照してください。
tasks.withType<DokkaTask>().configureEach {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(layout.buildDirectory.dir("dokka/$name"))
    failOnWarning.set(false)
    suppressObviousFunctions.set(true)
    suppressInheritedMembers.set(false)
    offlineMode.set(false)

    // ..
    // source set configuration section
    // ソースセット設定セクション
    // ..
}

groovy

import org.jetbrains.dokka.gradle.DokkaTask

// Note: To configure multi-project builds, you need
//       to configure Partial tasks of the subprojects.
//       See "Configuration example" section of documentation.
// 注: マルチプロジェクトビルドを設定するには、
//     サブプロジェクトのPartialタスクを設定する必要があります。
//     ドキュメントの「設定例」セクションを参照してください。
tasks.withType(DokkaTask.class) {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(file("build/dokka/$name"))
    failOnWarning.set(false)
    suppressObviousFunctions.set(true)
    suppressInheritedMembers.set(false)
    offlineMode.set(false)

    // ..
    // source set configuration section
    // ソースセット設定セクション
    // ..
}

moduleName

モジュールを参照するために使用される表示名です。目次、ナビゲーション、ロギングなどに使用されます。

シングルプロジェクトビルドまたはMultiModuleタスクに設定されている場合、プロジェクト名として使用されます。

デフォルト: Gradleプロジェクト名

moduleVersion

モジュールのバージョンです。シングルプロジェクトビルドまたはMultiModuleタスクに設定されている場合、プロジェクトバージョンとして使用されます。

デフォルト: Gradleプロジェクトバージョン

outputDirectory

ドキュメントが生成されるディレクトリです。フォーマットに関係なく、タスクごとに設定できます。

デフォルトは{project}/{buildDir}/{format}です。ここで{format}はタスク名から "dokka"プレフィックスを削除したものです。dokkaHtmlMultiModuleタスクの場合は、 project/buildDir/htmlMultiModuleとなります。

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

ソースセット設定

DokkaはKotlinソースセットのいくつかのオプションを設定できます。

KotlinGroovy

kotlin

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.Platform
import java.net.URL

// Note: To configure multi-project builds, you need
//       to configure Partial tasks of the subprojects.
//       See "Configuration example" section of documentation.
// 注: マルチプロジェクトビルドを設定するには、
//     サブプロジェクトのPartialタスクを設定する必要があります。
//     ドキュメントの「設定例」セクションを参照してください。
tasks.withType<DokkaTask>().configureEach {
    // ..
    // general configuration section
    // 一般的な設定セクション
    // ..

    dokkaSourceSets {
        // configuration exclusive to the 'linux' source set
        // 'linux'ソースセットに限定された設定
        named("linux") {
            dependsOn("native")
            sourceRoots.from(file("linux/src"))
        }
        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(Visibility.PUBLIC))
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            noStdlibLink.set(false)
            noJdkLink.set(false)
            noAndroidSdkLink.set(false)
            includes.from(project.files(), "packages.md", "extra.md")
            platform.set(Platform.DEFAULT)
            sourceRoots.from(file("src"))
            classpath.from(project.files(), file("libs/dependency.jar"))
            samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                // Source link section
                // ソースリンクセクション
            }
            externalDocumentationLink {
                // External documentation link section
                // 外部ドキュメントリンクセクション
            }
            perPackageOption {
                // Package options section
                // パッケージオプションセクション
            }
        }
    }
}

groovy

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.Platform
import java.net.URL

// Note: To configure multi-project builds, you need
//       to configure Partial tasks of the subprojects.
//       See "Configuration example" section of documentation.
// 注: マルチプロジェクトビルドを設定するには、
//     サブプロジェクトのPartialタスクを設定する必要があります。
//     ドキュメントの「設定例」セクションを参照してください。
tasks.withType(DokkaTask.class) {
    // ..
    // general configuration section
    // 一般的な設定セクション
    // ..

    dokkaSourceSets {
        // configuration exclusive to the 'linux' source set
        // 'linux'ソースセットに限定された設定
        named("linux") {
            dependsOn("native")
            sourceRoots.from(file("linux/src"))
        }
        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([Visibility.PUBLIC])
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            noStdlibLink.set(false)
            noJdkLink.set(false)
            noAndroidSdkLink.set(false)
            includes.from(project.files(), "packages.md", "extra.md")
            platform.set(Platform.DEFAULT)
            sourceRoots.from(file("src"))
            classpath.from(project.files(), file("libs/dependency.jar"))
            samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                // Source link section
                // ソースリンクセクション
            }
            externalDocumentationLink {
                // External documentation link section
                // 外部ドキュメントリンクセクション
            }
            perPackageOption {
                // Package options section
                // パッケージオプションセクション
            }
        }
    }
}

suppress

ドキュメント生成時にこのソースセットをスキップするかどうかです。

デフォルト: false

displayName

このソースセットを参照するために使用される表示名です。

名前は、外部（例えば、ドキュメントリーダーに見えるソースセット名）と内部（例えば、reportUndocumentedのロギングメッセージ）の両方で使用されます。

デフォルトでは、値はKotlin Gradleプラグインによって提供される情報から推測されます。

documentedVisibilities

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

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

これはパッケージごとに設定できます。

デフォルト: DokkaConfiguration.Visibility.PUBLIC

reportUndocumented

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

この設定はfailOnWarningと連携してうまく機能します。

これはパッケージごとに設定できます。

デフォルト: false

skipEmptyPackages

様々なフィルターが適用された後、可視な宣言を何も含まないパッケージをスキップするかどうかです。

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

デフォルト: true

skipDeprecated

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

これはパッケージごとに設定できます。

デフォルト: false

suppressGeneratedFiles

生成されたファイルをドキュメント化/分析するかどうかです。

生成されたファイルは{project}/{buildDir}/generatedディレクトリの下に存在すると想定されています。

これをtrueに設定すると、そのディレクトリ内のすべてのファイルが実質的に suppressedFilesオプションに追加されるため、手動で設定することも可能です。

デフォルト: true

jdkVersion

Java型用の外部ドキュメントリンクを生成する際に使用するJDKバージョンです。

例えば、何らかの公開宣言シグネチャで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

noAndroidSdkLink

Android SDK APIリファレンスへの外部ドキュメントリンクを生成するかどうかです。

これはAndroidプロジェクトでのみ関連性があり、それ以外の場合は無視されます。

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

デフォルト: false

includes

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

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

使用例については、Dokka gradleの例を参照してください。

platform

コード分析および@sample環境のセットアップに使用するプラットフォームです。

デフォルト値はKotlin Gradleプラグインによって提供される情報から推測されます。

sourceRoots

分析およびドキュメント化されるソースコードのルートです。許容される入力はディレクトリおよび個々の.kt / .javaファイルです。

デフォルトでは、ソースルートはKotlin Gradleプラグインによって提供される情報から推測されます。

classpath

分析およびインタラクティブなサンプル用のクラスパスです。

これは、依存関係から来るいくつかの型が自動的に解決/認識されない場合に便利です。

このオプションは.jarと.klibファイルの両方を受け入れます。

デフォルトでは、クラスパスはKotlin Gradleプラグインによって提供される情報から推測されます。

samples

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

ソースリンク設定

sourceLinks設定ブロックを使用すると、特定の行番号（行番号はremoteLineSuffixを設定することで構成可能）を持つremoteUrlに繋がるsourceリンクを各シグネチャに追加できます。

これにより、読者は各宣言のソースコードを見つけることができます。

例については、kotlinx.coroutinesのcount()関数のドキュメントを参照してください。

KotlinGroovy

kotlin

import org.jetbrains.dokka.gradle.DokkaTask
import java.net.URL

// Note: To configure multi-project builds, you need
//       to configure Partial tasks of the subprojects.
//       See "Configuration example" section of documentation.
// 注: マルチプロジェクトビルドを設定するには、
//     サブプロジェクトのPartialタスクを設定する必要があります。
//     ドキュメントの「設定例」セクションを参照してください。
tasks.withType<DokkaTask>().configureEach {
    // ..
    // general configuration section
    // 一般的な設定セクション
    // ..

    dokkaSourceSets.configureEach {
        // ..
        // source set configuration section
        // ソースセット設定セクション
        // ..

        sourceLink {
            localDirectory.set(projectDir.resolve("src"))
            remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src"))
            remoteLineSuffix.set("#L")
        }
    }
}

groovy

import org.jetbrains.dokka.gradle.DokkaTask
import java.net.URL

// Note: To configure multi-project builds, you need
//       to configure Partial tasks of the subprojects.
//       See "Configuration example" section of documentation.
// 注: マルチプロジェクトビルドを設定するには、
//     サブプロジェクトのPartialタスクを設定する必要があります。
//     ドキュメントの「設定例」セクションを参照してください。
tasks.withType(DokkaTask.class) {
    // ..
    // general configuration section
    // 一般的な設定セクション
    // ..

    dokkaSourceSets.configureEach {
        // ..
        // source set configuration section
        // ソースセット設定セクション
        // ..

        sourceLink {
            localDirectory.set(file("src"))
            remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src"))
            remoteLineSuffix.set("#L")
        }
    }
}

localDirectory

ローカルのソースディレクトリへのパスです。パスは現在のプロジェクトのルートからの相対パスでなければなりません。

remoteUrl

GitHub、GitLab、Bitbucketなど、ドキュメントリーダーがアクセスできるソースコードホスティングサービスのURLです。このURLは宣言のソースコードリンクを生成するために使用されます。

remoteLineSuffix

URLにソースコードの行番号を追加するために使用されるサフィックスです。これにより、読者はファイルだけでなく、宣言の特定の行番号に移動できるようになります。

番号自体は指定されたサフィックスに追加されます。例えば、このオプションが#Lに設定され、行番号が10の場合、結果のURLサフィックスは#L10となります。

一般的なサービスで使用されるサフィックス:

GitHub: #L
GitLab: #L
Bitbucket: #lines-

デフォルト: #L

パッケージオプション

perPackageOption設定ブロックは、matchingRegexによってマッチする特定のパッケージに対していくつかのオプションを設定することを可能にします。

KotlinGroovy

kotlin

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask

// Note: To configure multi-project builds, you need
//       to configure Partial tasks of the subprojects.
//       See "Configuration example" section of documentation.
// 注: マルチプロジェクトビルドを設定するには、
//     サブプロジェクトのPartialタスクを設定する必要があります。
//     ドキュメントの「設定例」セクションを参照してください。
tasks.withType<DokkaTask>().configureEach {
    // ..
    // general configuration section
    // 一般的な設定セクション
    // ..

    dokkaSourceSets.configureEach {
        // ..
        // source set configuration section
        // ソースセット設定セクション
        // ..

        perPackageOption {
            matchingRegex.set(".*api.*")
            suppress.set(false)
            skipDeprecated.set(false)
            reportUndocumented.set(false)
            documentedVisibilities.set(setOf(Visibility.PUBLIC))
        }
    }
}

groovy

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask

// Note: To configure multi-project builds, you need
//       to configure Partial tasks of the subprojects.
//       See "Configuration example" section of documentation.
// 注: マルチプロジェクトビルドを設定するには、
//     サブプロジェクトのPartialタスクを設定する必要があります。
//     ドキュメントの「設定例」セクションを参照してください。
tasks.withType(DokkaTask.class) {
    // ..
    // general configuration section
    // 一般的な設定セクション
    // ..

    dokkaSourceSets.configureEach {
        // ..
        // Source set configuration section
        // ソースセット設定セクション
        // ..

        perPackageOption {
            matchingRegex.set(".*api.*")
            suppress.set(false)
            skipDeprecated.set(false)
            reportUndocumented.set(false)
            documentedVisibilities.set([Visibility.PUBLIC])
        }
    }
}

matchingRegex

パッケージをマッチさせるために使用される正規表現です。

デフォルト: .*

suppress

ドキュメント生成時にこのパッケージをスキップするかどうかです。

デフォルト: false

skipDeprecated

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

これはソースセットレベルで設定できます。

デフォルト: false

reportUndocumented

この設定はfailOnWarningと連携してうまく機能します。

これはソースセットレベルで設定できます。

デフォルト: false

documentedVisibilities

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

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

これはソースセットレベルで設定できます。

デフォルト: DokkaConfiguration.Visibility.PUBLIC

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

externalDocumentationLinkブロックを使用すると、依存関係の外部ホストされているドキュメントに繋がるリンクを作成できます。

例えば、kotlinx.serializationの型を使用している場合、デフォルトではドキュメント内でクリックできず、未解決であるかのように表示されます。しかし、kotlinx.serializationのAPIリファレンスドキュメントはDokkaによって構築され、kotlinlang.orgで公開されているため、それに対する外部ドキュメントリンクを設定できます。これにより、Dokkaはライブラリからの型のリンクを生成し、それらを正常に解決してクリック可能にします。

デフォルトでは、Kotlin標準ライブラリ、JDK、Android SDK、AndroidXの外部ドキュメントリンクが設定されています。

KotlinGroovy

kotlin

import org.jetbrains.dokka.gradle.DokkaTask
import java.net.URL

// Note: To configure multi-project builds, you need
//       to configure Partial tasks of the subprojects.
//       See "Configuration example" section of documentation.
// 注: マルチプロジェクトビルドを設定するには、
//     サブプロジェクトのPartialタスクを設定する必要があります。
//     ドキュメントの「設定例」セクションを参照してください。
tasks.withType<DokkaTask>().configureEach {
    // ..
    // general configuration section
    // 一般的な設定セクション
    // ..

    dokkaSourceSets.configureEach {
        // ..
        // source set configuration section
        // ソースセット設定セクション
        // ..

        externalDocumentationLink {
            url.set(URL("https://kotlinlang.org/api/kotlinx.serialization/"))
            packageListUrl.set(
                rootProject.projectDir.resolve("serialization.package.list").toURL()
            )
        }
    }
}

groovy

import org.jetbrains.dokka.gradle.DokkaTask
import java.net.URL

// Note: To configure multi-project builds, you need
//       to configure Partial tasks of the subprojects.
//       See "Configuration example" section of documentation.
// 注: マルチプロジェクトビルドを設定するには、
//     サブプロジェクトのPartialタスクを設定する必要があります。
//     ドキュメントの「設定例」セクションを参照してください。
tasks.withType(DokkaTask.class) {
    // ..
    // general configuration section
    // 一般的な設定セクション
    // ..

    dokkaSourceSets.configureEach {
        // ..
        // source set configuration section
        // ソースセット設定セクション
        // ..

        externalDocumentationLink {
            url.set(new URL("https://kotlinlang.org/api/kotlinx.serialization/"))
            packageListUrl.set(
                file("serialization.package.list").toURL()
            )
        }
    }
}

url

リンク先のドキュメントのルートURLです。末尾にスラッシュが必要です。

Dokkaは、与えられたURLのpackage-listを自動的に見つけ、宣言をリンクするために最善を尽くします。

自動解決に失敗した場合、または代わりにローカルにキャッシュされたファイルを使用したい場合は、 packageListUrlオプションの設定を検討してください。

packageListUrl

package-listの正確な場所です。これはDokkaが自動的に解決することに頼る代替手段です。

パッケージリストには、モジュール名やパッケージ名など、ドキュメントとプロジェクト自体に関する情報が含まれています。

これは、ネットワーク呼び出しを避けるためのローカルキャッシュファイルでも構いません。

完全な設定

以下に、考えられるすべての設定オプションが同時に適用された例を示します。

KotlinGroovy

kotlin

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.Platform
import java.net.URL

// Note: To configure multi-project builds, you need
//       to configure Partial tasks of the subprojects.
//       See "Configuration example" section of documentation.
// 注: マルチプロジェクトビルドを設定するには、
//     サブプロジェクトのPartialタスクを設定する必要があります。
//     ドキュメントの「設定例」セクションを参照してください。
tasks.withType<DokkaTask>().configureEach {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(layout.buildDirectory.dir("dokka/$name"))
    failOnWarning.set(false)
    suppressObviousFunctions.set(true)
    suppressInheritedMembers.set(false)
    offlineMode.set(false)

    dokkaSourceSets {
        named("linux") {
            dependsOn("native")
            sourceRoots.from(file("linux/src"))
        }
        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(Visibility.PUBLIC))
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            noStdlibLink.set(false)
            noJdkLink.set(false)
            noAndroidSdkLink.set(false)
            includes.from(project.files(), "packages.md", "extra.md")
            platform.set(Platform.DEFAULT)
            sourceRoots.from(file("src"))
            classpath.from(project.files(), file("libs/dependency.jar"))
            samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(projectDir.resolve("src"))
                remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src"))
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLink {
                url.set(URL("https://kotlinlang.org/api/core/kotlin-stdlib/"))
                packageListUrl.set(
                    rootProject.projectDir.resolve("stdlib.package.list").toURL()
                )
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set(
                    setOf(
                        Visibility.PUBLIC,
                        Visibility.PRIVATE,
                        Visibility.PROTECTED,
                        Visibility.INTERNAL,
                        Visibility.PACKAGE
                    )
                )
            }
        }
    }
}

groovy

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.Platform
import java.net.URL

// Note: To configure multi-project builds, you need
//       to configure Partial tasks of the subprojects.
//       See "Configuration example" section of documentation.
// 注: マルチプロジェクトビルドを設定するには、
//     サブプロジェクトのPartialタスクを設定する必要があります。
//     ドキュメントの「設定例」セクションを参照してください。
tasks.withType(DokkaTask.class) {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(file("build/dokka/$name"))
    failOnWarning.set(false)
    suppressObviousFunctions.set(true)
    suppressInheritedMembers.set(false)
    offlineMode.set(false)

    dokkaSourceSets {
        named("linux") {
            dependsOn("native")
            sourceRoots.from(file("linux/src"))
        }
        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([Visibility.PUBLIC])
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            noStdlibLink.set(false)
            noJdkLink.set(false)
            noAndroidSdkLink.set(false)
            includes.from(project.files(), "packages.md", "extra.md")
            platform.set(Platform.DEFAULT)
            sourceRoots.from(file("src"))
            classpath.from(project.files(), file("libs/dependency.jar"))
            samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(file("src"))
                remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src"))
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLink {
                url.set(new URL("https://kotlinlang.org/api/core/kotlin-stdlib/"))
                packageListUrl.set(
                        file("stdlib.package.list").toURL()
                )
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set([Visibility.PUBLIC])
            }
        }
    }
}

概要

ビルダー

Spring

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

JavaからKotlinへの移行ガイド

C interop

Objective-C interop

メモリマネージャー

リファレンスとヒント

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

概要

Dokkaを実行する

出力形式

認知複雑度の最小化

Gradle

Dokkaの適用

ドキュメントの生成

シングルプロジェクトビルド

実験的フォーマット

マルチプロジェクトビルド

MultiModuleタスク

実験的フォーマット（マルチモジュール）

MultiModuleの成果物

Collectorタスク

Collectorの成果物

Partialタスク

javadoc.jarのビルド

設定例

シングルプロジェクト設定

マルチプロジェクト設定

サブプロジェクト設定

親プロジェクト設定

設定オプション

一般的な設定

ソースセット設定

ソースリンク設定

パッケージオプション

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

完全な設定

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

Gradle ​

Dokkaの適用 ​

ドキュメントの生成 ​

シングルプロジェクトビルド ​

実験的フォーマット ​

マルチプロジェクトビルド ​

MultiModuleタスク ​

実験的フォーマット（マルチモジュール） ​

MultiModuleの成果物 ​

Collectorタスク ​

Collectorの成果物 ​

Partialタスク ​

javadoc.jarのビルド ​

設定例 ​

シングルプロジェクト設定 ​

マルチプロジェクト設定 ​

サブプロジェクト設定 ​

親プロジェクト設定 ​

設定オプション ​

一般的な設定 ​

ソースセット設定 ​

ソースリンク設定 ​

パッケージオプション ​

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

完全な設定 ​

Gradle

Dokkaの適用

ドキュメントの生成

シングルプロジェクトビルド

実験的フォーマット

マルチプロジェクトビルド

MultiModuleタスク

実験的フォーマット（マルチモジュール）

MultiModuleの成果物

Collectorタスク

Collectorの成果物

Partialタスク

javadoc.jarのビルド

設定例

シングルプロジェクト設定

マルチプロジェクト設定

サブプロジェクト設定

親プロジェクト設定

設定オプション

一般的な設定

ソースセット設定

ソースリンク設定

パッケージオプション

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

完全な設定