> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Java Documentation Comment
A Java documentation comment (Javadoc) is a specialized block comment parsed by the `javadoc` utility to generate structured, HTML-based API documentation. It is strictly placed immediately preceding the declaration of a module (via `module-info.java`), package (via `package-info.java`), class, interface, record, enum, annotation, constructor, method, or field.
## Syntax Structure
A documentation comment begins with a forward slash and two asterisks `/**` and terminates with an asterisk and a forward slash `*/`. Intermediate lines conventionally begin with an asterisk `*`, which the parser automatically strips along with preceding whitespace.
```java theme={"dark"}
/**
* {@summary Parses a string into an integer and associates it with a generic identifier.}
* Subsequent sentences provide a more detailed description of the element.
* HTML tags such as bold or are valid here.
*
* @param the type of the metadata tag associated with the parsing operation
* @param input the string representation of the number
* @return the parsed integer value
* @throws NumberFormatException if the string does not contain a parsable integer
*/
public int parseNumber(String input) throws NumberFormatException {
return Integer.parseInt(input);
}
```
## Anatomical Components
A standard Javadoc comment is divided into two distinct sections:
1. **Main Description:** Begins immediately after the opening `/**`. Historically, the parser treated the first sentence (terminated by a period followed by a space, tab, or line terminator) as the concise summary statement used in index tables. In modern Java (Java 10 and later), the `{@summary ...}` inline tag is the robust standard for explicitly defining this summary text.
2. **Block Tags Section:** Begins with the first block tag (e.g., `@param`). Once the block tag section begins, no further main description text can be added.
## Block Tags
Block tags are standalone markers placed at the beginning of a line (ignoring the leading asterisk) to define specific metadata about the API element.
* **`@param`**: Documents a method parameter, constructor parameter, or generic type parameter. For generic type parameters, the angle-bracket syntax is required (e.g., `@param description of the type parameter`).
* **`@return`**: Documents the return value of a method. Omitted for `void` methods or constructors.
* **`@throws` / `@exception`**: Documents checked and unchecked exceptions that the method may propagate. Syntax requires the fully qualified or imported exception class name followed by the condition.
* **`@see`**: Generates a "See Also" reference to another API element, URL, or text.
* **`@since`**: Indicates the version of the software in which the element was introduced.
* **`@deprecated`**: Marks an element as obsolete. The description must include a migration path or alternative element.
* **`@version`**: Specifies the current version of the software (typically used at the class/interface level).
* **`@author`**: Identifies the creator of the code element.
## Inline Tags
Inline tags are enclosed within curly braces `{}` and can be embedded anywhere within the main description or block tag descriptions.
* **`{@summary text}`**: Explicitly defines the text to be used as the summary sentence in index tables, overriding the legacy period-and-space parsing rule.
* **`{@code text}`**: Renders the enclosed text in a monospaced font and escapes HTML characters (e.g., `<` and `>`), preventing the parser from interpreting them as HTML markup.
* **`{@link package.class#member label}`**: Generates an inline HTML hyperlink pointing to the documentation of another specific API element.
* **`{@value}`**: When used on a `static final` field (a compile-time constant), it evaluates and displays the constant value of that field.
## Parsing Mechanics
When the `javadoc` tool processes these comments:
* It ignores standard block comments (`/* ... */`) and end-of-line comments (`// ...`).
* It resolves fully qualified class names referenced in `@see`, `@throws`, and `{@link}` tags based on the current compilation unit's imports.
* It directly passes embedded HTML markup to the generated output, meaning malformed HTML within the comment will result in malformed documentation pages.
Tired of Poor Java Skills? Fix That With Deep Grasping!
Learn More
