Package com.norconex.commons.lang.javadoc

Class IncludeTaglet

  • All Implemented Interfaces:
    Taglet
    public class IncludeTaglet
extends Object
implements Taglet

    {@nx.include} Include text from other JavaDoc documentation found in source files.

    Making comments eligible for inclusion

    The text to be included is taken from the declared type JavaDoc comment of the referenced class source file. The given text needs to be wrapped by a block tag such as BlockTaglet, HTMLTaglet, JSONTaglet, XMLTaglet, etc.

    If you have multiple blocks of text to include from a JavaDoc comment, you can add a reference anchor to it (a recommended practice). In the following example, the JavaDoc comment has two HTML blocks ready to be included by any other JavaDoc comments. 

      package com.somepackage;

  /**
   * <h1>How to create a list</h1>
   * <p>Two examples:</p>
   *
   * {@nx.html #ordered
   *   <ol>
   *     <li>An item.</li>
   *     <li>Another item.</li>
   *   </ol>
   * }
   *
   * {@nx.html #unordered
   *   <ul>
   *     <li>An item.</li>
   *     <li>Another item.</li>
   *   </ul>
   * }
   */
  public class MyClassWithReusableComments {
    //...
  }

    Including comments

    The {@nx.include ...} directive is used to reference other classes along with which comment block to include. The complete syntax is: 

     {@nx.include [class][@tagName][#reference]}

    Where each elements in square brackets are:

    Include tag elements
    class The fully qualified class name containing the comment to include. Required.
    @tagName The name of the block tag wrapping the comment. If there are multiple block tags with the same name in the class comment, the first one will be picked. Use #reference for more precision. At least one of @tagName and #reference need to be specified.
    #reference Matches the reference anchor defined in the included class comment. Those should be unique within a class comment so should be favored over @tagName when present. At least one of @tagName and #reference need to be specified.

    The following example will insert the two blocks defined in the previous example along with additional HTML. 

      /**
   * <p>
   *   Here are two types of HTML lists:
   * </p>
   * {@nx.html
   *
   *   <h1>Ordered List</h1>
   *   {@nx.include com.somepackage.MyClassWithReusableComments#ordered}
   *
   *   <h1>Unordered List</h1>
   *   {@nx.include com.somepackage.MyClassWithReusableComments#unordered}
   * }
   */
  public class MyClassIncludingComments {
    //...
  }

    One thing to keep in mind is the included text is taken as is. If you want to format it, you would need to wrap it yourself like above. Includes can be nested in any other @nx.* taglets.

    Since:
    2.0.0