What is a Doc Comment

What is a Doc Comment?

Documentation comments, often called doc comments, let you associate reference documentation for use by client programmers using your code. These doc comments are used to generate reference documentation, which is typically presented in HTML format.

·     949j919j ;     949j919j ; Doc comments start with the three characters and continue until the next .

·     949j919j ;     949j919j ; Leading characters are ignored on doc comment lines, as are whitespace characters preceding a leading .

·     949j919j ;     949j919j ; Each doc comment (member, class, interface or package) has what is known as the first sentence, (also known as the summary sentence) which is used as a Summary for the identifier. The Javadoc tool copies this first sentence to the appropriate member, class/interface or package "Summary Section". This makes it important to write crisp and informative initial sentences that can stand on their own.

A sentence is defined as all text up to the first period with following whitespace. Even though it's referred to as a "summary sentence", it is often a phrase rather than a complete sentence. It can extend over several lines if needed; just don't include any blank lines. Since the sentence ends with the first period, so you must avoid abbreviations such as "e.g." in this sentence. Following the summary sentence, you may include more sentences to give more details; but again, don't include any blank lines.

Consider the following example:

* Get hire date for the given employee. The

* hire date will be retrieved from the central HR System.

*/

public Date getHireDate(int employeeID)

throws InvalidDateFormat;

In the above example, the summary (or first sentence) is "Get hire date for the given employee." The programmer should ensure that the first sentence of the doc comment provides a good summary.

·     949j919j ;     949j919j ; HTML tags will often be embedded in doc comments as formatting directives or as cross-reference links to portions of the document, other documents, or external web sites.

o     949j919j ;    While most HTML tags can be used, you should stay away from the header tags <h1>, <h2>, and so on. These tags are reserved for use by the javadoc tool.

o     949j919j ;    When trying to insert the characters <, >, or & use &lt, &gt; and &amp respectively.

o     949j919j ;    If you need to insert an character at the beginning a line within a doc comment, use &#064, - otherwise it will be assumed a doc comment tag.

·     949j919j ;     949j919j ; A common mistake made my new comers to javadoc is placement of your doc comments. Only doc comments that immediately precede a class, interface, method, or field will be processed. If anything besides whitespace or comments are between a doc comment and what it is trying to describe, will be ignored. Consider the following example:

* A utility class used to process employee information

*/

package info.iDevelopment.employee;

import java.sql.*;

public class employeeUtilities

In the above example, doc comment at the beginning of the file will not be processed since because of the "package" and "import" statements inserted between the doc comment and the class definition.

·     949j919j ;     949j919j ; If no doc comment exists for an inherited method, the method inherits the doc comment from the supertype.