This is the slide set I've used for JavaDocs and Best Practices session, which I did for the Carbon Team.

1. Aruna Karunarathna
JavaDocs & Best Practices

2. Adding Documentation to your code?
● Block Comments
The compiler ignores everything from /* to */.
● Line Comments
// text
The compiler ignores everything from // to the end of the line.
● JavaDoc Comments
/** documentation */
This indicates a documentation comment. (Doc Comments for shorter version...)

3. Demo

4. JavaDoc Important Tags
● @param
● @return
● @throws
● @deprecated
● @see
● @since
● @code
● @link

5. Adding Documentation to your code cntd..
● What is this supposed to do?
Answered only by the javadoc and method signature
● How does it try to do it?
Answered only by the implementation
● Keep in mind the 80/20 rule. When designing API’s
● Refer the JDK code for further reference.. :)

6. JavaDoc Guidelines..
● Write Javadoc to be read as source code
● Use @param same order as the parameters
● Keep a blank line between the Javadoc text and the @param or
@return
● Public and protected
● Use simple HTML tags, too much HTML not encouraged..!!!

7. JavaDoc Guidelines Cntd..
● Utilize the first sentence as much as possible.
* This means the first sentence of each member, class, interface or
package description
* A concise but complete description of the API item.
● Use @code and @link wisely
* Java keywords, package names, class names, method names,interface names
field names, argument names, code examples
* Keep in mind that audience is a advanced programmers use @link
economically

8. JavaDoc Guidelines Cntd...
● Use lists for explaining set of options, choices
● Avoid second person for sentences and use the third person
● Document accepting or returning null
● Use "this" instead of "the" when referring to an object created
from the current class.
● Use a single <p> tag between paragraphs, Don’t write too lengthy
sentences

9. JavaDoc Guidelines Cntd...
● @param / @return guidelines
@param x the x-coordinate, measured in pixels (Phrase Only)
@param x the x-coordinate. Measured in pixels. (Phrase followed by sentence)
@param x Specifies the x-coordinate, measured in pixels. (Sentence Only)
@param x Specifies the x-coordinate. Measured in pixels. (Multiple Sentences)

10. JavaDoc Guidelines Cntd...
● Add description beyond the API name.
/**
* Sets the tool tip text.
*
* @param text the text of the tool tip
*/
public void setToolTipText(String text) {... }
/**
* Registers the text to display in a tool tip. The text
* displays when the cursor lingers over the component.
*
* @param text the string to display. If the text is null,
* the tool tip is turned off for this component.
*/
public void setToolTipText(String text) {...}

11. JavaDoc Guidelines Cntd...
/**
* Gets personal info.
*
* @param userId user id
* @return Personal info dto.
*/
public PersonalInfoDTO getPersonalInfoDTO(int userId) { ... }
/**
* Gets a dto of personal info by querying the current list of users from
* active directory
*
* @param userId The id of the user. Must be greater than 0. The ID is stored
* in the application context or can be retrieved by a call to
getUserIdByName.
* @return A dto containing personal info. Returns null if the specified user
* information was not found.
*/
public PersonalInfoDTO getPersonalInfoDTO(int userId) { ... }

12. References
● http://www.oracle.com/technetwork/java/javase/documentation/index-
137868.html
● https://github.com/ThreeTen/threeten/blob/0b071a60997f409e44b9bbccde013b
004f24fe22/src/main/java/javax/time/LocalDate.java
● http://blog.joda.org/2012/11/javadoc-coding-standards.html