Dokka：将代码示例包含到包文档中

Question

如何将（经过测试的、非陈旧的）代码样本包含到 Dokka 包文档中？

更具体地说，假设我的 build.gradle.kts:

中有此配置

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

然后是一些测试代码：

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

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

还有一个包文档 Markdown 文件：

# Package some.project

This is the documentation for some package.

@sample some.project.TheSamples#helloWorldSample

，如何将 println(...) 部分包含到文档中？当前版本的 Dokka 完全支持它吗？

将 # 替换为 . 或将 @sample 替换为 @includeFunction 没有任何效果。

此外：

此处 is a related question，将近两年未得到答复。
这里 is some discussion from 2012，现在几乎完全由死链接组成。

Answer 1

@sample 标记放在函数的注释中或 class 您想要记录如何调用或使用它的示例。

@sample 将完全限定的 class 和函数名称作为参数。使用 Dokka 生成 API 文档时，该引用将替换为引用函数的内容。通常你有一个函数，你想用测试函数的样本来记录，但在这里，你的测试函数没有调用任何东西来测试，所以这个例子可能看起来很简单，但它是这样的形式：

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

dokka处理文件时，示例代码附加在评论信息中。下面是 dokka 的 HTML 输出的粗略估计。

getHelloWorld

有趣的 getHelloWorld()

这是一个我想用示例记录的函数。

println("hello, world")

我发现以下参考资料很有帮助：

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

我不明白已接受的答案，所以我不得不在 Kotlinlang Slack 中提问，试图找出答案。我从 Pablo García (Casía) 那里得到了帮助我理解的回复，所以也许这对其他人也有帮助。

您需要将示例目录（或文件列表）添加到 dokka 任务配置中

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

然后将示例添加到该目录，例如：

package samples

import demo.App

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

并在您的代码文档中使用它：

package demo

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

使用 ./gradlew dokkaHtml 生成 dokka 输出后，您将看到

println(App().greeting())

在 dokka 示例输出中

Dokka：将代码示例包含到包文档中

Dokka: include code samples into package documentation

kotlin

kdoc

kotlin-dokka