path: root/README.md

dokka  [![official JetBrains project](https://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
[![TeamCity (build status)](https://teamcity.jetbrains.com/app/rest/builds/buildType:(id:Kotlin_Dokka_DokkaAntMavenGradle)/statusIcon)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=Kotlin_Dokka_DokkaAntMavenGradle&branch_KotlinTools_Dokka=%3Cdefault%3E&tab=buildTypeStatusDiv) [ ![Download](https://api.bintray.com/packages/kotlin/dokka/dokka/images/download.svg) ](https://bintray.com/kotlin/dokka/dokka/_latestVersion)
=====

Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java.
Just like Kotlin itself, Dokka fully supports mixed-language Java/Kotlin projects. It understands
standard Javadoc comments in Java files and [KDoc comments](https://kotlinlang.org/docs/reference/kotlin-doc.html) in Kotlin files,
and can generate documentation in multiple formats including standard Javadoc, HTML and Markdown.

## Using Dokka

### Using the Gradle plugin

```groovy
buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath "org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}"
    }
}
repositories {
    jcenter() // or maven { url 'https://dl.bintray.com/kotlin/dokka' }
}

apply plugin: 'org.jetbrains.dokka'
```

or using the plugins block:

```groovy
plugins {
    id 'org.jetbrains.dokka' version '0.9.18'
}
repositories {
    jcenter() // or maven { url 'https://dl.bintray.com/kotlin/dokka' }
}
```

The plugin adds a task named "dokka" to the project.

If you encounter any problems when migrating from older versions of Dokka, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq).

Minimal dokka configuration:

Groovy
```groovy
dokka {
    outputFormat = 'html' 
    outputDirectory = "$buildDir/javadoc"
}
```

Kotlin
```kotlin
tasks {
    val dokka by getting(DokkaTask::class) {
        outputFormat = "html"
        outputDirectory = "$buildDir/dokka"
    }
}
```

[Output formats](#output_formats)

The available configuration options for single platform are shown below:

```groovy
dokka {
    outputFormat = 'html'
    outputDirectory = "$buildDir/javadoc"
    
    // In case of Gradle multiproject build, you can include subprojects here to get merged documentation
    // Note however, that you have to have the Kotlin plugin available in the root project 
    subProjects = ["subproject1", "subproject2"]
        
    // Used for disabling auto extraction of sources and platforms in both multi-platform and single-platform modes
    // When set to true, subProject and kotlinTasks are also omitted
    disableAutoconfiguration = false 

    // Use default or set to custom path to cache directory
    // to enable package-list caching
    // When set to default, caches stored in $USER_HOME/.cache/dokka
    cacheRoot = 'default' 
    
    configuration {
        moduleName = 'data'

        // Use to include or exclude non public members.
        includeNonPublic = false
        
        // Do not output deprecated members. Applies globally, can be overridden by packageOptions
        skipDeprecated = false 
       
        // Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions
        reportUndocumented = true 
        
        skipEmptyPackages = true // Do not create index pages for empty packages
     
        targets = ["JVM"] // See platforms section of documentation 

        platform = "JVM" // Platform used for code analysis 
        
        // Manual adding files to classpath
        // This property not overrides classpath collected from kotlinTasks but appends to it
        classpath = [new File("$buildDir/other.jar")]
    
        // By default, sourceRoots is taken from kotlinTasks, following roots will be appended to it
        // Short form sourceRoots
        sourceDirs = files('src/main/kotlin')
        
        // List of files with module and package documentation
        // https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation
        includes = ['packages.md', 'extra.md']
    
        // The list of files or directories containing sample code (referenced with @sample tags)
        samples = ['samples/basic.kt', 'samples/advanced.kt']

        // By default, sourceRoots is taken from kotlinTasks, following roots will be appended to it
        // Full form sourceRoot declaration
        // Repeat for multiple sourceRoots
        sourceRoot {
            // Path to source root
            path = "src" 
        }
        
        // These tasks will be used to determine source directories and classpath
        kotlinTasks {
            defaultKotlinTasks() + [':some:otherCompileKotlin', project("another").compileKotlin]
        }

        // Specifies the location of the project source code on the Web.
        // If provided, Dokka generates "source" links for each declaration.
        // Repeat for multiple mappings
        sourceLink {
            // Unix based directory relative path to the root of the project (where you execute gradle respectively). 
            path = "src/main/kotlin" // or simply "./"
             
            // URL showing where the source code can be accessed through the web browser
            url = "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin" //remove src/main/kotlin if you use "./" above
            
            // Suffix which is used to append the line number to the URL. Use #L for GitHub
            lineSuffix = "#L"
        }

        // Used for linking to JDK documentation
        jdkVersion = 6 

        // Disable linking to online kotlin-stdlib documentation
        noStdlibLink = false
        
        // Disable linking to online JDK documentation
        noJdkLink = false 
        
        // Allows linking to documentation of the project's dependencies (generated with Javadoc or Dokka)
        // Repeat for multiple links
        externalDocumentationLink {
            // Root URL of the generated documentation to link with. The trailing slash is required!
            url = new URL("https://example.com/docs/")
            
            // If package-list file located in non-standard location
            // packageListUrl = new URL("file:///home/user/localdocs/package-list") 
        }
        
        // Allows to customize documentation generation options on a per-package basis
        // Repeat for multiple packageOptions
        perPackageOption {
            prefix = "kotlin" // will match kotlin and all sub-packages of it
            // All options are optional, default values are below:
            skipDeprecated = false
            reportUndocumented = true // Emit warnings about not documented members 
            includeNonPublic = false
        }
        // Suppress a package
        perPackageOption {
            prefix = "kotlin.internal" // will match kotlin.internal and all sub-packages of it
            suppress = true
        }
    }
}
```

#### Multiplatform
Since 0.9.19 dokka supports multiplatform projects. 
The available configuration options for multiplatform are like those for single platform, but the `configuration` block 
is replaced by `multiplatform` which has inner blocks for each platform. The inner blocks can be named arbitrary, 
however if you want to use source roots and classpath provided by Kotlin Multiplatform plugin, they must have the same names.

Groovy
```groovy
kotlin { // Kotlin Multiplatform plugin configuration
    jvm() 
    js("customName")
}

dokka {
    outputDirectory = "$buildDir/dokka"
    outputFormat = "html"

    multiplatform {
        customName {} // The same name as in Kotlin Multiplatform plugin, so the sources are fetched automatically
        
        differentName { // Different name, so source roots and platform must be passed explicitly
            targets = ["JVM"]
            platform = "jvm"
            sourceRoot {
                path = kotlin.sourceSets.jvmMain.kotlin.srcDirs[0]
            }
            sourceRoot {
                path = kotlin.sourceSets.commonMain.kotlin.srcDirs[0]
            }
        }
    }
}
```

Kotlin
```kotlin
kotlin {  // Kotlin Multiplatform plugin configuration
    jvm()
    js("customName")
}

val dokka by getting(DokkaTask::class) {
        outputDirectory = "$buildDir/dokka"
        outputFormat = "html"

        multiplatform { 
            val customName by creating {} // The same name as in Kotlin Multiplatform plugin, so the sources are fetched automatically

            register("differentName") { // Different name, so source roots must be passed explicitly
                targets = listOf("JVM")
                platform = "jvm"
                sourceRoot {
                    path = kotlin.sourceSets.getByName("jvmMain").kotlin.srcDirs.first().toString()
                }
                sourceRoot {
                    path = kotlin.sourceSets.getByName("commonMain").kotlin.srcDirs.first().toString()
                }
            }
        }
    }
```

Note that `javadoc` output format cannot be used with multiplatform. 

To generate the documentation, use the `dokka` Gradle task:

```bash
./gradlew dokka
```

More dokka tasks can be added to a project like this:

```groovy
task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) {
    outputFormat = 'javadoc'
    outputDirectory = "$buildDir/javadoc"
}
```

Please see the [Dokka Gradle example project](https://github.com/JetBrains/kotlin-examples/tree/master/gradle/dokka-gradle-example) for an example.

#### Dokka Runtime
If you are using Gradle plugin and you want to use a custom version of Dokka, you can do it by setting `dokkaRuntime` and `dokkaFatJar`:

```groovy
buildscript {
    ...
}

apply plugin: 'org.jetbrains.dokka'

repositories {
    jcenter()
}

dependencies {
    dokkaRuntime "org.jetbrains.dokka:dokka-fatjar:0.9.19"
}

dokka {
    dokkaFatJar = "dokka-fatjar-0.9.19"
    outputFormat = 'html'
    outputDirectory = "$buildDir/dokkaHtml"
}

```
If you don't provide `dokkaFatJar` in `dokka` task then version from `dokka-gradle-plugin` will be used.  

To use your Fat Jar, just set path to it:

 ```groovy
 buildscript {
     ...
 }
 
 apply plugin: 'org.jetbrains.dokka'
 
 repositories {
     jcenter()
 }
 
 dependencies {
     dokkaRuntime files("/path/to/fatjar/dokka-fatjar-0.9.19.jar")
 }
 
 dokka {
     dokkaFatJar = "dokka-fatjar-0.9.19"
     outputFormat = 'html'
     outputDirectory = "$buildDir/dokkaHtml"
 }
 
 ```

#### FAQ
If you encounter any problems, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq).

#### Android

If you are using Android there is a separate Gradle plugin. Just make sure you apply the plugin after
`com.android.library` and `kotlin-android`.

```groovy
buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath "org.jetbrains.dokka:dokka-android-gradle-plugin:${dokka_version}"
    }
}
repositories {
    jcenter()
}
apply plugin: 'com.android.library'
apply plugin: 'kotlin-android'
apply plugin: 'org.jetbrains.dokka-android'
```

### Using the Maven plugin

The Maven plugin is available in JCenter. You need to add the JCenter repository to the list of plugin repositories if it's not there:

```xml
<pluginRepositories>
    <pluginRepository>
        <id>jcenter</id>
        <name>JCenter</name>
        <url>https://jcenter.bintray.com/</url>
    </pluginRepository>
</pluginRepositories>
```

Minimal Maven configuration is

```xml
<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <version>