I just finished a project I've been working on for three years, and I'd like to introduce it to you. Hopefully a Java library developer, someone out there somewhere, will find this useful.

(And if someone has some advice on how to actually get people using this project, it would be much appreciated!)

Thanks for listening.


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.Add erDemo%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.Add erDemo("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.Add erDemo%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.Add erDemo}

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
   - [url=http://en.wikipedia.org/wiki/Multi-licensing]Multi-licensing - Wikipedia, the free encyclopedia[/url].
 
   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: [url]https://www.gnu.org/licenses/lgpl-3.0.txt[/url]
   - ASL 2.0: [url]http://www.apache.org/licenses/LICENSE-2.0.txt[/url]
\*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. [URL=&quot;http://codelet.aliteralmind.com&quot;>{@code http://codelet.aliteralmind.com}[/URL], [URL=&quot;https://github.com/aliteralmind/codelet&quot;>{@code https://github.com/aliteralmind/codelet}[/URL]
 **/
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.