Title

Next: Misc

title

5.6.1.12 JavaDocs

Jindent is able to create missing JavaDoc comments defined by user templates. These templates can be inserted for all kind of declarations.
Additionally obsolete JavaDoc tags can be removed or missing JavaDoc tags can be completed.

title

5.6.1.12.1 Templates

JavaDoc insertion options are available for the following declaration accessors:

public
private
protected
friendly

JavaDoc insertion will be proceed by templates. They can be defined for:

classes
interfaces
annotation types
enumerations
fields
methods
constructors

Please note that all JavaDoc templates can contain environment variables.
For details about environment variables please refer to:

Insert missing tags in existing JavaDocs

Checks method/constructor JavaDocs and if necessary inserts missing JavaDoc tags.
Jindent is able to recognize the absence of the following JavaDoc tags:

@param of constructors/methods
@throws or @exception of constructors/methods
@return of methods

For JavaDoc insertions method/constructor templates below will be used.

Delete obsolete tags from existing JavaDocs

Checks method/constructor JavaDocs from input source codes and deletes obsolete JavaDoc tags.
Jindent is able to recognize if following JavaDoc tags are obsolete:

@param of constructors/methods
@throws or @exception of constructors/methods
@return of methods

public

Enables template insertion of JavaDocs for public class declarations.

See also:

Top template

friendly

Enables template insertion of JavaDocs for friendly class declarations.

See also:

Top template

protected

Enables template insertion of JavaDocs for protected class declarations.

See also:

Top template

private

Enables template insertion of JavaDocs for private class declarations.

See also:

Top template

JavaDoc template for class declarations.

JavaDoc templates for classes are divided into sub-templates.

Example templates:

Top Template:

				/**                                     

				 * Class $declarationName$              

				 *

Parameter Separator Template:

Parameter Template:

* @param $paramName$

Bottom Template:

				 *                                      

				 * @version    $version$ $date$         

				 * @author     $author$                 

				 */

And the generated JavaDoc insertion with looks like:

				/**                                          <- Top Template, line 1

				 * Class TestClass                           <- Top Template, line 2

				 *                                           <- Top Template, line 3

				 *                                           <- Parameter Separator Template, line 1

				 * @param <T>                                <- Parameter Template, line 1

				 *                                           <- Bottom Template, line 1

				 * @version    1.3 2005-02-14                <- Bottom Template, line 2

				 * @author     Ren Hoek                      <- Bottom Template, line 3

				 */                                          <- Bottom Template, line 4

				public class TestClass<T> {             

				    ...                                 

				}

In this example version and author are user defined environment variables.
Variable date is a special environment variable and represents the current date. declarationName contains the name of the corresponding class.

Please note: the param separation template will only be inserted if the class contains generic parameters.

If a sub-template is not needed, for instance the separation templates, then just leave this template empty and it won't be inserted.

Parameter separator template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Parameter template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Bottom template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

public

Enables template insertion of JavaDocs for public interface declarations.

See also:

Top template

friendly

Enables template insertion of JavaDocs for friendly interface declarations.

See also:

Top template

protected

Enables template insertion of JavaDocs for protected interface declarations.

See also:

Top template

private

Enables template insertion of JavaDocs for private interface declarations.

See also:

Top template

JavaDoc template for interface declarations.

JavaDoc templates for interfaces are divided into sub-templates.

Example templates:

Top Template:

				/**                                     

				 * Interface $declarationName$          

				 *

Parameter Separator Template:

Parameter Template:

* @param $paramName$

Bottom Template:

				 *                                      

				 * @version    $version$ $date$         

				 * @author     $author$                 

				 */

And the generated JavaDoc insertion with looks like:

				/**                                          <- Top Template, line 1

				 * Interface ITest                           <- Top Template, line 2

				 *                                           <- Top Template, line 3

				 *                                           <- Parameter Separator Template, line 1

				 * @param <T>                                <- Parameter Template, line 1

				 *                                           <- Bottom Template, line 1

				 * @version    1.3 2005-02-14                <- Bottom Template, line 2

				 * @author     Ren Hoek                      <- Bottom Template, line 3

				 */                                          <- Bottom Template, line 4

				public interface ITest<T> {             

				    ...                                 

				}

In this example version and author are user defined environment variables.
Variable date is a special environment variable and represents the current date. declarationName contains the name of the corresponding class.

Please note: the param separation template will only be inserted if the interface contains generic parameters.

If a sub-template is not needed, for instance the separation templates, then just leave this template empty and it won't be inserted.

Parameter separator template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Parameter template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Bottom template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

public

Enables template insertion of JavaDocs for public annotation types.

See also:

Template

friendly

Enables template insertion of JavaDocs for friendly annotation types.

See also:

Template

protected

Enables template insertion of JavaDocs for protected annotation types.

See also:

Template

private

Enables template insertion of JavaDocs for private annotation types.

See also:

Template

JavaDoc template for interface declarations.

Example template:

				/**                                     

				 * Annotation $declarationName$         

				 *                                      

				 * @version    $version$ $date$         

				 * @author     $author$                 

				 */

And the generated JavaDoc insertion looks like:

				/**                                     

				 * Annotation TestAnnotation            

				 *                                      

				 * @version    1.3 2005-02-14           

				 * @author     Ren Hoek                 

				 */                                     

				public @interface TestAnnotation {      

				    ...                                 

				}

In this example version and author are user defined environment variables.
Variable date represents the current date and declarationName the name of the corresponding annotation type.

public

Enables template insertion of JavaDocs for public enumerations.

See also:

Template

friendly

Enables template insertion of JavaDocs for friendly enumerations.

See also:

Template

protected

Enables template insertion of JavaDocs for protected enumerations.

See also:

