JALOPY | Java Source Code Formatter Beautifier Pretty Printer
Overview • Download • Documentation • Plug-ins • Links • Contact
Features | History | Manual | FAQ | Javadoc
This page generated: June 8 2004
4.3.9. Javadoc
Prev | 4.3. Printer | Next
- ### 4.3.9. Javadoc Let's you control all Javadoc-related options. Refer to the Javadoc home page for more information about Sun's Javadoc tool. ### Incompatibility with Sun JDK 1.4 Note that the Javadoc parsing for Jalopy may not work properly under Sun JDK 1.4 with the Client JVM. This seems to be a problem with the garbage collection. You may want to enable the Server JVM as a workaround. #### 4.3.9.1. General Controls the general handling of Javadoc comments. Parse/Format comments Enables the parsing of existing Javadoc comments which in turn leads to a reformatting of the original comment style during the printing. The used parser mostly supports HTML 3.2 and is not loose in a sense most browsers are these days: tags not contained in the standard will produce errors. And you should always strive to produce well-formed HTML (it works for the `<p>`, `<li>`, `<dd>`, `<dt>` and `<dir>` tags, but anyway). Don't forget that the standard HTML metacharacters, such as less and greater signs (`<`, `>`) or the ambersand (`&`), ... and the commercial "at" sign (`@`) needs to be escaped if not used as part of another HTML or Javadoc tag. Table 4.2. Character entities
  Symbol | Numeric Entity | Named Entity | Description
  --- | --- | --- | ---
  & | &038; | &amp | Ambersand
  < | &060; | &lt; | Less than
  > | &062; | &gt; | Greater than
  @ | &064; |  | Commercial "at" sign
  Example 4.145. Escaping characters in Javadoc comments Don't use
      /**
       * @author <a href="mailto:first.last@company.com">first.last@company.com</a>
       */
  But rather use
      /**
       * @author <a href="mailto:first.last@company.com">first.last&064;company.com</a>
       */
- Correct tags Enables the auto-insertion or -removal of missing and obsolete Javadoc tags (all but the `@throws` tag, see below) and the correction of misspelled Javadoc tag names. Correct @throws tags Controls the auto-correction for `@throws` tags. If enabled, Jalopy enforces a distinct `@throws` tag for every exception thrown by a method/constructor. Thus, if a method only declares to throw an `IOException` but throws a `FileNotFoundException` (which is a subclass of the former) too, Jalopy will add a declaration for the latter. #### 4.3.9.2. Generation Controls the auto-generation of missing Javadoc comments. ##### 4.3.9.2.1. Element/Level Element/Level Lets you selectively enable the auto-generation of missing Javadoc comments for specific class elements and access levels. Include inner classes Enables the auto-generation feature for inner classes, too. The auto-generation does not apply to anonymous inner classes. ##### 4.3.9.2.2. Misc Let's you control miscellaneous Javadoc settings. Field comments in single line Let's you specify how Javadoc comments of fields, that fit into one line, should be printed. Example 4.146. Field Javadoc comment
      /**
       * What history policy should be used?
       */
      private History.Policy _historyPolicy = History.Policy.DISABLED;
  If enabled, Javadoc comments for fields will be printed in a single line, if possible. Example 4.147. Field Javadoc comment (shortened)
      /** What history policy should be used? */
      private History.Policy _historyPolicy = History.Policy.DISABLED;
Note that this switch does not take affect for field template comments, as template are not parsed but inserted as-is. Note further that the Javadoc parsing must be enabled for this feature to work. #### 4.3.9.3. Templates Let's you define templates to be inserted for the different declaration elements. Each element (Class, Interface, Constructor, Method and Field) has its own template. Depending on the element type, a template consists of up to five parts that together form a valid Javadoc comment. Note that the resulting comment will be inserted as-is, and it is your responsibility to define the templates in a consistent style. You can use variable expressions throughout your templates. Read Section 4.3.8, “Environment” for more information about this feature. #### 4.3.9.4. Custom Tags Allows the definition of custom Javadoc tags to aid the syntax checking of Javadoc comments, and enable the auto-correction of misspelled custom tag names. ##### 4.3.9.4.1. Standard Tags Allows the definition of custom Javadoc standard tag names. The current build-in Standard tags are: `@author`, `@deprecated`, `@exception`, `@param`, `@return`, `@see`, `@serial`, `@serialData`, `@serialField`, `@since`, `@throws`, `@todo`, `@version` Use the Add... and Remove buttons to add or remove items from the list. Valid standard tag names have the form `@[a-zA-Z]+`, e.g. `@exclude`. ##### 4.3.9.4.2. In-line Tags Allows the definition of custom Javadoc in-line tag names. The current build-in In-line tags are: `@docRoot`, `@inheritDoc`, `@link`, `@linkPlain`, `@value` Use the Add... and Remove buttons to add or remove items from the list. Valid in-line tag names have the form `@[a-zA-Z]+`, e.g. `@mylink`.
Prev | Up | Next
4.3.8. Environment | Home | 4.3.10. Header
to top