1 Reply Latest reply: Jul 25, 2008 10:41 AM by thomas.behr RSS

    How to properly structure method JavaDoc comment format using Doclet API

    843810
      Wrote a custom doclet using the [Doclet API|http://java.sun.com/j2se/1.3/docs/tooldocs/javadoc/doclet/index.html] .

      The purpose for the doclet is to load Java source files and create stubs (which are identical Java source files but do not contain any method implementation details).

      Need the JavaDoc comments (located inside the newly created stub source file) to be properly formatted / match the format with the original source file using this doclet that I created...

      Here's my doclet:
      public class MyDoclet {
       
           private static String TAB = "\t";
       
           public static boolean start(RootDoc root) {
                ClassDoc[] classes = root.classes();
       
                // Parse through class or interface
                for (ClassDoc clazz : classes) {
                     Type superClass = clazz.superclassType();     
       
                     // Print Methods
                     MethodDoc[] methods = clazz.methods(); 
                     for (MethodDoc method : methods) {
                          Parameter[] parameters = method.parameters();
                          println();
                          if (!method.isPrivate()) {
                              if (!method.commentText().equals("") && method.commentText().length() > 1) {
                                          println(TAB + "/**");
                                          println(TAB + " * " + " " + method.commentText());
                                          println(TAB + " */");
                                    }
                                print(TAB + method.modifiers() + " "  
                                                               + method.returnType().simpleTypeName() + " " + method.name());
                                print("(");
                                for (int i=0; i < parameters.length; i++) {
                                        Parameter parameter = (Parameter) parameters;
                                    print(parameter.type().simpleTypeName() + " " + parameter.name());
                                    if (i != parameters.length - 1) {
                                         print(", ");
                                    }
                               }
                               print(")");
                               println(" {");
                               println("\n");
                               println(TAB + "}");
                          }
                     }
                }
                return true;
           }
      }
      For example, lets say I run it against this target source file:
      /**
      * The Inventory class contains the amounts of all the
      * inventory in the system. The types of
      * inventory in the system include coffee, milk, sugar
      * and chocolate.
      */
      public class Inventory {

      /**
      * Default constructor for Inventory
      * Sets all ingredients to 15 units
      */
      public Inventory() {
      }

      /**
      * Returns the units of coffee in the Inventory
      *
      * @return int
      */
      public int getAmtCoffee() {
      }

      /**
      * Sets the units of coffee in the Inventory
      *
      * @param int new units coffee
      */
      public void setAmtCoffee(int newCoffee) {
      }
      }
      The newly created Java source file's JavaDoc looks like this:
      /**
      * The Inventory class contains the amounts of all the
      inventory in the system. The types of
      inventory in the system include coffee, milk, sugar
      and chocolate.
      */
      public class Inventory {

      /**
      * Default constructor for Inventory
      Sets all ingredients to 15 units
      */
      public Inventory() {
      }

      /**
      * Returns the units of coffee in the Inventory
      @return int
      */
      public int getAmtCoffee() {
      }

      /**
      * Sets the units of coffee in the Inventory
      @param int new units coffee
      */
      public void setAmtCoffee(int newCoffee) {
      }
      }
      Notice how with the exception of the first line, the second line and subsequent lines are pushed to the left side of the screen and don't containing leading asterisks before them...
      
      This is definitely some type of weird formatting issue...
      
      What am I possibly doing wrong?
      
      Is there any easier way to correctly format the JavaDoc comments to match the target source file which is loaded by MyDoclet?
      
      Should I be using the com.sun.javadoc.SourcePosition.line() or com.sun.javadoc.SourcePosition.column() methods?
      
      Happy programming,
      
      Mike