Template

private

Enables template insertion of JavaDocs for private enumerations.

See also:

Template

JavaDoc template for enum declarations.

Example template:

				/**                                     

				 * Enum $declarationName$               

				 *                                      

				 * @version    $version$ $date$         

				 * @author     $author$                 

				 */

And the generated JavaDoc insertion looks like:

				/**                                     

				 * Enum TestEnumeration                 

				 *                                      

				 * @version    1.3 2005-02-14           

				 * @author     Ren Hoek                 

				 */                                     

				public enum TestEnumeration {           

				    ...                                 

				}

In this example version and author are user defined environment variables.
Variable date represents the current date and declarationName the name of the corresponding enumeration.

public

Enables template insertion of JavaDocs for public field declarations.

See also:

Template

friendly

Enables template insertion of JavaDocs for friendly field declarations.

See also:

Template

protected

Enables template insertion of JavaDocs for protected field declarations.

See also:

Template

private

Enables template insertion of JavaDocs for private field declarations.

See also:

Template

JavaDoc template for field declarations.

Example template:

/** Field $declarationName$ ... */

And the generated JavaDoc insertion looks like:

				/** Field myField ... */                

				public int myField;

Environment variable declarationName represents the name of the corresponding field.

Sort exceptions in JavaDoc templates

Sorts exceptions in alphabetical order within JavaDoc templates for methods and constructors.

public

Enables template insertion of JavaDocs for public constructor declarations.

See also:

Top template

friendly

Enables template insertion of JavaDocs for friendly constructor declarations.

See also:

Top template

protected

Enables template insertion of JavaDocs for protected constructor declarations.

See also:

Top template

private

Enables template insertion of JavaDocs for private constructor declarations.

See also:

Top template

JavaDoc template for constructor declarations.

Since JavaDoc templates for interfaces and classes are pretty simple, templates for constructors and methods are divided into sub-templates.

Example templates:

Top Template:

				/**                                     

				 * Constructor $declarationName$ ...    

				 *

Parameter Separator Template:

* ------------------------------------

Parameter Template:

				 * @param $paramName$, $paramType$      

				 *        We need more space for params 

				 *

Exception Separator Template:

* ------------------------------------

Exception Template:

* @throws $exceptionName$

Bottom Template:

And the generated JavaDoc insertion with sorted exceptions looks like:

				/**                                          <- Top Template, line 1

				 * Constructor Demo ...                      <- Top Template, line 2

				 *                                           <- Top Template, line 3

				 * ------------------------------------      <- Parameter Separator Template, line 1

				 * @param a, int                             <- Parameter Template, line 1

				 *        We need more space for params      <- Parameter Template, line 2

				 *                                           <- Parameter Template, line 3

				 * @param b, String                          <- Parameter Template, line 1

				 *        We need more space for params      <- Parameter Template, line 2

				 *                                           <- Parameter Template, line 3

				 * ------------------------------------      <- Exception Separator Template, line 1

				 * @throws AException                        <- Exception Template, line 1

				 * @throws BException                        <- Exception Template, line 1

				 * @throws CException                        <- Exception Template, line 1

				 */                                          <- Bottom Template, line 1

				public Demo(int a, String b) throws BException, AException, CException {

				    ...                                 

				}

Please note: the param separation template will only be inserted if the constructor contains parameters. The same applies to exception separation templates and exceptions.

If a sub-template is not needed, for instance the separation templates, then just leave this template empty and it won't be inserted.

Parameter separator template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Parameter template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Exception separator template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Exception template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Bottom template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

public

Enables template insertion of JavaDocs for public method declarations.

See also:

Top template

friendly

Enables template insertion of JavaDocs for friendly method declarations.

See also:

Top template

protected

Enables template insertion of JavaDocs for protected method declarations.

See also:

Top template

private

Enables template insertion of JavaDocs for private method declarations.

See also:

Top template

JavaDoc template for method declarations.

Since JavaDoc templates for interfaces and classes are much simpler, templates for constructors and methods are divided into sub-templates.

Example templates:

Top Template:

				/**                                     

				 * Method $declarationName$ ...         

				 *

Parameter Separator Template:

Parameter Template:

* @param $paramName$, $paramType$

Return Template:

				 * @return a value of $returnType$ ...  

				 *

Exception Separator Template:

Exception Template:

* @throws $exceptionName$

Bottom Template:

				 *                                      

				 * some space here ...                  

				 */

And the generated JavaDoc insertion with non-sorted exceptions looks like:

				/**                                          <- Top Template, line 1

				 * Method calculate ...                      <- Top Template, line 2

				 *                                           <- Top Template, line 3

				 *                                           <- Parameter Separator Template, line 1

				 * @param a, int                             <- Parameter Template, line 1

				 * @param b, String                          <- Parameter Template, line 1

				 *                                           <- Exception Separator Template, line 1

				 * @return a value of float ...              <- Return Template, line 1

				 *                                           <- Return Template, line 2

				 * @throws BException                        <- Exception Template, line 1

				 * @throws AException                        <- Exception Template, line 1

				 * @throws CException                        <- Exception Template, line 1

				 *                                           <- Bottom Template, line 1

				 * some space here ...                       <- Bottom Template, line 2

				 */                                          <- Bottom Template, line 3

				public float calculate(int a, String b) throws BException, AException, CException {

				    ...                                 

				}

Please note: the param separation template will only be inserted if the method contains parameters. The same applies to exception separation templates and exceptions.

If a sub-template is not needed, for instance the separation templates, then just leave this template empty and it won't be inserted.

Parameter separator template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Parameter template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Return Template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Exception separator template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Exception template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.

Bottom template

Sub-template for JavaDoc insertion. Please refer to "Top template" for a detailed example.