Open AIDoc

日本語

简体中文
繁體中文
한국어

日本語

简体中文
繁體中文
한국어

Appearance

Gradle ​

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

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

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

Dokkaの適用 ​

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

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設定を使用できます。

kotlin
subprojects {
    apply(plugin = "org.jetbrains.dokka")
}
groovy
subprojects {
    apply plugin: 'org.jetbrains.dokka'
}

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

NOTE

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

NOTE

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

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

ドキュメントの生成 ​

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

単一プロジェクトビルド ​

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

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

実験的なフォーマット ​

タスク説明
dokkaGfmGitHub Flavored Markdown形式でドキュメントを生成します。
dokkaJavadocJavadoc形式でドキュメントを生成します。
dokkaJekyllJekyll互換Markdown形式でドキュメントを生成します。

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

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

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

MultiModuleタスク ​

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

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

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

実験的なフォーマット (マルチモジュール) ​

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

NOTE

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）を実行し、すべての出力を単一の仮想プロジェクトに結合します。

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

TIP

マルチプロジェクトビルド用の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タスクを設定できます。

DANGER

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

NOTE

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

javadoc.jarのビルド ​

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

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

Dokka用Gradleプラグインにはこのための既製の機能はありませんが、カスタムGradleタスクを使用して実現できます。HTML形式のドキュメントを生成するためのタスクと、Javadoc形式のドキュメントを生成するためのタスクです。

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")
}

TIP

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

設定例 ​

プロジェクトのタイプによって、Dokkaの適用方法と設定方法は若干異なります。ただし、設定オプション自体は、プロジェクトのタイプに関わらず同じです。

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

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

単一プロジェクト設定 ​

単一プロジェクトビルドでは通常、プロジェクトのルートにbuild.gradle.ktsまたはbuild.gradleファイルが1つだけあり、典型的に以下の構造を持っています。

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

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

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

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"))
}
groovy
plugins {
    id 'org.jetbrains.dokka' version '2.0.0'
}

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

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

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

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"
}

// dokkaHtml, dokkaJavadoc, dokkaGfmなど、すべての単一プロジェクトDokkaタスクを同時に設定します。
tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets.configureEach {
        documentedVisibilities.set(
            setOf(
                Visibility.PUBLIC,
                Visibility.PROTECTED,
            )
        )

        perPackageOption {
            matchingRegex.set(".*internal.*")
            suppress.set(true)
        }
    }
}
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'
}

// 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ファイルがあり、典型的に以下の構造を持っています。

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タスクを設定する必要があります。

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

kotlin
import org.jetbrains.dokka.gradle.DokkaTaskPartial

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

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

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

    // すべてのフォーマットタスクを一度に設定
    tasks.withType<DokkaTaskPartial>().configureEach {
        dokkaSourceSets.configureEach {
            includes.from("README.md")
        }
    }
}
groovy
import org.jetbrains.dokka.gradle.DokkaTaskPartial

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

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

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

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

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

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

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

// subproject-Aのみの設定
tasks.dokkaHtmlPartial {
    outputDirectory.set(layout.buildDirectory.dir("docs/partial"))
}
groovy
apply plugin: 'org.jetbrains.dokka'

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

親プロジェクト設定 ​

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

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

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

tasks.dokkaHtmlMultiModule {
    moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER")
}
groovy
plugins {
    id 'org.jetbrains.dokka' version '2.0.0'
}

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

設定オプション ​

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

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

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

一般設定 ​

ソースセットやパッケージに関わらず、あらゆるDokkaタスクの一般設定の例を以下に示します。

kotlin
import org.jetbrains.dokka.gradle.DokkaTask

// 注意: マルチプロジェクトビルドを設定するには、
// サブプロジェクトの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)
    
    // ..
    // ソースセット設定セクション
    // ..
}
groovy
import org.jetbrains.dokka.gradle.DokkaTask

// 注意: マルチプロジェクトビルドを設定するには、
// サブプロジェクトの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)

    // ..
    // ソースセット設定セクション
    // ..
}
moduleName

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

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

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

moduleVersion

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

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

outputDirectory

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

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

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

ソースセット設定 ​

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

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

