Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

dokka

Documentation Engine for Kotlin

Subscribe to updates I use dokka


Statistics on dokka

Number of watchers on Github 549
Number of open issues 84
Average time to close an issue about 1 month
Main language Kotlin
Average time to merge a PR 5 days
Open pull requests 22+
Closed pull requests 11+
Last commit over 1 year ago
Repo Created over 5 years ago
Repo Last Updated over 1 year ago
Size 435 MB
Organization / Authorkotlin
Latest Release0.9.16
Contributors8
Page Updated
Do you use dokka? Leave a review!
View open issues (84)
View dokka activity
View on github
Fresh, new opensource launches šŸš€šŸš€šŸš€
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating dokka for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

dokka official JetBrains project

TeamCity (build status) Download

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 in Kotlin files, and can generate documentation in multiple formats including standard Javadoc, HTML and Markdown.

Using Dokka

Using the Gradle plugin

buildscript {
    repositories {
        jcenter()
    }

    dependencies {
        classpath "org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}"
    }
}

apply plugin: 'org.jetbrains.dokka'

The plugin adds a task named dokka to the project.

Minimal dokka configuration:

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

Output formats

The available configuration options are shown below:

dokka {
    moduleName = 'data'
    outputFormat = 'html'
    outputDirectory = "$buildDir/javadoc"

    // These tasks will be used to determine source directories and classpath 
    kotlinTasks {
        defaultKotlinTasks() + [':some:otherCompileKotlin', project("another").compileKotlin]
    }

    // List of files with module and package documentation
    // http://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']

    jdkVersion = 6 // Used for linking to JDK

    // 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' 

    // 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

    impliedPlatforms = ["JVM"] // See platforms section of documentation 

    // 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')

    // 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" 
        // See platforms section of documentation 
        platforms = ["JVM"] 
    }

    // Specifies the location of the project source code on the Web.
    // If provided, Dokka generates "source" links for each declaration.
    // Repeat for multiple mappings
    linkMapping {
        // Source directory
        dir = "src/main/kotlin"

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

        // Suffix which is used to append the line number to the URL. Use #L for GitHub
        suffix = "#L"
    }

    // No default documentation link to kotlin-stdlib
    noStdlibLink = 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
    packageOptions {
        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
    packageOptions {
        prefix = "kotlin.internal" // will match kotlin.internal and all sub-packages of it
        suppress = true
    }
}

To generate the documentation, use the dokka Gradle task:

./gradlew dokka

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

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

Please see the Dokka Gradle example project for an example.

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.

buildscript {
    repositories {
        jcenter()
    }

    dependencies {
        classpath "org.jetbrains.dokka:dokka-android-gradle-plugin:${dokka_version}"
    }
}

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:

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

Minimal Maven configuration is

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <version>${dokka.version}</version>
    <executions>
        <execution>
            <phase>pre-site</phase>
            <goals>
                <goal>dokka</goal>
            </goals>
        </execution>
    </executions>
</plugin>

By default files will be generated in target/dokka.

The following goals are provided by the plugin:

  • dokka:dokka - generate HTML documentation in Dokka format (showing declarations in Kotlin syntax);
  • dokka:javadoc - generate HTML documentation in JavaDoc format (showing declarations in Java syntax);
  • dokka:javadocJar - generate a .jar file with JavaDoc format documentation.

