使用Dokka进行Kotlin文档编写简介

1. Overview

In this quick tutorial, we’ll look at handling documentation with Dokka. Dokka is a documentation engine for Kotlin that generates API documentation in various formats, including HTML, PDF, and Markdown.

In the first part of the article, we’ll see how to include Dokka in our Gradle or Kotlin project. Next, we’ll look at the principal input and output formats and the most important customizations available. Finally, we’ll see an example of the documentation generated.

2. How to Include and Run Dokka in a Project

First, let’s see how it’s possible to include and run Dokka generation in Maven or Gradle projects. In general, consider that the maven plugin has way fewer customization available. In this case, you might want to consider generating the documentation using the command line interface without adding the documentation generation in the managed build process.

2.1. Dokka with Maven

With Maven, it’s enough to add the dokka-maven-plugin to the plugins section of the POM file:

<build>
    <plugins>
        <plugin>
            <groupId>org.jetbrains.dokka</groupId>
            <artifactId>dokka-maven-plugin</artifactId>
            <version>1.7.20</version>
            <executions>
                <execution>
                    <phase>pre-site</phase>
                    <goals>
                        <goal>dokka</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

And then we can run:

$ mvn dokka:dokka

to generate the documentation, that by default will be placed in: {project.basedir}/target/dokka.

2.2. Dokka with Gradle

With Gradle instead, we should add the org.jetbrains.dokka plugin (works both with the new plugins DSL or with the legacy method) in the build.gradle file:

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

And then we can run:

$ gradle dokkaHtml

to generate the documentation that by default will be placed in the {project}/{buildDir}/html folder.

3. Input and Output Formats and Customizations

With Dokka, we can document mixed-language projects (Java and Kotlin) with two different kinds of input formats: JavaDoc and KDoc. As for the output, Dokka can generate documentation in  HTML format, Markdown, or standard Javadoc HTML.

All available customization for the Gradle and Maven plugins can be found in the official documentation.

Here you can find a list of the most useful options you might want to consider:

• sourceRoots: The source code roots to be analyzed and documented; really useful if you want to exclude some folders
• suppressObviousFunctions: Whether to suppress obvious functions and exclude them from the documentation
• jdkVersion: The JDK version to use when generating external documentation links for Java types.

4. Example of Documentation Generated

Let’s finally see an example of the Dokka HTML documentation of a Kotlin project. Having this kind of documentation in our brand new Blog class:

/**
 * A blog of *articles*.
 *
 * This class it's just a documentation example.
 *
 * @param T the type of article in this blog.
 * @property name the name of this article.
 * @constructor Creates an empty blog.
 */
class Blog<T>(val name: String) {

    /**
     * The variable containing the articles.
     */
    private var articles: MutableList<T> = mutableListOf()

    /**
     * Adds an [article] to this blog.
     * @return the new number of articles of the blog.
     */
    fun add(article: T): Int {
        articles.add(article)
        return articles.size
    }

    /**
     * Remove an [article] to this blog.
     * @return the new number of articles of the blog.
     */
    fun remove(article: T): Int {
        articles.remove(article)
        return articles.size
    }
}

We can generate (with Gradle or Maven, as we have already seen before) this well-formatted and easy-to-read documentation:

The HTML documentation generated is made to be easily published on a website with no additional effort. It comes with a pleasant interface that, nonetheless, is possible to customize further by providing additional CSS files.

4. Conclusion

In this article, we have taken a quick look at Dokka, an API documentation engine for Kotlin. After including Dokka in our Gradle or Maven project, we saw how generating documentation with different input/output formats is possible. Finally, we looked at one running example.

As usual, all the examples are available over on GitHub.