java - 有没有办法在javadoc中嵌入文件或部分文件的内容

在编写单元测试时，我将它们视为验证代码行为是否符合预期的机制，以及作为如何使用代码的已记录示例。因此，我很乐意将测试类的内容作为示例。所以像这样：

/**
 * Foos the bar
 * @example FooBarTest#testFooingBar()
 * @param bar The {@link Bar} to foo
 * return The fooed {@code Bar}
 */
public Bar fooBar(Bar bar)
{
   // Completely foo the bar
}

然后，当呈现此内容时，将在javadoc中看到FooBarTest.testFooingBar（）的内容。

我做了一些谷歌搜索，什么也没看到。那么有什么办法可以做到这一点（也许是Maven插件）？

最佳答案

我刚刚完成了一个Beta版的库，就可以做到这一点。它称为Codelet。这是我刚刚在this question中发布的答案：

这是我尝试使用Codelet（GitHub link）回答的问题。

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

有四个Codelet标签：

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

A common example：

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

它使用eliminateCommentBlocksAndPackageDecl()“ customizer”来消除包声明行和所有多行注释（例如license和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开始，以第二个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，更改显示源和输出的模板以及对任意行或所有行进行任意更改。例如，以黄色突出显示某些内容，或进行正则表达式替换。

作为最后一个示例，并且与上述示例相反，这里的标签是盲目地打印示例代码中的所有行，而无需进行任何更改。它使用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 &quot;LICENSE_lgpl-3.0.txt&quot; and &quot;LICENSE_asl-2.0.txt&quot;. 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在beta中，但相当稳定。请考虑尝试一下，并在GitHub问题跟踪器中发表您的评论和批评。

谢谢。