Subversion Repositories HomeAutomation

Comment all public and protected classes, fields & methods with JavaDoc!

Method/Function example:

/**
 * Here goes the function description. Be short, but precise.
 * Wrap the lines so things look nice. Don't forget to finish
 * every sentence with a dot (or else, JavaDoc might fail).
 *
 * @param someString Here goes a description for the
 * "someString"-parameter. Wrap the lines as usual, and don't
 * forget to comment what a value of "null" means (if the
 * parameter is an Object that is).
 *
 * @param someInt Here goes the description for the "someInt"-
 * parameter.
 *
 * @return Describe what the function returns here. Don't
 * write this like "@return This method returns...", but
 * instead something like this "@return the sum of A and B".
 */
protected int myMethod(String someString, int someInt) {
    this.someString = someString;
}


Class example:

/**
 * Class description goes here. Same procedure as for method
 * descriptions.
 *
 * @author [Your name goes here] (If an @author-tag already exists,
 * just add another one with your name, indicating that you
 * have also participated writing the class)
 */
class MyClass extends SomeOtherClass implements SomeInterfaces {
    
    //this is a private field, so no need to JavaDoc it!
    private int myInt;
    
    /**
     * This is a public or protected field, and thus, we must provide
     * JavaDoc since somebody else might use this. Description
     * of the field goes here.
     */
    protected String myString;
    
    //no need to JavaDoc this either. only if it would have
    //been public or protected (in that case, use same format
    //as for this outer class)
    private class MyInnerClass {
        
        //ok, now this is public, but the class it belongs to
        //is just private, so no need to JavaDoc this either
        //(we're the only ones who're going to be able to use
        //this anyway)
        public String blabla;
        
    }
    
}


If you're overriding a method that already has good javadoc comments
you don't need to provide new javadoc comments if you don't want to.
Javadoc tools will then use the comments from the method in the
superclass instead. Here is an example:

This superclass has proper Javadoc comments already:

abstract class Module {
    /**
     * Gets the name of the module.
     * @return The name of the module.
     */
    abstract public String getName();
}


And thus, this inheriting class doesn't need to provide its own
Javadoc comments for the functions it overrides:

class MyModule extends Module {
    public String getName() {
        return "MyModule";
    }
}