如何在 JavaDoc 中显示我的示例代码，而无需手动复制/粘贴？

Question

我需要在我的库的 JavaDoc 文档中直接显示我的示例代码，包括它的输出。但是我想自动化这个过程，所以示例代码可以通过外部进程进行单元测试，并且不显示，除非它确实有效。

除了每次进行更改时手动复制粘贴源代码（和输出）之外，我还没有想出一种方法来做到这一点——这是无法管理的，因为我的各种示例类中现在有超过一百个示例类项目。或者，我可以简单地不显示这些示例，而是提供指向它们的链接。

这两种解决方案都是不可接受的，我希望可能有更好的方法来做到这一点。

如何自动插入示例代码，使其直接显示在 JavaDoc 中？

谢谢。

Answer 1

不完全是您想要的，但也许另一个有趣的方法是Play Framework 的文档：

他们使用 Markdown 记录并集成带有特殊注释的代码示例（在 Guidelines for writing Play documentation 中描述）。因此，所有代码示例都可以在包含在文档中之前进行测试。

可以在play-doc GitHub repository 中找到他们生成文档的（不幸的是自定义）解决方案。

Answer 2

这是我尝试用Codelet (GitHub link) 回答的问题。

Codelet 使用 taglets 自动将已经单元测试的示例代码插入到您的 JavaDoc 中。与所有 taglet 一样，Codelet 作为javadoc.exe 的一部分执行。它现在以测试版发布，（并且需要测试版测试人员！）。

有四个 Codelet taglets：

• {@codelet.and.out}：显示源代码，紧跟其输出
• {@codelet}：只显示源代码
• {@codelet.out}：仅显示输出
• {@file.textlet}：显示任何纯文本文件的内容，例如示例代码的输入。

common example:

{@.codelet.and.out com.github.aliteralmind.codelet.examples.adder.AdderDemo%eliminateCommentBlocksAndPackageDecl()}

它使用eliminateCommentBlocksAndPackageDecl() "customizer" 来消除包声明行和所有多行 cmets（例如许可证和 JavaDoc 块）。

输出（横线之间）：

---

示例

public class AdderDemo  {
   public static final void main(String[] ignored)  {

      Adder adder = new Adder();
      System.out.println(adder.getSum());

      adder = new Adder(5, -7, 20, 27);
      System.out.println(adder.getSum());
   }
}

输出

0
45

---

另一种方法是仅显示示例代码的一部分：A code snippet:

{@.codelet.and.out com.github.aliteralmind.codelet.examples.adder.AdderDemo%lineRange(1, false, "Adder adder", 2, false, "println(adder.getSum())", "^ ")}

这显示了与上面相同的示例，以（包含）Adder adder 的行开头，并以 second println(adder.getSum()) 结尾。这也消除了额外的缩进，在本例中为六个空格。

输出（横线之间）：

---

示例

Adder adder = new Adder();
System.out.println(adder.getSum());

adder = new Adder(5, -7, 20, 27);
System.out.println(adder.getSum());

输出：

0
45

---

所有小标签都接受定制器。

可以编写自己的自定义程序，例如，可以"linkify" function names、更改显示源和输出的模板，并对任何或所有行进行任意更改。示例包括以黄色突出显示某些内容，或进行正则表达式替换。

作为最后一个示例，作为与上述示例的对比，这里是从示例代码中盲目打印所有行的 taglet，没有任何更改。它使用no customizer:

{@.codelet.and.out com.github.aliteralmind.codelet.examples.adder.AdderDemo}

输出（横线之间）：

---

示例

/*license*\
   Codelet: Copyright (C) 2014, Jeff Epstein (aliteralmind __DASH__ github __AT__ yahoo __DOT__ com)

   This software is dual-licensed under the:
   - Lesser General Public License (LGPL) version 3.0 or, at your option, any later version;
   - Apache Software License (ASL) version 2.0.

   Either license may be applied at your discretion. More information may be found at
   - http://en.wikipedia.org/wiki/Multi-licensing.

   The text of both licenses is available in the root directory of this project, under the names "LICENSE_lgpl-3.0.txt" and "LICENSE_asl-2.0.txt". The latest copies may be downloaded at:
   - LGPL 3.0: https://www.gnu.org/licenses/lgpl-3.0.txt
   - ASL 2.0: http://www.apache.org/licenses/LICENSE-2.0.txt
\*license*/
package  com.github.aliteralmind.codelet.examples.adder;
/**
   <P>Demonstration of {@code com.github.aliteralmind.codelet.examples.adder.Adder}.</P>

   <P>{@code java com.github.aliteralmind.codelet.examples.AdderDemo}</P>

   @since  0.1.0
   @author  Copyright (C) 2014, Jeff Epstein ({@code aliteralmind __DASH__ github __AT__ yahoo __DOT__ com}), dual-licensed under the LGPL (version 3.0 or later) or the ASL (version 2.0). See source code for details. <A HREF=&quot;http://codelet.aliteralmind.com&quot;>{@code http://codelet.aliteralmind.com}</A>, <A HREF=&quot;https://github.com/aliteralmind/codelet&quot;>{@code https://github.com/aliteralmind/codelet}</A>
 **/
public class AdderDemo  {
   public static final void main(String[] ignored)  {

      Adder adder = new Adder();
      System.out.println(adder.getSum());

      adder = new Adder(5, -7, 20, 27);
      System.out.println(adder.getSum());
   }
}

输出：

0
45

---

Codelet 现已发布测试版。请考虑尝试一下，并在 GitHub 问题跟踪器中发布您的 cmets 和批评。