Question

I want to learn to write method definition in my class. i.e:

    public int myMethod()
    {
    //This method is used for ....bla bla bla....
    }

I want to inform user about what methods do.
In .Net you can write this definition and you can see the explanation when you write the method. How can it be done in JAVA ?

Answer 1

Fleshing out some of the other answers.

The first sentence should be third-person declarative sentence that answers the question “What does the method do,” e.q., “Creates a foobar.” Also, the first sentence is used as the summary comment, so it should be as clear, and concise, as possible.

For example, if your method read in a file and returned an integer status:

/**
 * Reads in config file and initializes application.
 *
 * @return Application status; 0 if everything is okay.
 */
public int myMethod() {
    // ...
}

IMO adding unnecessary details is just that–unnecessary. Some methods are self-documenting, the canonical example being getters/setters:

/**
 * Sets first name.
 *
 * @param firstName Name to set.
 */
public void setFirstName(String firstName) {
    this.firstName = firstName;
}

Redundant comment. Similarly, well-named methods can avoid needing extensive, or any, docs:

public List<User> getAllUsers() { ... }
public User findUserById(Long id) { ... }

IMO unless there’s something actually remarkable, there’s no need to remark.

HTML is used to mark up Javadocs, but IMO it’s a good idea to format it in such a way that it can be read in multiple formats (editor, IDE, Javadocs, etc.) so I tend to indent and use whitespace to make sure I can see everything in plain text as well as rendered.

The standard doclet assumes HTML: whitespace is ignored unless made explicit via <p> or <br> tags.

/**
 * Builds and returns the current list of ingredients.
 *
 * <p>
 *   <b>Note:</b> Initializes ingredient information if necessary.
 * </p>
 */

Useful links:

• javadoc program docs
• How to write javadocs
• Requirements for writing Java API specs
• My own take on Javadocs and documentation in general (includes some lesser-used Javadoc tricks)