kotlin - 多卡 : include code samples into package documentation

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 标记放置在您想要记录的函数或类的注释中，并提供如何调用或使用它的示例。

@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 输出的粗略近似值。

获取HelloWorld

有趣的 getHelloWorld()

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

println("你好，世界")

<小时/>

我发现以下引用资料很有帮助:

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

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