How can I display my example code in JavaDoc, without having to manually copy/paste it?

问题

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.

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

Thanks.

回答1:

Not exactly what you want, but maybe another interesting approach is the documentation of the Play Framework:

They document with Markdown and integrate code samples with special annotations (described in the Guidelines for writing Play documentation). So all the code samples can be tested before they are included in the documentation.

Their (unfortunately custom) solution to generate the docs can be found in the play-doc GitHub repository.

回答2:

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

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!).

There are four Codelet taglets:

{@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 common example:

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

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):

Example

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

An alternative is to display only a portion of the example's code: A code snippet:

{@.codelet.and.out com.github.aliteralmind.codelet.examples.adder.AdderDemo%lineRange(1, false, "Adder adder", 2, false, "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):

Example

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

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

Output:

0
45

All taglets accept customizers.

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):

Example

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

Output:

0
45

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

来源：https://stackoverflow.com/questions/24516962/how-can-i-display-my-example-code-in-javadoc-without-having-to-manually-copy-pa

标签

java

documentation

javadoc