Comments

<< Visitor Variations | Generating Java from the Shell >>

jADT files can have 2 broad categories of comments: internal and Java. Internal comments are completely ignored by the parser and have no effect on code generation. They start with # and continue to the end of the line. They're useful when you want to temporarily comment out a block of jADT definition.

Here's an example of an internal comment.

# This is an internal comment.  It's completely ignored by the parser
# blah de blah de blah

Java comments are the range of comments from Java: end of line, block, and JavaDoc. The parser will pick them up and pass them through to the generated code. Because the parser must be aware of them, there are only a few places where they are allowed. Java comments can go before a package declaration, before an import declaration, before a data type declaration, or before a constructor case. Java comments on constructor cases can appear before the punctuation ('=' and '|') or after. Java comments in any other location will cause a syntax error.

In a large team, most programmers will interact with the generated java more than the jADT files so JavaDoc comments on constructor cases are treated specially. Different parts of the generated code will get subsets of the JavaDoc provided for the jADT constructor case. The resulting Java class's doc will have @param and @return tags stripped, the resulting factory method will have no tags stripped, the resulting constructor method will have @return stripped, and each field will have only the documentation from its corresponding @param tag. In short, put the usual range of JavaDoc tags (@author, @since, @return, @param, etc) in JavaDoc comments on constructor cases and jADT will try to do something reasonable with them in the generated Java code.

Here's an example of using end of line and block comments on package and import declarations.

/*
 * Here's one sample comment.  It's a good spot for copyright and license info.
 * This one happens to be a block comment
 */
package com.pogofish.jadt.samples.comments.data

 // Imports can also have comments.  Mostly useful for the case when there is
 // no package declaration.
 // this one happens to be an end of line style comment
import java.util.*

Here's an example of using JavaDoc comments before a datatype declaration and after '=' and '|' punctuation on constructor cases.

/**
 * Here's one style of using JavaDoc
 *
 * @author me
 */
CommentStyle1 =
    /**
     * A constructor case
     *
     * @param arg1 some argument
     * @param arg2 some other argument
     * @return The Foo case of ConstructorStyle1
     */
     Foo(int arg1, int arg2) |
     /**
      * Another constructor case
      * @return The Bar case of ConstructorStyle1
      */
     Bar

Here's a similar example, but the JavaDoc comments are before '=' and '|' punctuation on constructor cases.

/**
 * Here's another style of using JavaDoc.
 *
 * @since the day after tomorrow
 */
CommentStyle2
    /**
     * A constructor case
     *
     * @param arg1 some argument
     * @param arg2 some other argument
     * @return The Foo case of ConstructorStyle2
     */
   = Foo(int arg1, int arg2)
     /**
      * Another constructor case
      * @return The Bar case of ConstructorStyle2
      */
   | Bar       

<< Visitor Variations | Generating Java from the Shell >>