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