Javadoc comments

Comments are read from the compiler’s comment trees and rendered as native Sphinx content, so your theme styles them like any other page. Source comments are never interpreted as reStructuredText, and no raw HTML is emitted.

HTML, inline tags and snippets

One class comment uses most of the supported content: paragraphs, emphasis, nested lists, <pre>{@code ...}</pre> blocks, line breaks, external links, an inline {@snippet}, a table with a caption, {@value}, {@link} and {@linkplain}, and the @see and @since tags.

/** A widget with a unified Java API and handwritten guides.
 * <p>Call {@link #convert(int)} or {@linkplain #convert(String) the text overload}.
 * Types such as {@link Instant}, {@link java.util.Map.Entry}, and
 * {@link String#substring(int, int)} link to configured external Javadoc.
 * <ul><li>Preserves <strong>structure</strong> and <em>emphasis</em>.</li>
 * <li>Supports nested lists:<ol><li>Read.</li><li>Transform.</li></ol></li></ul>
 * <pre>{@code Widget widget = new Widget();
 * String result = widget.convert(42);
 * if (result.length() > 0) {
 *     System.out.println(result);
 * }}</pre>
 * <p>First line<br><em>Second line<br>Third line</em><br>Last line.</p>
 * <p>Try <a href="https://example.test/?a=1&amp;b=2">query parameters</a>.</p>
 * <p>An inline snippet:</p>
 * {@snippet :
 *     String value = widget.convert(7);
 *     System.out.println(value);
 * }
 * <table class="striped">
 * <caption>Conversion examples</caption>
 * <tr><th>Call</th><th>Result</th><th>Notes</th></tr>
 * <tr><td>{@code widget.convert(42)}</td><td>{@code "42"}</td>
 * <td>Labelled {@value #LABEL}; long names such as
 * {@code com.example.widgets.configuration.DefaultWidgetLabelProvider} stay inside the table</td></tr>
 * </table>
 * @see Point
 * @since 1.0
 */
public class Widget implements Transformer<String> {

public class demo.Widget implements Transformer<String>

A widget with a unified Java API and handwritten guides.

Call #convert(int) or the text overload. Types such as Instant, java.util.Map.Entry, and String#substring(int, int) link to configured external Javadoc.

• Preserves structure and emphasis.

• Supports nested lists:

  1. Read.

  2. Transform.

Widget widget = new Widget();
 String result = widget.convert(42);
 if (result.length() > 0) {
     System.out.println(result);
 }

First line

Second line

Third line

Last line.

Try query parameters.

An inline snippet:

    String value = widget.convert(7);
    System.out.println(value);

Conversion examples

Call	Result	Notes
widget.convert(42)	"42"	Labelled "widget"; long names such as com.example.widgets.configuration.DefaultWidgetLabelProvider stay inside the table

See also:

Point

Since:

1.0

Parameters, returns and exceptions

@param, @return and @throws become fields. Type parameters get their own field.

    /** Builds a generic index.
     * @param <T> comparable numeric key
     * @param values input values
     * @param fallback default entries
     * @return grouped entries
     */
    public <T extends Number & Comparable<T>> Map<T, List<? extends CharSequence>> buildIndex(
            List<? extends T> values, Map<T, List<? extends CharSequence>> fallback) { return fallback; }

public <T extends Number & Comparable<T>> Map<T, List<? extends CharSequence>> buildIndex(List<? extends T> values, Map<T, List<? extends CharSequence>> fallback)

Builds a generic index.

Type parameters:

<T> – comparable numeric key

Parameters:

• values – input values

• fallback – default entries

Returns:

grouped entries

API and implementation notes

The JDK’s @apiNote, @implSpec and @implNote tags use the standard doclet’s headings. @author and @version are left out, as the standard doclet does by default.

    /** Transforms a value twice.
     * @apiNote Use this when one pass is not enough.
     * @implSpec The default implementation calls {@link #convert(Object)} twice.
     * @implNote This implementation does not cache the first result.
     * @param input the value to transform
     * @return the twice transformed value
     */
    default T twice(T input) {

public default T twice(T input)

Transforms a value twice.

API Note:

Use this when one pass is not enough.

Implementation Requirements:

The default implementation calls #convert(Object) twice.

Implementation Note:

This implementation does not cache the first result.

Parameters:

input – the value to transform

Returns:

the twice transformed value

Deprecation

@deprecated produces the same notice as Sphinx’s deprecated directive, and the annotation stays in the signature.

    /** Old entry point.
     * @deprecated Use {@link #convert(int)}.
     */
    @Deprecated(since="1.0", forRemoval=true) public void old() {}

@Deprecated(since="1.0", forRemoval=true) public void old()

Deprecated: Use #convert(int).

Old entry point.