kotlin - 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(...)-part 包含到文档中？当前版本的 Dokka 是否完全支持它？

---

交换或替换#没有做任何事情。.@sample@includeFunction

此外：

• 这是一个相关的问题，将近两年没有回答。
• 这是 2012 年的一些讨论，现在几乎完全由死链接组成。

Answer 1

该@sample标签放置在您要记录的函数或类的注释中，并附有如何调用或使用它的示例。

@sample将完全限定的类和函数名作为参数。当使用 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()

这是我想用示例记录的功能。

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!"
}

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

println(App().greeting())

在 dokka 样本输出中