求Kotlin/Java中类似Rust注释代码编译功能的方案

核心思路 #

要实现注释里的示例代码兼具文档展示和逻辑校验功能，核心是让注释中的示例可转化为可执行测试用例，与主代码同步编译运行——当函数返回值或逻辑变更时，测试触发失败，否则作为有效文档保留。

Kotlin 实现方案 #

1. KDoc + JUnit 手动绑定（简单直接） #

在KDoc中编写示例代码，同时手动编写对应的JUnit测试用例，确保两者逻辑一致：

/**
 * some descriptive text
 * 
 * Example:
 * ```
 * val foo = bar()
 * check(foo == "bar") // Kotlin中check断言失败会抛出IllegalStateException，无需额外启动参数
 * ```
 *
 * @return "bar" as String
 */
fun bar() = "bar"

对应的JUnit测试：

import org.junit.Test
import kotlin.test.assertEquals

class BarTest {
    @Test
    fun testBarReturnValue() {
        val foo = bar()
        assertEquals("bar", foo)
    }
}

这种方式无需额外工具，只需手动维护注释示例与测试用例的同步性。

2. Dokka 自定义插件（自动同步） #

借助Kotlin官方文档生成工具Dokka的自定义插件，可自动抽取KDoc中的代码块并生成JUnit测试类。配置完成后，注释示例的变更会同步更新测试用例，函数逻辑变化时测试直接失败。

Java 实现方案 #

1. Javadoc + JUnit 手动绑定 #

在Javadoc中用代码块编写示例，配合JUnit测试用例校验：

/**
 * some descriptive text
 * 
 * <pre>{@code
 * String foo = bar();
 * // 推荐用JUnit断言替代Java默认assert，无需开启-ea参数
 * }</pre>
 *
 * @return "bar" as String
 */
public String bar() {
    return "bar";
}

对应的JUnit测试：

import org.junit.Test;
import static org.junit.Assert.assertEquals;

public class BarTest {
    @Test
    public void testBarReturnValue() {
        String foo = bar();
        assertEquals("bar", foo);
    }
}

2. Javadoc 测试生成工具 #

使用javadoc-testlet这类工具，可解析Javadoc中的代码示例并自动生成可执行测试用例，实现注释示例与测试逻辑的自动同步。

关键注意事项 #

• 无论手动还是自动方式，都要保证注释示例与测试逻辑完全一致，才能起到有效校验作用。
• Kotlin优先使用check、require或Kotlin Test库的断言方法，比Java默认assert更可靠；Java测试建议直接使用JUnit断言方法，避免依赖启动参数。

内容的提问来源于stack exchange，提问作者MomStopFlashing