Codelet: Automated insertion of already unit-tested example code (its source code, console output, and input text-files) into JavaDoc, using inline taglets--Codelet makes it possible to have always accurate documentation. As with all inline taglets, codelets are automatically processed when generating your JavaDoc. Customizations include:

1. Displaying only a portion of an example's source code (code snippets).
2. Making the first appearance of a function, constructor, class, or field name into a clickable JavaDoc link.
3. Syntax highlighting with the SyntaxHighlighter JavaScript library (TO-DO).

Type	Example	Description
{@link com.github.aliteralmind.codelet.CodeletType#SOURCE_CODE {@.codelet}}	{@code {@.codelet fully.qualified.examples.ExampleClass}}	Replaced with all source-code lines from an example code's Java file.
{@link com.github.aliteralmind.codelet.CodeletType#CONSOLE_OUT {@.codelet.out}}	{@code {@.codelet.out fully.qualified.examples.ExampleClass}}     or {@code {@.codelet.out fully.qualified.examples.ExampleClass("command", -1, "line", true, "params")}}	Executes the example code, with optional command line parameters, and displays its console output.
{@link com.github.aliteralmind.codelet.CodeletType#SOURCE_AND_OUT {@.codelet.and.out}}	{@code {@.codelet.and.out fully.qualified.examples.ExampleClass}}	Prints both source-code and its output.
{@link com.github.aliteralmind.codelet.CodeletType#FILE_TEXT {@.file.textlet}}	{@code {@.file.textlet fully\qualified\examples\doc-files\input.txt}}	Replaced with all lines in a plain-text file, such as for displaying an example code's input.

Contents

1. Installation instructions
2. Examples:
   1. No customizer: A codelet with no customizations. This is also the full source code of the example class used in all below examples.
   2. A first example: "Hello Codelet!"
   3. Code snippet
   4. Custom customizer: Making function/constructor/class/field names into clickable JavaDoc links
3. Customizer function: The function itself, calling it from a taglet, and the object it returns: A {@link com.github.aliteralmind.codelet.CustomizationInstructions} object (line filter, alterer, template)
4. {@linkplain com.github.aliteralmind.codelet.CodeletTemplateBase Templates}: Configuring default templates, {@linkplain com.github.aliteralmind.codelet.UserExtraGapGetter custom gaps}, and {@linkplain com.github.aliteralmind.codelet.TemplateOverrides overrides}
5. Debugging Codelet:
   1. Configuring {@linkplain com.github.aliteralmind.codelet.CodeletBaseConfig#GLOBAL_DEBUG_LEVEL global} and {@linkplain com.github.aliteralmind.codelet.CodeletInstance#DEBUG_LEVEL_PREFIX_PREFIX taglet} debugging levels
   2. {@linkplain com.github.aliteralmind.codelet.CodeletBootstrap#NAMED_DEBUGGERS_CONFIG_FILE Named debuggers}: Extensive and specific control of debugging information, without the need for recompiling code.
   3. {@linkplain com.github.aliteralmind.codelet.CodeletBaseConfig#BLACK_WHITE_LIST_TYPE Blacklisting} codelets, either in a single file or entire package, to focus on the problem taglet.

Other:

1. Codelet is hosted by GitHib: Project page, issue tracker, Wiki
2. Generation reports: Full build, JavaDoc only
3. Other downloads: JavaDoc, source code (including build-files)
4. I use com.github.xbn.testdev.{@link com.github.xbn.testdev.VerifyApplicationOutput} to unit test applications.
5. Thanks go to fge and Michael for the technical comments and suggestions (fge came with lowercase "codelet"), to Gregg Stebben for the support, and especially to Sherrie.

Known issues, and major to-dos

1. Test and confirm {@linkplain com.github.aliteralmind.codelet.TemplateOverrides template overrides}
2. Test and confirm auto-gaps (such as SourceCodeTemplate).
3. Figure out how to implement syntax highlighting with the SyntaxHighlighter JavaScript library.
4. Configuration is loaded repeatedly in each run of {@code javadoc.exe}, although this does not affect reliability. It is likely an issue that won't go away.

  Codelet: Example: No customizer

This first example demonstrates a codelet with no customizer, displaying all lines, without change, followed by its output.

(This is the example class used throughout this documentation.)

The taglet:

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

Output (between the horizontal rules):

  Codelet: Example: Hello Codelet!: A basic use

This displays the above example class, but eliminates its package-declaration line and all multi-line comment blocks.

The taglet:

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

Output (between the horizontal rules):

This is a simple, self-contained, compilable example, which your users can copy, paste, compile, and run.

The customizer portion, which follows the {@linkplain com.github.aliteralmind.codelet.CodeletInstance#CUSTOMIZER_PREFIX_CHAR percent sign} ({@code '%'})

     eliminateCommentBlocksAndPackageDecl()

{@linkplain com.github.aliteralmind.codelet.BasicCustomizers#eliminateCommentBlocksAndPackageDecl(CodeletInstance, CodeletType) eliminates} all multi-line comments, including the license block and all JavaDoc blocks, and the package declaration line.

(This uses the {@linkplain com.github.aliteralmind.codelet.CodeletBaseConfig#DEFAULT_AND_OUT_TMPL_PATH default template}, which can be edited directly. A different template can be assigned to a single taglet by creating a custom customizer. The {@linkplain com.github.aliteralmind.codelet.TemplateOverrides template overrides} configuration file allows a different template to assigned to all taglets in a single file or entire package.)

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

is basically equivalent to all of the following:

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

and

     {@.file.textlet examples\com\github\aliteralmind\codelet\examples\adder\AdderDemo.java%eliminateCommentBlocksAndPackageDecl()}
     {@.codelet.out com.github.aliteralmind.codelet.examples.adder.AdderDemo}

({@linkplain com.github.aliteralmind.codelet.examples.TrivialTestClassForFileTextletWithCustomizer View the above.})

and

     {@.file.textlet C:\java_code\my_library\examples\com\github\aliteralmind\codelet\examples\adder\AdderDemo.java%eliminateCommentBlocksAndPackageDecl()}
     {@.codelet.out com.github.aliteralmind.codelet.examples.adder.AdderDemo}

  Codelet: Example: Displaying a "code snippet"

An alternative to a fully-working example is to display only a portion of the example code's source, using the {@link com.github.aliteralmind.codelet.BasicCustomizers#lineRange(CodeletInstance, CodeletType, Integer, Boolean, String, Integer, Boolean, String, String) lineRange} customizer:

The taglet:

{@.codelet.and.out com.github.aliteralmind.codelet.examples.adder.AdderDemo%lineRange(1, false, "Adder adder", 2, false, "println(adder.getSum())", "^      ")}

Output (between the horizontal rules):

It starts with (the line containing) {@code "Adder adder"}, and ends with the second {@code "println(adder.getSum())"}. This also eliminates the extra indentation, which in this case is six spaces.

The {@code false} parameters indicate the strings are literal. {@code true} treats them as regular expressions.

  Codelet: Example: Custom Customizer: Making function/constructor/class/field names into clickable JavaDoc links

[Go to: Notes and debugging tips, Putting it all together, full customizer versions one, two, three]

The final example displays the same line snippet from a previous example. Since it is not possible to know what strings should be made clickable, nor the method (or constructor, class, or field) it represents, this requires a custom customizer function. As a reminder, here is the original code-snippet:

The taglet:

{@.codelet.and.out com.github.aliteralmind.codelet.examples.adder.AdderDemo%lineRange(1, false, "Adder adder", 2, false, "println(adder.getSum())", "^      ")}

Output (between the horizontal rules):

Our goal is to link the first constructor ({@code "Adder()"}) and {@code "getSum()"} function.

All customizer functions return a {@link com.github.aliteralmind.codelet.CustomizationInstructions} object, which is made up of:

1. A {@linkplain com.github.aliteralmind.codelet.CustomizationInstructions#filter(FilteredLineIterator) filter}: Which lines should be kept?
2. An {@linkplain com.github.aliteralmind.codelet.CustomizationInstructions#alterer(AllTextLineAlterer) alterer}: What alterations should be made to the kept lines?
3. And a template: The context into which the fully-customized text is placed, and whose rendered output actually replaces the taglet.

The same filter and template as in the original example (as used by its customizer function: {@link com.github.aliteralmind.codelet.BasicCustomizers}.{@link com.github.aliteralmind.codelet.BasicCustomizers#lineRange(CodeletInstance, CodeletType, Integer, Boolean, String, Integer, Boolean, String, String) lineRange}) can also be used here:

1. Filter: {@link com.github.aliteralmind.codelet.NewLineFilterFor NewLineFilterFor}.{@link com.github.aliteralmind.codelet.NewLineFilterFor#lineRange(int, boolean, String, Appendable, Appendable, int, boolean, String, Appendable, Appendable, Appendable, Appendable, LengthInRange) lineRange}
2. Template: The {@linkplain com.github.aliteralmind.codelet.CustomizationInstructions#defaultOrOverrideTemplate(Appendable) default}

1. Escape all text for html display:
       {@link com.github.xbn.linefilter.alter.NewTextLineAltererFor}.{@link com.github.xbn.linefilter.alter.NewTextLineAltererFor#escapeHtml() escapeHtml}()
2. Eliminate the extra indentation, which is six spaces:
       {@link com.github.aliteralmind.codelet.alter.NewLineAltererFor}.{@link com.github.aliteralmind.codelet.alter.NewLineAltererFor#eliminateIndentationOrNull(String, Appendable) eliminateIndentationOrNull}("^      ", null)

And (3) replace the {@code Adder} constructor and (4) {@code getSum()} function to JavaDoc links.

To replace the {@code Adder} constructor call to a link, use

     {@link com.github.aliteralmind.codelet.alter.NewJDLinkForWordOccuranceNum}.{@link com.github.aliteralmind.codelet.alter.NewJDLinkForWordOccuranceNum#constructor(CodeletInstance, int, Class, String, Appendable, Appendable, Appendable, Appendable) constructor}(instance, 1, Adder.class, "(*)", null, null)

1. {@code 1} indicates the first occurance of {@code "Adder("} should be linked,
2. {@code "(*)"} is the constructor's parameter-list {@linkplain com.github.aliteralmind.codelet.simplesig.ConstructorParamSearchTerm search-term}, in this case meaning one or more of any type,
3. {@code Adder.class} is the link-target class, and
4. The {@code null} parameters are for optional debugging. Possible values include:
   1. {@code null}: No debugging is output
   2. {@code System.out}: Prints to the console.
   3. {@link com.github.aliteralmind.codelet.CodeletBaseConfig#getDebugApblIfOn(int, CodeletInstance) getDebugApblIfOn}{@code (3, instance)}
      outputs only when either the {@linkplain com.github.aliteralmind.codelet.CodeletBaseConfig#GLOBAL_DEBUG_LEVEL global} or {@linkplain com.github.aliteralmind.codelet.CodeletInstance#getDebugLevel() taglet debugging level} is set to three or greater.
   4. {@link com.github.aliteralmind.codelet.CodeletBaseConfig#getDebugApblIfOn(CodeletInstance, String) getDebugApblIfOn}{@code (instance, "Adder.constructor.link.replacer")}
      outputs only when the {@linkplain com.github.aliteralmind.codelet.CodeletBootstrap#NAMED_DEBUGGERS_CONFIG_FILE named debugger} called {@code "Adder.constructor.link.replacer"} is active. Making a named debug level active is done by setting it to either zero, or to a number less-than-or-equal to the current debugging level.

Simlarly, here is the {@code getSum()} function link alterer:

     NewJDLinkForWordOccuranceNum.{@link com.github.aliteralmind.codelet.alter.NewJDLinkForWordOccuranceNum#method(CodeletInstance, int, Class, String, Appendable, Appendable, Appendable, Appendable) method}(instance, 1, Adder.class, "getSum()", null, null)

Where {@code "getSum()"} is the function signature's {@linkplain com.github.aliteralmind.codelet.simplesig.MethodSigSearchTerm search-term}.

Putting it all together:

The taglet:

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

Output (between the horizontal rules):

(In this {@code overview-summary.html} file,
    {@code ":adderDemo_lineSnippetWithLinks()"}
must actually be
    {@code ":com.github.aliteralmind.codelet.examples.LineRangeWithLinksCompact#adderDemo_lineSnippetWithLinks()"}
because that is the class in which the customizer function exists (is contained). In the {@linkplain com.github.aliteralmind.codelet.examples.LineRangeWithLinksCompact full example} (click the left-arrow to return) it can be shortened to
    {@code ":adderDemo_lineSnippetWithLinks()"}
because one of the default customizer classes is the one containing the taglet--if it is indeed a class.)

The full customizer function (version 1 of 3):

Notes:

1. The {@link com.github.aliteralmind.codelet.CodeletInstance} and {@code com.github.aliteralmind.codelet.CodeletType} are required as the first and second parameters in all customizer functions. Both are ommitted from all taglet-calls.
2. Alterations are made in the the order they appear in the array.
3. To link to an external library, its package-list must be {@linkplain com.github.aliteralmind.codelet.CodeletBootstrap#EXTERNAL_DOC_ROOT_URL_FILE configured}.
4. Arbitrary alterers may be added to the array, such as {@linkplain com.github.xbn.linefilter.alter.NewTextLineAltererFor#literalReplacement(AlterationRequired, String, String, ReplacedInEachInput, Appendable, ValidResultFilter) literal} or {@linkplain com.github.xbn.linefilter.alter.NewTextLineAltererFor#replacement(AlterationRequired, Pattern, String, ReplacedInEachInput, Appendable, ValidResultFilter) regular expression} replacements, or {@linkplain com.github.xbn.linefilter.alter.NewTextLineAltererFor#prependLineNumber(int, String) prepending line numbers}
5. When using SyntaxHighlighter with the "<PRE> method", it is not possible to have any links, due to its limitation that all less-than characters ('<') must be html escaped.

The same function, with documentation on the available {@linkplain com.github.aliteralmind.codelet.CodeletBaseConfig#GLOBAL_DEBUG_LEVEL debugging} parameters (version 2 of 3):

And again, this time with automated {@linkplain com.github.aliteralmind.codelet.CodeletBootstrap#NAMED_DEBUGGERS_CONFIG_FILE named debuggers} (version 3 of 3, presented as a fully-working, ready-to-use class):

This requires all of the following lines to be added the named-debugger {@linkplain com.github.aliteralmind.codelet.CodeletBootstrap#NAMED_DEBUGGERS_CONFIG_FILE configuration file}:

To turn an item off, set it to {@code -1}. To turn it on, set it to zero.

LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.allalterer=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.elimindent=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.filter.blockend.validfilter=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.filter.blockend=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.filter.blockstart.validfilter=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.filter.blockstart=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.filter.linenums=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.filter.alllines=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.link.constructor.searchterm.doesmatch=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.link.constructor.searchterm=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.link.constructor.validfilter=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.link.constructor=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.link.getSum.searchterm.doesmatch=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.link.getSum.searchterm=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.link.getSum.validfilter=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.link.getSum=-1
LineRangeWithLinksAndNamedDebugs.adderDemo_lineSnippetWithLinks.template=-1

  Codelet: Installation

Codelet requires the 1.7 version of the {@code javadoc.exe} tool. The code whose JavaDoc has codelet-taglets in it has no version restrictions.

(For building, see XBN-Java's installation instructions. The Codelet build process is derived from XBN-Java's.)

Downloads for latest version: ${jd_project_version_number}

View Release notes (includes downloads and release notes for all previous versions)

1. The Codelet jar, with no external dependencies (choose exactly one):
   1. {@code x}{@code odelet_${jd_project_version_number}-all.jar}: Core classes, example code, and unit tests.
   2. {@code c}{@code odelet_${jd_project_version_number}.jar}: Core classes only.
2. {@code c}{@code odelet_${jd_project_version_number}_config_and_dependency_jars.jar}: All external jars required to use Codelet, including {@code tools.jar} from the JDK 1.7_51, which contains {@code com.sun.javadoc} and {@code com.sun.tools.doclets}.
3. {@code c}{@code odelet_${jd_project_version_number}-sources.jar}: Source code, including all files necessary for building Codelet.
4. {@code c}{@code odelet_${jd_project_version_number}-javadoc.jar}: JavaDoc documentation for local installation.

Steps

1. Add the necessary items from {@code codelet_${jd_project_version_number}_config_and_dependency_jars.zip} (download link above) to your classpath:

   INSTALLATION_DIR\codelet_${jd_project_version_number}_config_and_dependency_jars\dependency_jars\*
   INSTALLATION_DIR\codelet_${jd_project_version_number}-all.jar     (or {@code ".jar"})

2. Configure {@code javadoc} to recognize Codelet taglets
3. Configure Codelet

  Codelet: Installation: Custom taglets and the Codelet configuration directory

Executing {@code javadoc} in turn executes Codelet. Its four custom taglets must be registered, and the required Codelet system property must be passed to {@code javadoc.exe}:

1. {@link com.github.aliteralmind.codelet.CodeletBootstrap#CODELET_CONFIG_DIR_SYS_PROP_NAME codelet_config_dir}: The path to the directory in which all Codelet configuaration files exist. Must end with a file-separator (the value returned by System.getProperty("file.separator", "\\")).
.

Executing Codelet at the command-line:

{@code javadoc -taglet com.github.aliteralmind.codelet.taglet.SourceCodeTaglet -taglet com.github.aliteralmind.codelet.taglet.SourceAndOutTaglet -taglet com.github.aliteralmind.codelet.taglet.ConsoleOutTaglet -taglet com.github.aliteralmind.codelet.taglet.FileTextTaglet -J-Dcodelet_config_dir=C:\java_code\codelet_${jd_project_version_number}\${jd_project_codelet_config_dir}\}

Information on JavaDoc's {@code -J} flag, and {@code java}'s {@code -D} flag (for the {@code -D} link, scroll down a bit).

Executing Codelet with Apache Ant:

<javadoc packagenames="my.package" sourcepath="C:\java_code\" destdir="${dir_build_docs_javadoc}"
   additionalparam="-J-Dcodelet_config_dir=C:\java_code\codelet_${jd_project_version_number}\${jd_project_codelet_config_dir}\">
      <taglet name="com.github.aliteralmind.codelet.taglet.SourceCodeTaglet">
      <taglet name="com.github.aliteralmind.codelet.taglet.SourceAndOutTaglet">
      <taglet name="com.github.aliteralmind.codelet.taglet.ConsoleOutTaglet">
      <taglet name="com.github.aliteralmind.codelet.taglet.FileTextTaglet"/>
   </javadoc>

This assumes that Codelet is on your Ant-classpath.

  Codelet: Installation: Configuring Codelet itself

At a minimum, the following three values must be set in {@link com.github.aliteralmind.codelet.CodeletBaseConfig codelet.properties}:

1. {@link com.github.aliteralmind.codelet.CodeletBaseConfig#BASE_DIR_BASE_DIR base_dir_base_dir}: The root directory on which all other directory values are based on. This is used by other values with {@code ${BASE}}. Example value:
       C:\java_code\project_name\
2. {@link com.github.aliteralmind.codelet.CodeletBaseConfig#EXAMPLE_CLASS_SRC_BASE_DIR example_class_src_base_dir}: The directory in which the top-most package name of all example code resides. Example value
       ${BASE}examples\\
3. {@link com.github.aliteralmind.codelet.CodeletBaseConfig#ENCLOSING_CLASS_SRC_BASE_DIRS enclosing_class_src_base_dirs}: The directory in which the top-most package name of all codelet-taglet containing classes reside. Example value
       ${BASE}src\\,${BASE}test\\,${BASE}examples\\