Introducing “Codelet”: Automated insertion of example code into JavaDoc

Codelet (GitHub link) 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.

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


Source

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

If AdderDemo required command line parameters, you’d instead use

  {@.codelet.and.out com.github.aliteralmind.codelet.examples.adder.AdderDemo("command line params", true, 3)%eliminateCommentBlocksAndPackageDecl()}

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


Source

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


Source

/*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 is now available in beta. Please consider giving it a try, and posting your comments and criticisms in the GitHub issue tracker.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s