Dokka for Kotlin: Complete Guide with Examples

Introduction to Dokka: what it is and why you need it

\n\n

Dokka is a powerful tool for generating documentation from Kotlin source code. Developed by JetBrains, Dokka is the official solution for creating documentation for Kotlin projects. It analyzes your code, extracts KDoc comments (the Kotlin equivalent of JavaDoc), and generates structured documentation in various formats: HTML, Markdown, Javadoc, and others.

\n\n

Why do you need Dokka?

\n

\n
• Automation: You don't need to write documentation manually. Dokka generates it based on your code and comments.
\n
• Up-to-date: Documentation always matches the code since it is generated directly from it.
\n
• Kotlin Multiplatform support: Dokka works great with multiplatform projects, combining documentation from different modules (common, jvm, js, native).
\n
• Flexibility: You can customize the appearance, output format, and include/exclude specific parts of the code.
\n
• Integration: Easily integrates with Gradle and Maven build systems.
\n

\n\n

Dokka is indispensable for developers of libraries, APIs, and large projects where high-quality documentation is critical for users.

\n\n

Installing Dokka

\n\n

Dokka is not installed via pip or npm, as it is a tool for the Kotlin/JVM ecosystem. The main installation method is through the Gradle (recommended) or Maven build system.

\n\n

Installation via Gradle (Kotlin DSL)

\n

\n// build.gradle.kts\nplugins {\n    id("org.jetbrains.dokka") version "1.9.20" // Check for the latest version\n}\n\n// Or via apply plugin:\n// apply(plugin = "org.jetbrains.dokka")\n

\n\n

Installation via Gradle (Groovy DSL)

\n

\n// build.gradle\nplugins {\n    id 'org.jetbrains.dokka' version '1.9.20'\n}\n

\n\n

Installation via Maven

\n

\n<plugin>\n    <groupId>org.jetbrains.dokka</groupId>\n    <artifactId>dokka-maven-plugin</artifactId>\n    <version>1.9.20</version>\n    <executions>\n        <execution>\n            <phase>compile</phase>\n            <goals><goal>dokka</goal></goals>\n        </execution>\n    </executions>\n</plugin>\n

\n\n

Quick Start: First Run

\n\n

After adding the plugin, you need to write some KDoc comments in your code and run the Gradle task.

\n\n

Step 1: Write code with comments

\n

\n// src/main/kotlin/com/example/Calculator.kt\n\n/**\n * A simple calculator that performs basic arithmetic operations.\n *\n * @author PythonLib Team\n * @since 1.0.0\n */\nclass Calculator {\n\n    /**\n     * Adds two integers.\n     *\n     * @param a The first addend.\n     * @param b The second addend.\n     * @return The sum of a and b.\n     */\n    fun add(a: Int, b: Int): Int = a + b\n\n    /**\n     * Divides one number by another.\n     *\n     * @param dividend The number to be divided.\n     * @param divisor The divisor. Cannot be zero.\n     * @return The result of the division.\n     * @throws IllegalArgumentException if divisor is zero.\n     */\n    fun divide(dividend: Double, divisor: Double): Double {\n        if (divisor == 0.0) throw IllegalArgumentException("Divisor cannot be zero")\n        return dividend / divisor\n    }\n}\n

\n\n

Step 2: Run the generation

\n

In the terminal, execute the command:

\n

./gradlew dokkaHtml

\n

After execution, the documentation will be generated in the build/dokka/html folder. Open index.html in your browser.

\n\n

Main Methods and Functions of Dokka (Gradle API)

\n\n

Dokka provides a rich API for customizing generation. Here are the main methods