Gradle

To generate documentation for a Gradle-based project, you can use the Gradle plugin for Dokka.

It comes with basic autoconfiguration for your project, has convenient Gradle tasks for generating documentation, and provides a great deal of configuration options to customize the output.

You can play around with Dokka and see how it can be configured for various projects by visiting our Gradle example projects.

Apply Dokka

The recommended way of applying the Gradle plugin for Dokka is with the plugins DSL:

【Kotlin】

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

【Groovy】

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

When documenting multi-project builds, you need to apply the Gradle plugin for Dokka within subprojects as well. You can use allprojects {} or subprojects {} Gradle configurations to achieve that:

【Gradle Kotlin DSL】

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

【Gradle Groovy DSL】

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

See Configuration examples if you are not sure where to apply Dokka.

Under the hood, Dokka uses the Kotlin Gradle plugin to perform autoconfiguration of source sets for which documentation is to be generated. Make sure to apply the Kotlin Gradle Plugin or configure source sets manually.

If you are using Dokka in a precompiled script plugin, you need to add the Kotlin Gradle plugin as a dependency for it to work properly.

If you cannot use the plugins DSL for some reason, you can use the legacy method of applying plugins.

Generate documentation

The Gradle plugin for Dokka comes with HTML, Markdown and Javadoc output formats built in. It adds a number of tasks for generating documentation, both for single and multi-project builds.

Single-project builds

Use the following tasks to build documentation for simple, single-project applications and libraries:

Task Description
dokkaHtml Generates documentation in HTML format.

Experimental formats

Task Description
dokkaGfm Generates documentation in GitHub Flavored Markdown format.
dokkaJavadoc Generates documentation in Javadoc format.
dokkaJekyll Generates documentation in Jekyll compatible Markdown format.

By default, generated documentation is located in the build/dokka/{format} directory of your project. The output location, among other things, can be configured.

Multi-project builds

For documenting multi-project builds, make sure that you apply the Gradle plugin for Dokka within subprojects that you want to generate documentation for, as well as in their parent project.

MultiModule tasks

MultiModule tasks generate documentation for each subproject individually via Partial tasks, collect and process all outputs, and produce complete documentation with a common table of contents and resolved cross-project references.

Dokka creates the following tasks for parent projects automatically:

Task Description
dokkaHtmlMultiModule Generates multi-module documentation in HTML output format.

Experimental formats (multi-module)

Task Description
dokkaGfmMultiModule Generates multi-module documentation in GitHub Flavored Markdown output format.
dokkaJekyllMultiModule Generates multi-module documentation in Jekyll compatible Markdown output format.

The Javadoc output format does not have a MultiModule task, but a Collector task can be used instead.

By default, you can find ready-to-use documentation under {parentProject}/build/dokka/{format}MultiModule directory.

MultiModule results

Given a project with the following structure:

parentProject
    └── childProjectA
        ├── demo
            ├── ChildProjectAClass
    └── childProjectB
        ├── demo
            ├── ChildProjectBClass

These pages are generated after running dokkaHtmlMultiModule:

Screenshot for output of dokkaHtmlMultiModule task

See our multi-module project example for more details.

Collector tasks

Similar to MultiModule tasks, Collector tasks are created for each parent project: dokkaHtmlCollector, dokkaGfmCollector, dokkaJavadocCollector and dokkaJekyllCollector.

A Collector task executes the corresponding single-project task for each subproject (for example, dokkaHtml), and merges all outputs into a single virtual project.

The resulting documentation looks as if you have a single-project build that contains all declarations from the subprojects.

Use the dokkaJavadocCollector task if you need to create Javadoc documentation for your multi-project build.

Collector results

Given a project with the following structure:

parentProject
    └── childProjectA
        ├── demo
            ├── ChildProjectAClass
    └── childProjectB
        ├── demo
            ├── ChildProjectBClass

These pages are generated after running dokkaHtmlCollector:

Screenshot for output of dokkaHtmlCollector task

See our multi-module project example for more details.

Partial tasks

Each subproject has Partial tasks created for it: dokkaHtmlPartial,dokkaGfmPartial, and dokkaJekyllPartial.

These tasks are not intended to be run independently, they are called by the parent's MultiModule task.

However, you can configure Partial tasks to customize Dokka for your subprojects.

Output generated by Partial tasks contains unresolved HTML templates and references, so it cannot be used on its own without post-processing done by the parent's MultiModule task.

If you want to generate documentation for a single subproject only, use single-project tasks. For example, :subprojectName:dokkaHtml.

