如何使Javadocs中的代码示例保持最新

我正在开发一个小型库，该库提供基本的，众所周知的字符串指标的实现。主要是为了我自己的教育。因此，只要有空闲时间，开发就会发生。

因此，我已经完成了大多数流程的自动化工作，因此我可以不费吹灰之力就发布一个版本。但是，维护Java文档仍然是一个负担，因为它包含示例。

随着API的发展，我不得不一次又一次地手动检查每个示例。有一个更好的方法吗？

我已经考虑过将文档和示例移到一个单独的项目中（例如Caliper Tutorial），以便可以将其与常规代码一起重构和编译。但是，这确实使文档脱离了它所涉及的类。

嗯是的。我也想吃蛋糕。：D

 * <h2>Tokenization</h2>
 * 
 * Tokenization cuts up a string into tokens e.g.
 * <code>chilperic ii son of childeric ii</code> is tokenized into
 * <code>[chilperic, ii, son, of,
 * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing
 * the individual tokens e.g.
 * <code>[ch,hi,il,il,lp,pe,er,ri,ic, ii, so,on, of, ch,hi,il,ld,de,er,ri,ic, ii]</code>
 * <p>
 * 
 * <pre>
 * <code>
 * {@code
 *  return new StringMetricBuilder()
 *          .with(new SimonWhite<String>())
 *          .tokenize(new Whitespace())
 *          .tokenize(new QGram(2))
 *          .build();
 * }
 * </code>
 * </pre>
 * 
 * <p>

如果上面太抽象了。这是一个文档样本。目前，我正在按照有效Java的建议添加静态构造函数，例如Tokenizers.createQGram(2)在折旧构造函数方法的同时。每次我做这样的事情时，我都必须更新上面的示例代码，并检查它是否仍然有效。

这可能无法回答您的问题-根据在文档中包含这些示例的“要求”而定。

也许您可以换个角度：在JUnit测试中提供示例。（也许甚至是com.examples之类的包）注释中的代码存在的问题是，您的IDE在大多数情况下会忽略它。但是您的IDE将验证JUnit测试中的代码。这样，您可以确保代码示例是“正确的”-测试将不会编译，或者如果您未更新它们就会失败。

我不是Javadocs的向导，但是也许可以使用其中的示例代码将源文件的文档链接到JUnit文件。我真的不知道从哪里开始。粗略的谷歌搜索给我看了@see标签。我在一个项目中对其进行了测试，但在生成后并未在实际的Javadoc中对其进行测试。

这肯定需要进行一些前期的研究，但我真的认为，从长远来看，如果您的代码示例实际上是编译的，那么情况会更好。

作为目标，您还可以在运行JUnit示例时增加代码覆盖率。这样，您一眼就能知道示例覆盖了多少代码库。