Dokka: include code samples into package documentation

Question

How do I include (tested, non-stale) code samples into Dokka package documentation?

---

More specifically, assuming that I have this configuration in my build.gradle.kts:

withType<DokkaTask> {
    outputFormat = "html"
    outputDirectory = "$buildDir/documentation"
    includes = listOf("packageDocumentation.md")
    samples = listOf("$rootDir/src/test/kotlin/some/project/TheSamples.kt")
}

And then some test code:

package some.project
import org.junit.jupiter.api.Test

class TheSamples {
    @Test
    fun helloWorldSample() {
        println("hello, world")
    }
}

and also a package documentation Markdown file:

# Package some.project

This is the documentation for some package.

@sample some.project.TheSamples#helloWorldSample

, how do I include the println(...)-part into the documentation? Is it supported at all in the current version of Dokka?

---

Exchanging # for . or replacing @sample by @includeFunction didn't do anything.

Furthermore:

• Here is a related question, left unanswered for almost two years.
• Here is some discussion from 2012, which by now consists almost entirely of dead links.

Answer 1

The @sample tag is placed in the comment of the function or class you want to document with a sample of how to call it, or use it.

@sample takes a fully qualified class and function name as an argument. When generating API docs with Dokka that reference is replaced with the content of the referenced function. Typically you'd have a function that you'd like to document with a sample of the test function, but here, your test function isn't calling anything to test, so this example may appear trivial, but this is the form:

/**
 * This is a function that I want to document with a sample.
 *
 * @sample some.project.TheSamples.helloWorldSample
 */
fun getHelloWorld() {
  // Do stuff
}

When dokka processes the files, the sample code is appended onto the information in the comment. Below is a rough approximation of dokka's HTML output.

getHelloWorld

fun getHelloWorld()

This is a function that I want to document with a sample.

println("hello, world")

---

I found the following references helpful:

https://livebook.manning.com/book/kotlin-in-action/appendix-b/7

https://medium.com/@rfletcher_96265/testable-samples-in-kotlin-api-docs-f7cd2da17c4f

Answer 2

I didn't understand the accepted answer, so I had to ask in the Kotlinlang Slack to try and figure it out. I got a response from Pablo García (Casía) that helped me understand, so maybe this will help someone too.

You need to add samples dir (or a list of files) to dokka task config

tasks.dokkaHtml.configure {
    outputDirectory.set(buildDir.resolve("dokka"))
    dokkaSourceSets {
        configureEach {
            samples.from("$projectDir/src/samples/kotlin/samples/samples.kt")
        }
    }
}

Then add a sample to that dir, for example:

package samples

import demo.App

class GreeterExample {
    fun greeting() {
        println(App().greeting())
    }
}

And use it in your code doc:

package demo

class App {
    /**
     * Greeting
     *
     * @sample samples.GreeterExample.greeting
     *
     * @return Will return the string `Hello World!`
     */
    fun greeting(): String = "Hello World!"
}

After you generate the dokka output with ./gradlew dokkaHtml you will see

println(App().greeting())

in dokka sample output