Build javadoc.jar

If you want to publish your library to a repository, you may need to provide a javadoc.jar file that contains API reference documentation of your library.

For example, if you want to publish to Maven Central, you must supply a javadoc.jar alongside your project. However, not all repositories have that rule.

The Gradle plugin for Dokka does not provide any way to do this out of the box, but it can be achieved with custom Gradle tasks. One for generating documentation in HTML format and another one for Javadoc format:

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

If you publish your library to Maven Central, you can use services like javadoc.io to host your library's API documentation for free and without any setup. It takes documentation pages straight from the javadoc.jar. It works well with the HTML format as demonstrated in this example.

Configuration examples

Depending on the type of project that you have, the way you apply and configure Dokka differs slightly. However, configuration options themselves are the same, regardless of the type of your project.

For simple and flat projects with a single build.gradle.kts or build.gradle file found in the root of your project, see Single-project configuration.

For a more complex build with subprojects and multiple nested build.gradle.kts or build.gradle files, see Multi-project configuration.

Single-project configuration

Single-project builds usually have only one build.gradle.kts or build.gradle file in the root of the project, and typically have the following structure:

【Kotlin】

Single platform:

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

Multiplatform:

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

【Groovy】

Single platform:

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

Multiplatform:

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

In such projects, you need to apply Dokka and its configuration in the root build.gradle.kts or build.gradle file.

You can configure tasks and output formats individually:

【Kotlin】

Inside ./build.gradle.kts:

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

tasks.dokkaHtml {
    outputDirectory.set(buildDir.resolve("documentation/html"))
}

tasks.dokkaGfm {
    outputDirectory.set(buildDir.resolve("documentation/markdown"))
}

【Groovy】

Inside ./build.gradle:

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

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

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

Or you can configure all tasks and output formats at the same time:

【Kotlin】

Inside ./build.gradle.kts:

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

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