// 注意: マルチプロジェクトビルドを設定するには、
// サブプロジェクトのPartialタスクを設定する必要があります。
// ドキュメントの「設定例」セクションを参照してください。
tasks.withType<DokkaTask>().configureEach {
    // ..
    // 一般設定セクション
    // ..

    dokkaSourceSets {
        // '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 {
                // ソースリンクセクション
            }
            externalDocumentationLink {
                // 外部ドキュメントリンクセクション
            }
            perPackageOption {
                // パッケージオプションセクション
            }
        }
    }
}
groovy
import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.Platform
import java.net.URL

// 注意: マルチプロジェクトビルドを設定するには、
// サブプロジェクトのPartialタスクを設定する必要があります。
// ドキュメントの「設定例」セクションを参照してください。
tasks.withType(DokkaTask.class) {
    // ..
    // 一般設定セクション
    // ..
    
    dokkaSourceSets {
        // '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 {
                // ソースリンクセクション
            }
            externalDocumentationLink {
                // 外部ドキュメントリンクセクション
            }
            perPackageOption {
                // パッケージオプションセクション
            }
        }
    }
}
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 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

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

これにより、読者は各宣言のソースコードを見つけやすくなります。

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

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

// 注意: マルチプロジェクトビルドを設定するには、
// サブプロジェクトのPartialタスクを設定する必要があります。
// ドキュメントの「設定例」セクションを参照してください。
tasks.withType<DokkaTask>().configureEach {
    // ..
    // 一般設定セクション
    // ..
    
    dokkaSourceSets.configureEach {
        // ..
        // ソースセット設定セクション
        // ..
        
        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

// 注意: マルチプロジェクトビルドを設定するには、
// サブプロジェクトのPartialタスクを設定する必要があります。
// ドキュメントの「設定例」セクションを参照してください。
tasks.withType(DokkaTask.class) {
    // ..
    // 一般設定セクション
    // ..
    
    dokkaSourceSets.configureEach {
        // ..
        // ソースセット設定セクション
        // ..
        
        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に一致する特定のパッケージに対していくつかのオプションを設定できます。

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

// 注意: マルチプロジェクトビルドを設定するには、
// サブプロジェクトのPartialタスクを設定する必要があります。
// ドキュメントの「設定例」セクションを参照してください。
tasks.withType<DokkaTask>().configureEach {
    // ..
    // 一般設定セクション
    // ..
    
    dokkaSourceSets.configureEach {
        // ..
        // ソースセット設定セクション
        // ..
        
        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

// 注意: マルチプロジェクトビルドを設定するには、
// サブプロジェクトのPartialタスクを設定する必要があります。
// ドキュメントの「設定例」セクションを参照してください。
tasks.withType(DokkaTask.class) {
    // ..
    // 一般設定セクション
    // ..
    
    dokkaSourceSets.configureEach {
        // ..
        // ソースセット設定セクション
        // ..
        
        perPackageOption {
            matchingRegex.set(".*api.*")
            suppress.set(false)
            skipDeprecated.set(false)
            reportUndocumented.set(false)
            documentedVisibilities.set([Visibility.PUBLIC])
        }
    }
}
matchingRegex

パッケージに一致するために使用される正規表現です。

デフォルト: .*

suppress

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

デフォルト: false

skipDeprecated

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

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

デフォルト: false

reportUndocumented

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

この設定は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の外部ドキュメントリンクが設定されています。

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

// 注意: マルチプロジェクトビルドを設定するには、
// サブプロジェクトのPartialタスクを設定する必要があります。
// ドキュメントの「設定例」セクションを参照してください。
tasks.withType<DokkaTask>().configureEach {
    // ..
    // 一般設定セクション
    // ..
    
    dokkaSourceSets.configureEach {
        // ..
        // ソースセット設定セクション
        // ..
        
        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

// 注意: マルチプロジェクトビルドを設定するには、
// サブプロジェクトのPartialタスクを設定する必要があります。
// ドキュメントの「設定例」セクションを参照してください。
tasks.withType(DokkaTask.class) {
    // ..
    // 一般設定セクション
    // ..
    
    dokkaSourceSets.configureEach {
        // ..
        // ソースセット設定セクション
        // ..
        
        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が自動的に解決するのを信頼する代わりに使用できる代替手段です。

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

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

完全な設定 ​

以下に、利用可能なすべての設定オプションが同時に適用された例を示します。

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

// 注意: マルチプロジェクトビルドを設定するには、
// サブプロジェクトの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

// 注意: マルチプロジェクトビルドを設定するには、
// サブプロジェクトの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])
            }
        }
    }
}

Copyright © 2025 Open AIDoc.