The available configuration options are shown below:

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <version>${dokka.version}</version>
    <executions>
        <execution>
            <phase>pre-site</phase>
            <goals>
                <goal>dokka</goal>
            </goals>
        </execution>
    </executions>
    <configuration>

        <!-- Set to true to skip dokka task, default: false -->
        <skip>false</skip>

        <!-- Default: ${project.artifactId} -->
        <moduleName>data</moduleName>
        <!-- See list of possible formats below -->
        <outputFormat>html</outputFormat>
        <!-- Default: ${project.basedir}/target/dokka -->
        <outputDir>some/out/dir</outputDir>

        <!-- 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</cacheRoot>

        <!-- List of '.md' files with package and module docs -->
        <!-- http://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation -->
        <includes>
            <file>packages.md</file>
            <file>extra.md</file>
        </includes>

        <!-- List of sample roots -->
        <samplesDirs>
            <dir>src/test/samples</dir>
        </samplesDirs>

        <!-- Used for linking to JDK, default: 6 -->
        <jdkVersion>6</jdkVersion>

        <!-- Do not output deprecated members, applies globally, can be overridden by packageOptions -->
        <skipDeprecated>false</skipDeprecated> 
        <!-- Emit warnings about not documented members, applies globally, also can be overridden by packageOptions -->
        <reportNotDocumented>true</reportNotDocumented>             
        <!-- Do not create index pages for empty packages -->
        <skipEmptyPackages>true</skipEmptyPackages> 

        <!-- See platforms section of documentation -->
        <impliedPlatforms>
            <platform>JVM</platform>
        </impliedPlatforms>

        <!-- Short form list of sourceRoots, by default, set to ${project.compileSourceRoots} -->
        <sourceDirectories>
            <dir>src/main/kotlin</dir>
        </sourceDirectories>

        <!-- Full form list of sourceRoots -->
        <sourceRoots>
            <root>
                <path>src/main/kotlin</path>
                <!-- See platforms section of documentation -->
                <platforms>JVM</platforms>
            </root>
        </sourceRoots>

        <!-- Specifies the location of the project source code on the Web. If provided, Dokka generates "source" links
             for each declaration. -->
        <sourceLinks>
            <link>
                <!-- Source directory -->
                <dir>${project.basedir}/src/main/kotlin</dir>
                <!-- URL showing where the source code can be accessed through the web browser -->
                <url>http://github.com/me/myrepo</url>
                <!--Suffix which is used to append the line number to the URL. Use #L for GitHub -->
                <urlSuffix>#L</urlSuffix>
            </link>
        </sourceLinks>

        <!-- No default documentation link to kotlin-stdlib -->
        <noStdlibLink>false</noStdlibLink>

        <!-- Allows linking to documentation of the project's dependencies (generated with Javadoc or Dokka) -->
        <externalDocumentationLinks>
            <link>
                <!-- Root URL of the generated documentation to link with. The trailing slash is required! -->
                <url>https://example.com/docs/</url>
                <!-- If package-list file located in non-standard location -->
                <!-- <packageListUrl>file:///home/user/localdocs/package-list</packageListUrl> -->
            </link>
        </externalDocumentationLinks>

        <!-- Allows to customize documentation generation options on a per-package basis -->
        <perPackageOptions>
            <packageOptions>
                <!-- Will match kotlin and all sub-packages of it -->
                <prefix>kotlin</prefix>

                <!-- All options are optional, default values are below: -->
                <skipDeprecated>false</skipDeprecated>
                <!-- Emit warnings about not documented members  -->
                <reportUndocumented>true</reportUndocumented>
                <includeNonPublic>false</includeNonPublic>
            </packageOptions>
        </perPackageOptions>
    </configuration>
</plugin>

Please see the Dokka Maven example project for an example.

Output formats

Using the Ant task

The Ant task definition is also contained in the dokka-fatjar.jar referenced above. Here's an example of using it:

<project name="Dokka" default="document">
    <typedef resource="dokka-antlib.xml" classpath="dokka-fatjar.jar"/>

    <target name="document">
        <dokka src="src" outputdir="doc" modulename="myproject"/>
    </target>
</project>

The Ant task supports the following attributes:

  • outputDir - the output directory where the documentation is generated
  • outputFormat - the output format (see the list of supported formats above)
  • classpath - list of directories or .jar files to include in the classpath (used for resolving references)
  • samples - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the @sample tag)
  • moduleName - the name of the module being documented (used as the root directory of the generated documentation)
  • include - names of files containing the documentation for the module and individual packages
  • skipDeprecated - if set, deprecated elements are not included in the generated documentation
  • jdkVersion - version for linking to JDK
  • impliedPlatforms - See platforms section
  • <sourceRoot path="src" platforms="JVM" /> - analogue of src, but allows to specify platforms
  • <packageOptions prefix="kotlin" includeNonPublic="false" reportUndocumented="true" skipDeprecated="false"/> - Per package options for package kotlin and sub-packages of it
  • noStdlibLink - No default documentation link to kotlin-stdlib
  • <externalDocumentationLink url="https://example.com/docs/" packageListUrl="file:///home/user/localdocs/package-list"/> - linking to external documentation, packageListUrl should be used if package-list located not in standard location
  • cacheRoot - 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

Using the Command Line

To run Dokka from the command line, download the Dokka jar. To generate documentation, run the following command:

java -jar dokka-fatjar.jar <source directories> <arguments>

Dokka supports the following command line arguments:

  • -output - the output directory where the documentation is generated
  • -format - the output format:
  • -classpath - list of directories or .jar files to include in the classpath (used for resolving references)
  • -samples - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the @sample tag)
  • -module - the name of the module being documented (used as the root directory of the generated documentation)
  • -include - names of files containing the documentation for the module and individual packages
  • -nodeprecated - if set, deprecated elements are not included in the generated documentation
  • -impliedPlatforms - List of implied platforms (comma-separated)
  • -packageOptions - List of package options in format prefix,-deprecated,-privateApi,+warnUndocumented;...
  • -links - External documentation links in format url^packageListUrl^^url2...
  • -noStdlibLink - Disable documentation link to stdlib
  • -cacheRoot - 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

Output formats

  • html - minimalistic html format used by default
  • javadoc - Dokka mimic to javadoc
  • html-as-java - as html but using java syntax
  • markdown - Markdown structured as html
    • gfm - GitHub flavored markdown
    • jekyll - Jekyll compatible markdown
  • kotlin-website* - internal format used for documentation on kotlinlang.org

Platforms

Dokka can annotate elements with special platform block with platform requirements

Example of usage can be found on kotlinlang.org

Each source root has a list of platforms for which members are suitable. Also, the list of 'implied' platforms is passed to Dokka. If a member is not available for all platforms in the implied platforms set, its documentation will show the list of platforms for which it's available.

