Supported Javadoc

Write API documentation as traditional Javadoc comments. This page lists what renders as native Sphinx content. Anything else produces a warning; see Troubleshoot a documentation build for alternatives and Compatibility and limits for known limits.

Tags and HTML

Supported traditional Javadoc content includes descriptions, @param (including type parameters), @return, @throws/@exception, @see, @since and @deprecated, plus the JDK’s @apiNote, @implSpec and @implNote notes, which use the standard doclet’s headings and are not inherited. @author, @version and the @serial tags are omitted without a warning, as the standard doclet does by default; other custom tags warn. Inline code, literal, link, linkplain, value and inheritDoc are processed from compiler trees. HTML paragraphs, nested ordered/unordered lists, tables, preformatted code, emphasis, strong text and absolute HTTP(S)/mailto links become native nodes. Literal text is never interpreted as RST, and raw HTML is not emitted. HTML link attribute entities are decoded once, and <br> preserves line breaks and inline formatting. Repeated @throws descriptions for the same exception are retained in order, including when inherited.

Constant values

{@value} shows a constant in Java source form, as the standard doclet does: strings are quoted and escaped, characters quoted, and long/float values keep their L/f suffix. {@value Type#FIELD} links to the field, including external Javadoc fields such as Double#MAX_VALUE; bare {@value} in a constant’s own comment is plain text. An optional java.util.Formatter format, such as {@value %x #MASK}, is applied with the root locale. References to non-constant fields, bare {@value} outside a constant and invalid formats warn.

Tables

HTML tables become native Sphinx tables with <caption> as the table title. Rows in <thead>, or leading rows that contain only <th> cells, form the header. colspan and rowspan are kept, short rows are padded, and HTML’s optional </td>, </th> and </tr> end tags are inferred. Cells can contain paragraphs, lists, code and nested tables. class, summary and border on <table> and scope on cells are accepted but have no effect: themes style tables. Other attributes and text outside cells warn. <th> cells outside the header render as ordinary cells. Wide tables scroll horizontally within the content column, and code in cells is not wrapped. Text from {@literal} and {@value} keeps straight quotes because Sphinx’s smart quotes are not applied to it.

Inherited documentation

Overriding methods inherit omitted descriptions, parameters, returns and declared throws documentation. Parameter matching is positional, so renamed parameters work. Generic exception types are substituted through the compiler’s view of the parent method: Contract<E> implemented as Contract<IOException> can supply @throws IOException documentation. Method exception type parameters are matched by position, and inherited throws labels use the overriding method’s exception. The default search follows the JDK 25 rule; {@inheritDoc SomeSupertype} selects a supertype explicitly. Links in inherited prose resolve in the original author’s scope. Class and constructor comments do not inherit. Explicit unresolved inheritance is visibly marked and warned; missing inherited parts also warn. This is not a full replacement for standard Javadoc’s DocLint or all standard-doclet synthesis.

Snippets

Plain inline snippets become native literal blocks, with Java highlighting by default. An optional lang selects a Sphinx/Pygments language (such as text):

/** Example:
 * {@snippet lang="java" :
 *     System.out.println("Hello");
 * }
 */

Indentation follows JDK String.stripIndent rules, including the closing brace’s indentation. Snippet content is literal: HTML entities, Javadoc tags and RST syntax inside the body are preserved rather than interpreted. Snippets are never executed. External/hybrid snippets (file/class), regions, IDs, duplicate attributes and markup actions (@highlight, @replace, @link, @start, @end) warn and retain the original tag as literal text. Markup detection is conservative: reserved markup tags following // or # also warn inside quoted examples.

Inline return descriptions

A method comment beginning with {@return description} produces both the introductory “Returns description.” sentence and a Returns field. Inline markup and inherited return descriptions are preserved in both places. The conformance suite compares these results with the JDK standard doclet, including inheritance between inline and block return tags.