Java Documentation Comment Syntax

The Java language supports special "doc comments," which begin with /** and end with */. These comments are not actually treated specially by the compiler, but can be extracted and automatically turned into HTML documentation by the javadoc program.

Because the lines of a doc comment are embedded within a Java comment, any leading spaces and asterisks (*) are stripped from each comment line before processing. A doc comment may contain HTML markup tags, such as <PRE> and <TT> for code usage examples, but should not contain HTML structural tags such as <H2> or <HR>. Doc comments should immediately precede the declaration of the class, field, or method that they are associated with. The first sentence of a doc comment should be a summary sentence, suitable for display on its own. The following sentences may document the feature in more detail.

Following the initial summary sentence and any additional documentation, a doc comment may use special tags, which all begin with the @ character and allow javadoc to provide additional formatting for the documentation. The available tags are listed below. When you use a special javadoc tag, it must be the first thing on its line within the doc comment. The text that follows a tag may span more than one line, and continues until the next javadoc tag is encountered or until the comment ends. If you use more than one tag of the same type, they should be on subsequent lines. For example, a class with multiple authors, or a method with multiple arguments would use multiple @author or @param tags.