// Configure all single-project Dokka tasks at the same time, 
// such as dokkaHtml, dokkaJavadoc and dokkaGfm.
tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets.configureEach {
        documentedVisibilities.set(
            setOf(
                Visibility.PUBLIC,
                Visibility.PROTECTED,
            )
        )

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

【Groovy】

Inside ./build.gradle:

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

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

// Configure all single-project Dokka tasks at the same time, 
// such as dokkaHtml, dokkaJavadoc and dokkaGfm.
tasks.withType(DokkaTask.class) {
    dokkaSourceSets.configureEach {
        documentedVisibilities.set([
                Visibility.PUBLIC,
                Visibility.PROTECTED
        ])

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

Multi-project configuration

Gradle's multi-project builds are more complex in structure and configuration. They usually have multiple nested build.gradle.kts or build.gradle files, and typically have the following structure:

【Kotlin】

.
├── 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

【Groovy】

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

In this case, there are multiple ways of applying and configuring Dokka.

Subproject configuration

To configure subprojects in a multi-project build, you need to configure Partial tasks.

You can configure all subprojects at the same time in the root build.gradle.kts or build.gradle file, using Gradle's allprojects {} or subprojects {} configuration blocks:

【Kotlin】

In the root ./build.gradle.kts:

import org.jetbrains.dokka.gradle.DokkaTaskPartial

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

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

    // configure only the HTML task
    tasks.dokkaHtmlPartial {
        outputDirectory.set(buildDir.resolve("docs/partial"))
    }

    // configure all format tasks at once
    tasks.withType<DokkaTaskPartial>().configureEach {
        dokkaSourceSets.configureEach {
            includes.from("README.md")
        }
    }
}

【Groovy】

In the root ./build.gradle:

import org.jetbrains.dokka.gradle.DokkaTaskPartial

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

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

    // configure only the HTML task
    dokkaHtmlPartial {
        outputDirectory.set(file("build/docs/partial"))
    }

    // configure all format tasks at once
    tasks.withType(DokkaTaskPartial.class) {
        dokkaSourceSets.configureEach {
            includes.from("README.md")
        }
    }
}

Alternatively, you can apply and configure Dokka within subprojects individually.

For example, to have specific settings for the subproject-A subproject only, you need to apply the following code inside ./subproject-A/build.gradle.kts:

【Kotlin】

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

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

// configuration for subproject-A only.
tasks.dokkaHtmlPartial {
    outputDirectory.set(buildDir.resolve("docs/partial"))
}

【Groovy】

Inside ./subproject-A/build.gradle:

apply plugin: 'org.jetbrains.dokka'

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

Parent project configuration

If you want to configure something which is universal across all documentation and does not belong to the subprojects - in other words, it's a property of the parent project - you need to configure the MultiModule tasks.

For example, if you want to change the name of your project which is used in the header of the HTML documentation, you need to apply the following inside the root build.gradle.kts or build.gradle file:

【Kotlin】

In the root ./build.gradle.kts file:

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

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

【Groovy】

In the root ./build.gradle file:

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

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

Configuration options

Dokka has many configuration options to tailor your and your reader's experience.

Below are some examples and detailed descriptions for each configuration section. You can also find an example with all configuration options applied at the bottom of the page.

See Configuration examples for more details on where to apply configuration blocks and how.

General configuration

Here is an example of general configuration of any Dokka task, regardless of source set or package:

【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. 
tasks.withType<DokkaTask>().configureEach {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(buildDir.resolve("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. 
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
    // ..
}

The display name used to refer to the module. It is used for the table of contents, navigation, logging, etc.

If set for a single-project build or a MultiModule task, it is used as the project name.

Default: Gradle project name

The module version. If set for a single-project build or a MultiModule task, it is used as the project version.

Default: Gradle project version

The directory to where documentation is generated, regardless of format. It can be set on a per-task basis.

The default is {project}/{buildDir}/{format}, where {format} is the task name with the "dokka" prefix removed. For the dokkaHtmlMultiModule task, it is project/buildDir/htmlMultiModule.

Whether to fail documentation generation if Dokka has emitted a warning or an error. The process waits until all errors and warnings have been emitted first.

This setting works well with reportUndocumented.

Default: false

Whether to suppress obvious functions.

A function is considered to be obvious if it is:

  • Inherited from kotlin.Any, Kotlin.Enum, java.lang.Object or java.lang.Enum, such as equals, hashCode, toString.
  • Synthetic (generated by the compiler) and does not have any documentation, such as dataClass.componentN or dataClass.copy.

    • Default: true

    Whether to suppress inherited members that aren't explicitly overridden in a given class.

    Note: This can suppress functions such as equals / hashCode / toString, but cannot suppress synthetic functions such as dataClass.componentN and dataClass.copy. Use suppressObviousFunctions for that.

    Default: false

    Whether to resolve remote files/links over your network.

    This includes package-lists used for generating external documentation links. For example, to make classes from the standard library clickable.

    Setting this to true can significantly speed up build times in certain cases, but can also worsen documentation quality and user experience. For example, by not resolving class/member links from your dependencies, including the standard library.

    Note: You can cache fetched files locally and provide them to Dokka as local paths. See externalDocumentationLinks section.

    Default: false

    Source set configuration

    Dokka allows configuring some options for Kotlin source sets:

    【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. 
tasks.withType<DokkaTask>().configureEach {
    // ..
    // general configuration section
    // ..

    dokkaSourceSets {
        // configuration exclusive to the 'linux' source set
        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. 
tasks.withType(DokkaTask.class) {
    // ..
    // general configuration section
    // ..

    dokkaSourceSets {
        // configuration exclusive to the 'linux' source set 
        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
            }
        }
    }
}

    Whether this source set should be skipped when generating documentation.

    Default: false

    The display name used to refer to this source set.

    The name is used both externally (for example, as source set name visible to documentation readers) and internally (for example, for logging messages of reportUndocumented).

    By default, the value is deduced from information provided by the Kotlin Gradle plugin.

    The set of visibility modifiers that should be documented.

    This can be used if you want to document protected/internal/private declarations, as well as if you want to exclude public declarations and only document internal API.

    This can be configured on per-package basis.

    Default: DokkaConfiguration.Visibility.PUBLIC

    Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs after they have been filtered by documentedVisibilities and other filters.

    This setting works well with failOnWarning.

    This can be configured on per-package basis.

    Default: false

    Whether to skip packages that contain no visible declarations after various filters have been applied.

    For example, if skipDeprecated is set to true and your package contains only deprecated declarations, it is considered to be empty.

    Default: true

    Whether to document declarations annotated with @Deprecated.

    This can be configured on per-package basis.

    Default: false

    Whether to document/analyze generated files.

    Generated files are expected to be present under the {project}/{buildDir}/generated directory.

    If set to true, it effectively adds all files from that directory to the suppressedFiles option, so you can configure it manually.

    Default: true

    The JDK version to use when generating external documentation links for Java types.

    For example, if you use java.util.UUID in some public declaration signature, and this option is set to 8, Dokka generates an external documentation link to JDK 8 Javadocs for it.

    Default: JDK 8

    The Kotlin language version used for setting up analysis and @sample environment.

    By default, the latest language version available to Dokka's embedded compiler is used.

    The Kotlin API version used for setting up analysis and @sample environment.

    By default, it is deduced from languageVersion.

    Whether to generate external documentation links that lead to the API reference documentation of Kotlin's standard library.

    Note: Links are generated when noStdLibLink is set to false.

    Default: false

    Whether to generate external documentation links to JDK's Javadocs.

    The version of JDK Javadocs is determined by the jdkVersion option.

    Note: Links are generated when noJdkLink is set to false.

    Default: false

    Whether to generate external documentation links to the Android SDK API reference.

    This is only relevant in Android projects, ignored otherwise.

    Note: Links are generated when noAndroidSdkLink is set to false.

    Default: false

    A list of Markdown files that contain module and package documentation.

    The contents of the specified files are parsed and embedded into documentation as module and package descriptions.

    See Dokka gradle example for an example of what it looks like and how to use it.

    The platform to be used for setting up code analysis and @sample environment.

    The default value is deduced from information provided by the Kotlin Gradle plugin.

    The source code roots to be analyzed and documented. Acceptable inputs are directories and individual .kt / .java files.

    By default, source roots are deduced from information provided by the Kotlin Gradle plugin.

    The classpath for analysis and interactive samples.

    This is useful if some types that come from dependencies are not resolved/picked up automatically.

    This option accepts both .jar and .klib files.

    By default, classpath is deduced from information provided by the Kotlin Gradle plugin.

    A list of directories or files that contain sample functions which are referenced via the @sample KDoc tag.

    The sourceLinks configuration block allows you to add a source link to each signature that leads to the remoteUrl with a specific line number. (The line number is configurable by setting remoteLineSuffix).

    This helps readers to find the source code for each declaration.

    For an example, see the documentation for the count() function in kotlinx.coroutines.

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

    The path to the local source directory. The path must be relative to the root of the current project.

    The URL of the source code hosting service that can be accessed by documentation readers, like GitHub, GitLab, Bitbucket, etc. This URL is used to generate source code links of declarations.

    The suffix used to append the source code line number to the URL. This helps readers navigate not only to the file, but to the specific line number of the declaration.

    The number itself is appended to the specified suffix. For example, if this option is set to #L and the line number is 10, the resulting URL suffix is #L10.

    Suffixes used by popular services:

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

    • Default: #L

    Package options

    The perPackageOption configuration block allows setting some options for specific packages matched by matchingRegex.

    【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. 
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.
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])
        }
    }
}

    The regular expression that is used to match the package.

    Default: .*

    Whether this package should be skipped when generating documentation.

    Default: false

    Whether to document declarations annotated with @Deprecated.

    This can be configured on source set level.

    Default: false

    Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs after they have been filtered by documentedVisibilities and other filters.

    This setting works well with failOnWarning.

    This can be configured on source set level.

    Default: false

    The set of visibility modifiers that should be documented.

    This can be used if you want to document protected/internal/private declarations within this package, as well as if you want to exclude public declarations and only document internal API.

    This can be configured on source set level.

    Default: DokkaConfiguration.Visibility.PUBLIC

    The externalDocumentationLink block allows the creation of links that lead to the externally hosted documentation of your dependencies.

    For example, if you are using types from kotlinx.serialization, by default they are unclickable in your documentation, as if they are unresolved. However, since the API reference documentation for kotlinx.serialization is built by Dokka and is published on kotlinlang.org, you can configure external documentation links for it. Thus allowing Dokka to generate links for types from the library, making them resolve successfully and clickable.

    By default, external documentation links for Kotlin standard library, JDK, Android SDK and AndroidX are configured.

    【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. 
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. 
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()
            )
        }
    }
}

    The root URL of documentation to link to. It must contain a trailing slash.

    Dokka does its best to automatically find package-list for the given URL, and link declarations together.

    If automatic resolution fails or if you want to use locally cached files instead, consider setting the packageListUrl option.

    The exact location of a package-list. This is an alternative to relying on Dokka automatically resolving it.

    Package lists contain information about the documentation and the project itself, such as module and package names.

    This can also be a locally cached file to avoid network calls.

    Complete configuration

    Below you can see all possible configuration options applied at the same time.

    【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. 
tasks.withType<DokkaTask>().configureEach {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(buildDir.resolve("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/latest/jvm/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. 
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/latest/jvm/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])
            }
        }
    }
}