如何在JavaDoc中显示示例代码，而无需手动复制/粘贴？ [英] How can I display my example code in JavaDoc, without having to manually copy/paste it?

问题描述

我需要在我的库的JavaDoc文档中直接显示我的示例代码，包括其输出。但是我想自动化此过程，因此示例代码可以通过外部进程进行单元测试，除非实际工作，否则不显示 。

I need to display my example code directly in my library's JavaDoc documentation, including its output. But I want to automate this process, so the example code can be unit tested by an external process, and not displayed unless it actually works.

我还没有想到这样做，除非手动复制粘贴源代码（和输出）每次进行更改 - 这是无法管理的，因为现在已经有超过一百个示例类在我的各种项目。或者，我可以简单地不显示这些示例，而是提供一个链接。

I have not figured out a way to do this except by manually copy-pasting the source code (and output) each time a change is made--which is unmanageable given there are now well above a hundred example classes in my various projects. Alternatively I could simply not display those examples, but instead provide a link to them.

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

Both of these solutions are unacceptable, and I am hoping there might be a better way to do this.

如何自动插入示例代码，因此它直接显示在您的JavaDoc？

How do you automate the insertion of your example code, so it is displayed directly in your JavaDoc?

谢谢。

推荐答案

这是我试图用 Codelet （ GitHub link

This is the question I've tried to answer with Codelet (GitHub link).

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

Codelet automates the insertion of already unit-tested example code into your JavaDoc, using taglets. As with all taglets, Codelet is executed as part of javadoc.exe. It is now released in beta, (and needs beta testers!).

有四个Codelet标签：

There are four Codelet taglets:

• {@ codelet.and.out} ：立即显示源代码，然后显示其输出


• {@ codelet} ：仅显示源代码


• {@ codelet.out} ：仅显示输出


• {@ file.textlet} ：显示任何纯文本文件的内容，如输入一个示例代码。

• {@codelet.and.out}: Displays source code immediately followed by its output
• {@codelet}: Displays source code only
• {@codelet.out}: Displays output only
• {@file.textlet}: Displays the contents of any plain-text file, such as the input for an example code.

A 常见示例：

{@。 .and.out com.github.aliteralmind.codelet.examples.adder.AdderDemo％eliminationCommentBlocksAndPackageDecl（）}

其中使用 eliminationCommentBlocksAndPackageDecl（）customizer消除包声明行和所有多行注释（如l许可证和JavaDoc块）。

which uses the eliminateCommentBlocksAndPackageDecl() "customizer" to eliminate the package declaration line and all multi-line comments (such as the license and JavaDoc blocks).

输出（横向规则之间）：

Output (between the horizontal rules):

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());
   }
}

输出

Output

0
45

---

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

{@ .codelet.and.out com.github.aliteralmind.codelet.examples.adder.AdderDemo％lineRange（1，false，Adder adder，2，false，println（adder.getSum（）），^）

这显示了与上述相同的示例，从（包含）行开始加法器加法器，并以第二个 println（adder.getSum（））结尾。这也消除了额外的缩进，在这种情况下是六个空格。

This displays the same example as above, starting with (the line containing) Adder adder, and ending with the second println(adder.getSum()). This also eliminates the extra indentation, which in this case is six spaces.

输出（横向规则之间）：

Output (between the horizontal rules):

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

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

输出：

Output:

0
45

---

所有taglet都接受自定义工具。

---

All taglets accept customizers.

可以编写自己的自定义工具，例如可以<一个href =http://aliteralmind.com/docs/computer/programming/codelet/documentation/javadoc/overview-summary.html#xmpl_links =nofollow>linkify函数名称，更改显示源和输出的模板，并对任何或所有行进行任意改动。示例包括以黄色突出显示某些东西，或进行正则表达式替换。

It is possible to write your own customizers which, for example, can "linkify" function names, change the template in which source-and-output is displayed, and do any arbitrary alteration to any or all lines. Examples include highlighting something in yellow, or making regular expression replacements.

作为最后一个例子，与上述相反，这里是盲目打印所有行的标签从示例代码，没有任何更改。它使用无自定义工具：

As a final example, and as a contrast to those above, here is the taglet that blindly prints all lines from an example code, without any changes. It uses no customizer:

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

输出（横向规则之间）：

Output (between the horizontal rules):

/*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());
   }
}

输出：

Output:

0
45

---

Codelet现在以测试版发布。请考虑尝试，并在GitHub问题跟踪器中发表您的意见和批评。

---

Codelet is now released in beta. Please consider giving it a try, and posting your comments and criticisms in the GitHub issue tracker.

这篇关于如何在JavaDoc中显示示例代码，而无需手动复制/粘贴？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！