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