Writing Documentation for a Kotlin Project: From A to Z

Introduction: Why Documentation is Important for a Kotlin Project

Writing documentation is not just a formality, but a key element of a successful Kotlin project. Well-documented code accelerates the onboarding of new developers, simplifies maintenance, and reduces the number of errors. Kotlin, being a modern language, offers powerful tools for creating documentation: KDoc (an analog of JavaDoc) and Dokka (a documentation generator). In this article, we will break down the complete cycle of writing documentation for a Kotlin project: from code comments to publishing the finished documentation.

Regardless of whether you are working on a library, API, or internal application, following the best practices of documentation will make your code clear and accessible. Let's start with the basics.

KDoc Basics: Syntax and Structure

KDoc is a markup language for documenting Kotlin code. It is based on JavaDoc but adapted to Kotlin's features: null-safety, extension functions, properties, and lambdas. KDoc comments start with /** and end with */.

Basic Structure of a KDoc Comment

Each KDoc comment consists of a description and optional tags. The main tags are:

\n
• @param — description of a function parameter
\n
• @return — description of the return value
\n
• @throws or @exception — description of an exception
\n
• @see — reference to another element
\n
• @sample — insertion of a code example
\n
• @property — description of a class property
\n
• @constructor — description of a constructor
\n
• @receiver — description of the receiver for extension functions
\n

Example of a simple KDoc comment:

/**\n * Calculates the factorial of a given number.\n *\n * Uses an iterative approach to avoid stack overflow.\n * Works only with non-negative integers.\n *\n * @param n A non-negative integer for which the factorial is calculated\n * @return The factorial of the number n (n!)\n * @throws IllegalArgumentException if n < 0\n */\nfun factorial(n: Int): Long {\n    require(n >= 0) { "n must be non-negative" }\n    var result = 1L\n    for (i in 2..n) {\n        result *= i\n    }\n    return result\n}

Documenting Properties and Classes

For classes and properties, use the @property tag:

/**\n * Represents a system user.\n *\n * @property id Unique user identifier\n * @property name Full user name\n * @property email Email address\n * @property isActive Account activity flag\n */\ndata class User(\n    val id: Long,\n    val name: String,\n    val email: String,\n    val isActive: Boolean = true\n)

Generating Documentation with Dokka

Dokka is the official tool for generating Kotlin documentation. It supports several output formats: HTML, Markdown, Javadoc, and JSON. Dokka can handle multiplatform projects and correctly displays Kotlin-specific constructs.

Setting up Dokka in Gradle

To add Dokka to a project, include the plugin in build.gradle.kts:

plugins {\n    id("org.jetbrains.dokka") version "1.9.20"\n}\n\ntasks.dokkaHtml {\n    outputDirectory.set(buildDir.resolve("dokka"))\n    moduleName.set("My Kotlin Library")\n}\n\ntasks.dokkaJavadoc {\n    outputDirectory.set(buildDir.resolve("javadoc"))\n}

After that, run the command ./gradlew dokkaHtml — the documentation will be generated in the build/dokka folder.

Advanced Dokka Features

Dokka supports customization of the appearance, inclusion/exclusion of packages, and adding additional pages. Example of a configuration with custo