Dokka Internals

Documentation Model

Dokka uses Kotlin-as-a-service technology to build code model, then processes it into documentation model. Documentation model is graph of items describing code elements such as classes, packages, functions, etc.

Each node has semantic attached, e.g. Value:name -> Type:String means that some value name is of type String.

Each reference between nodes also has semantic attached, and there are three of them:

  1. Member - reference means that target is member of the source, form tree.
  2. Detail - reference means that target describes source in more details, form tree.
  3. Link - any link to any other node, free form.

Member & Detail has reverse Owner reference, while Link's back reference is also Link.

Nodes that are Details of other nodes cannot have Members.

Rendering Docs

When we have documentation model, we can render docs in various formats, languages and layouts. We have some core services:

  • FormatService -- represents output format
  • LocationService -- represents folder and file layout
  • SignatureGenerator -- represents target language by generating class/function/package signatures from model

Basically, given the documentation as a model, we do this:

    val signatureGenerator = KotlinSignatureGenerator()
    val locationService = FoldersLocationService(arguments.outputDir)
    val markdown = JekyllFormatService(locationService, signatureGenerator)
    val generator = FileGenerator(signatureGenerator, locationService, markdown)
    generator.generate(documentation)

Building Dokka

Dokka is built with Gradle. To build it, use ./gradlew build. Alternatively, open the project directory in IntelliJ IDEA and use the IDE to build and run Dokka.

dokka open issues Ask a question     (View All Issues)
  • about 3 years Insufficient documentation for gradle task
  • about 3 years Jekyll format generates bad links
  • over 3 years Javadoc generation fails via dokka-gradle-plugin (v0.9.9)
  • over 3 years Suggestion: Linking to Kotlin/Java stdlib
  • over 3 years Missing class: DocErrorReporter
  • over 3 years Suggestion: Group Methods or Classes
  • over 3 years Indented code blocks
  • over 3 years Can't reference a specific function overload
  • over 3 years Dokka can't find return type function with expression body and omitted return type
  • over 3 years Don't ever print <ERROR CLASS> to the output
  • over 3 years Java package-info.html files not included in documentation
  • over 3 years Any chance Kotlin Dokka will support emoji?
  • almost 4 years Add another Dokka distribution that is not a fatjar
  • almost 4 years Dokka Gradle plugin should run Dokka out of process
  • almost 4 years Please publish the plugin to maven central
dokka open pull requests (View All Pulls)
  • Fix KT-11099
  • Android support and custom sources
  • Maven : Avoid crash when no javadoc generated
  • many markdown fixes
  • Apply Gradle Plugin Publishing Plugin 0.9.5
  • Fix for KT-14076 : empty visible div's
  • Fix for GH #92 : Jekyll format generates bad links
  • Tweaked output for kotlin-website samples feature
  • KT-14818 Render function type argument names in generated documentation
  • Type alias support
  • Fix dokka-android plugin with Android Gradle 2.4.0 build tools
  • Add a line between table rows
  • Add information on suppress package option
  • MPP fixes
  • Update plugin-publish-plugin
  • Suppress all generated files (Java and Android projects)
  • #221 - Updates external documentation link configuration
  • Optional support for asciidoctor in dokka
  • Put samples in a section
  • Document that kotlin-android plugin is required even for non-kotlin pā€¦
  • fix doc linkMapping, requires absolute path
  • Includes gradle plugin fixes and xml attribute generation.
dokka list of languages used
dokka latest release notes
0.9.16 0.9.16
  • Bundled kotlin compiler updated to 1.2.40-dev-529
  • #251 Fixed suboptimal (non-incremental) input properties for Gradle tasks
  • #252 Fixed crash when class folders are on the classpath
  • #265 Fixed Gradle plugin compatibility with Kotlin 1.2
  • #243 Renamed reportNotDocumented to reportUndocumented in the Gradle plugin
  • #128 Added task option to suppress an entire package
  • #220 Fixed Dokka running under JDK9
  • #174 Fixed wrong link in the last breadcrumbs item
  • #205 Fixed links to Companion static methods with parameters do not work in javadoc format
  • #224 Filtered out Android generated classes from docs
  • #186 Fixed Gradle plugin task does not execute after source updates
  • #228 Fixed Multi-line indented code block rendering to HTML
  • #226 Fixed Gradle plugin includeNonPublic not working as documented
  • #218 Made classpath configuration option Iterable<File>
  • #219 Unbundled kotlin-stdlib & kotlin-reflect from Gradle plugin
  • #225 Fixed exception when using packageOptions in Gradle plugin

Get artifacts at https://bintray.com/kotlin/dokka/dokka/0.9.16

0.9.16-eap-3 0.9.16 EAP 3

Fixed incompatibility with Gradle 4.5+ (#265)

Dokka now not compatible with Gradle >= 3.2, < 3.5

Artifacts

https://bintray.com/kotlin/kotlin-eap/dokka/0.9.16-eap-3

0.9.16-eap-2 0.9.16 EAP 2

Artifacts available at https://bintray.com/kotlin/kotlin-eap/dokka

Other projects in Kotlin