Page History

...

Comments are enclosed in between /** and */ and must immediately precede the java constructs (e.g. class, field, method) that are to be commented.
Each method should have a comment that describes the purpose of the method.
Each method should have a comment for each parameter, if any. The comment for a parameter has the form:
- @param parameter-name some-description
Each function method should have a comment for the returned object. The comment for the returned object has the form:
- @return some-description

Each method should have a comment for each exception thrown, if any. The comment for an exception has the form:

@exception exception-type some-description
Here are two files that at documented in javadoc style.

Code Block

/**
 * Represents a person who knows how to compute the number of months till his/her
 * next birthday.
 * @author DXN
 * @since Copyright 2009 by DXN - All rights reserved
 */
class Person {
    /**
     * birth month
     */
    int bm;

    /**
     * Computes the number of month until the next birthday given the current month.
     * @param cm an integer between 1 and 12 as the current month.
     * @return an integer between 0 and 11.
     */
    int nMonthTillBD (int cm) {
        return (bm - cm + 12) % 12;
    }
}

/**
 * JUnit test class to test all methods in class Person.
 * @author DXN
 * @since 02/20/2009
 */
class TestPerson extends TestCase {

    /**
     * Tests nMonthTillBD by covering three cases:
     * the current month is less than the birth month
     * the current month is equal to the birth month
     * the current month is greater than the birth month.
     */
    void test_nMonthTillBD() {

        Person peter = new Person(9); // a person born in September.

        assertEquals("Calling nMonthTillBD(2).", 7, peter.nMonthTillBD(2));
        assertEquals("Calling nMonthTillBD(9).", 0, peter.nMonthTillBD(9));
        assertEquals("Calling nMonthTillBD(12).", 9, peter.nMonthTillBD(12));
    }
}

Creating javadoc using

...

DrJava:

DrJava has incorporated the javadoc utility into its IDE. Since javadoc does not know anything about language levels, we will delay running the javadoc utility on our code until we switch to the Full Java language.

...

The above can be implemented in Java using the composite design pattern as follows.

Code Block

/**
 * Abstract list structure.
 */
abstract class IntList {
}

/**
 * Concrete empty list structure containing nothing.
 */
class EmptyIntList extends IntList {
}

/**
 * Concrete non-empty list structure containing an int, called first,
 * and a rest, 
  * which is a list structure.
 */
class ConsIntList extends IntList {
    int first;
    IntList rest;
}

...

Code Block

abstract class IntList {
    abstract returnType methodName(parameter_list); // returnType may be voidVoid
}

class EmptyIntList extends IntList {
    returnType methodName(parameter_list) {
        // base case code
    }
}

class ConsIntList extends IntList {
    int first;
    IntList rest;
    returnType methodName(parameter_list) {
        // ... first ...
        // ... rest.methodName(parameter_list)...
    }

}

...

Code Block

abstract class IntList {
    /**
     * Computes a String representation of this list wiht matching parentheses
      * as in Scheme.  For example, the list containing 1, 2 and 3 should return
      * (1, 2, 3) and the empty list should return ().
      * @return a non empty String consisting of elements in this list enclosed
      * in a pair of matching parenthesis, separated by commas.
      */
    abstract String listString();

    /**
     * Accumulator helper method for listString to compute the String
      * required representation of this list given the accumulated
      * String representation of the preceding list.
      * @param acc the accumulated String representation of the list that
      * precedes this list.
      * @return a non empty String consisting of elements in this list enclosed
      * in a pair of matching parenthesis, separated by commas.
      */
    abstract String listStringHelp(String acc);
}


class EmptyIntList extends IntList {

    /**
     * @return "()"*/
     */
    String listString() {
        return "()";
    }

    /**
     * @param acc the accumulated String representation of the list that
      * precedes this list.  For example "(5, 3"
      * @return a non empty String consisting of elements in this list enclosed
      * in a pair of matching parenthesis, separated by commas.  For example,
      * "(5, 3)"
      */
    String listStringHelp(String acc) {
        return acc + ")";
    }
}

class ConsIntList extends IntList {
    int first;
    IntList rest;

    /**
     * Calls on rest to perform the helper method listStringHelp passing it
      *   the accumulated String representation so far, which is "(" + first.
      * @return a non empty String consisting of elements in this list enclosed
      *    in a pair of matching parenthesis, separated by commas.
      */
    String listString() {
        return rest.listStringHelp("(" + first);
    }

    /**
     * @param acc the accumulated String representation of the list that
      *   precedes this list.  For example "(5, 3"
      * @return a non empty String consisting of elements in this list enclosed
      *   in a pair of matching parenthesis, separated by commas.  For example,
      *   "(5, 3)"
      */
    String listStringHelp(String acc) {
        return rest.listStringHelp(acc + ", " + first);
    }
}

/**
 * Testing empty lists.
 */
class TestEmptyIntList extends TestCase {

    /**
     */
    void test_listString() {
        EmptyIntList mt = new EmptyIntList();

        assertEquals(mt + ".listString()", "()", mt.listString());
    }
}

...

Child pages

Versions Compared

Old Version 3

New Version Current

Key

Creating javadoc using

DrJava: