Supported Javadoc ================= These traditional Javadoc constructs render as native Sphinx content. Anything else produces a warning; see :doc:`troubleshooting`. Comment text is never interpreted as reStructuredText, and no raw HTML is emitted. Tags and HTML ------------- - Block tags: ``@param`` (including type parameters), ``@return``, ``@throws``/``@exception``, ``@see``, ``@since`` and ``@deprecated``. - JDK notes: ``@apiNote``, ``@implSpec`` and ``@implNote``, with the standard doclet's headings. They are not inherited. - Inline tags: ``code``, ``literal``, ``link``, ``linkplain``, ``value``, ``inheritDoc``, ``return`` and plain inline ``snippet``. ``{@summary}`` shows its text, ``{@index}`` its term and ``{@systemProperty}`` the property name as code, as in the standard doclet; there is no search index entry. - HTML: paragraphs, nested lists, definition lists (``
``, ``
``, ``
``), tables, ``
``, headings ``

`` to ``

`` as rubrics, ``
`` and absolute HTTP(S) or mailto links. - Inline HTML: emphasis (````, ````, ````, ````, ````), strong text (````, ````), code (````, ````, ````, ````), ````, ```` and ````, which shows as plain text. ``
`` is highlighted as Java where its text is Java, and shown without a warning
where it is not, such as a table of results. With a ``lang`` attribute, as in
snippets, Sphinx warns when the text does not match the language.

``@author``, ``@version`` and the ``@serial`` tags are omitted silently, as in the
standard doclet's default output. Other custom tags warn.

Fields follow the order of the JDK's own documentation, whatever the order of the
tags: Specified by and Overrides, the notes, then Type parameters, Parameters,
Returns, Throws, Since and See also.

Text reads as in the standard doclet. A link without a label shows
``Map.Entry``, ``String.format(String, Object...)``, or ``of(L, R)`` for a member of
the same type. A link to a type parameter or a module, such as ``{@link T}`` or
``{@link java.base/}``, shows its name or label as code without linking. Sphinx's
smart quotes are off, so quotes and ``...`` stay as written. ``@throws`` names link
to the exception type.

Constant values
---------------

``{@value}`` shows a constant in Java source form, as the standard doclet does:
quoted strings and characters, and ``L``/``f`` suffixes. ``{@value Type#FIELD}``
links to the field, including JDK fields such as ``Double#MAX_VALUE``. A format
such as ``{@value %x #MASK}`` is applied with the root locale. Non-constant fields
and invalid formats warn.

Tables
------

HTML tables become Sphinx tables. ```` becomes the title, and ````
rows or leading all-```` rows form the header. ``colspan``, ``rowspan``,
omitted end tags and nested content work. Styling attributes are ignored because
the theme styles tables; other attributes warn. Wide tables scroll horizontally.

Inherited documentation
-----------------------

An overriding method inherits an omitted description, parameters, return and
declared throws from its ancestor, following the JDK 25 search order.
``{@inheritDoc SomeSupertype}`` picks a supertype explicitly. Parameters match by
position, generic exception types are substituted, and links resolve in the
ancestor's scope. Class and constructor comments do not inherit. Unresolved
inheritance is marked in the output and warns.

The ancestor's source must be available: in ``java_sources`` or
``java_sourcepath``.

Snippets
--------

Plain inline snippets become code blocks, highlighted as Java unless ``lang``
says otherwise:

.. code-block:: java

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

Indentation follows ``String.stripIndent``. The body is shown literally and never
executed. External snippets (``file``/``class``), regions, IDs and markup tags such
as ``@highlight`` warn and keep the original tag as text.

Inline return
-------------

A comment starting with ``{@return description}`` produces both the "Returns
description." first sentence and a Returns field, as the standard doclet does.