sphinx-java-autodoc 0.6.0__tar.gz → 0.7.0__tar.gz

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sphinx-java-autodoc
-Version: 0.6.0
+Version: 0.7.0
 Summary: Compiler-backed Java API documentation in native Sphinx nodes
 Project-URL: Documentation, https://r4sky0.github.io/sphinx-java-autodoc/
 Project-URL: Repository, https://github.com/r4sky0/sphinx-java-autodoc
@@ -52,8 +52,8 @@ for the output.
 
 ## Requirements
 
-Python 3.12+, Sphinx 8.2.x or 9.1.x, and **JDK 25 for extraction**. Your library can keep
-targeting Java 17 or 21. See
+Python 3.12+, Sphinx 8.2.x, 9.0.x or 9.1.x, and **JDK 25 for extraction**. Your library
+can keep targeting Java 17 or 21. See
 [compatibility and limits](https://r4sky0.github.io/sphinx-java-autodoc/compatibility.html).
 
 ## Quick start

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/README.md

@@ -21,8 +21,8 @@ for the output.
 
 ## Requirements
 
-Python 3.12+, Sphinx 8.2.x or 9.1.x, and **JDK 25 for extraction**. Your library can keep
-targeting Java 17 or 21. See
+Python 3.12+, Sphinx 8.2.x, 9.0.x or 9.1.x, and **JDK 25 for extraction**. Your library
+can keep targeting Java 17 or 21. See
 [compatibility and limits](https://r4sky0.github.io/sphinx-java-autodoc/compatibility.html).
 
 ## Quick start

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/docs/compatibility.rst

@@ -25,8 +25,9 @@ Requirements and tested versions
      - 3.12+
      - 3.12, 3.13 and 3.14
    * - Sphinx
-     - 8.2.x and 9.1.x
+     - 8.2.x, 9.0.x and 9.1.x
      - 9.1.0, with the Docutils version it installs (0.22.4); the test suite on 8.2.3
+       and on 9.0.4 with Docutils 0.22.4
    * - Operating system
      - Platform-neutral
      - Linux, macOS and Windows in GitHub Actions
@@ -57,8 +58,9 @@ Known limits
 * Traditional Javadoc comments and plain inline ``{@snippet}`` bodies are
   supported; see :doc:`javadoc-support`. Markdown comments (``///``), external or
   hybrid snippets, snippet regions, IDs and markup, and unsupported tags warn. The
-  HTML subset excludes definition lists, headings, images, presentational attributes,
-  ``<th>`` styling outside table headers, and local documentation assets.
+  HTML subset excludes images, presentational attributes, ``<th>`` styling outside
+  table headers, and local documentation assets. Headings become rubrics, outside
+  the page's table of contents.
 * Only declared members are shown. Non-overridden inherited methods stay on their
   ancestor's page. Compiler-generated record and enum methods are listed, but the
   standard doclet's generated prose for them is not synthesized.

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/docs/gallery/comments.rst

@@ -11,7 +11,8 @@ 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.
+``{@linkplain}``, a heading, a definition list, ``<sup>``, ``<kbd>``,
+``{@systemProperty}``, and the ``@see`` and ``@since`` tags.
 
 .. literalinclude:: ../../examples/standalone/src/demo/Widget.java
    :language: java

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/docs/gallery/declarations.rst

@@ -3,6 +3,9 @@ Declarations and signatures
 
 Signatures come from the compiler, so they show exactly what JDK 25 accepts. Type
 names in signatures link to their documentation, here or in external Javadoc.
+Modifiers are those the standard doclet shows: it leaves out implied ones, such as
+``public`` on interface members, ``abstract`` on interfaces and ``final`` on records
+and enums, and implementation details such as ``synchronized`` and ``native``.
 
 Generics, arrays and varargs
 ----------------------------

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/docs/gallery/warnings.rst

@@ -16,19 +16,23 @@ this site builds with ``-W``, so a real warning would fail it.
      - Markdown documentation comments are not supported
      - ``java.extract``
    * - An unknown block tag, such as ``@todo``
-     - Unsupported block tag UNKNOWN_BLOCK_TAG
+     - Unsupported block tag @todo
      - ``java.extract``
    * - External snippets, regions or markup
      - Unsupported snippet attributes or markup
      - ``java.extract``
-   * - ``{@link}`` to a symbol the compiler can't find
+   * - ``{@link}`` or ``@throws`` naming a symbol the compiler can't find
      - Unresolved Javadoc reference
      - ``java.extract``
+   * - An override without its own text, such as ``toString``, whose ancestor has
+       no source documentation
+     - Cannot inherit
+     - ``java.inherit``
    * - ``{@inheritDoc}`` without ancestor source
      - Cannot resolve inheritDoc
      - ``java.extract``
-   * - An HTML element outside the supported subset, such as ``<h3>``
-     - Unsupported Javadoc HTML <h3>
+   * - An HTML element outside the supported subset, such as ``<img>``
+     - Unsupported Javadoc HTML <img>
      - ``java.html``
    * - A ``:members:`` entry that doesn't exist
      - Java member ... was not found

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/docs/javadoc-support.rst

@@ -13,17 +13,33 @@ Tags and HTML
 - 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``.
-- HTML: paragraphs, nested lists, tables, ``<pre>``, emphasis, strong text,
-  ``<br>`` and absolute HTTP(S) or mailto links.
+  ``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 (``<dl>``, ``<dt>``, ``<dd>``),
+  tables, ``<pre>``, headings ``<h1>`` to ``<h6>`` as rubrics, ``<br>`` and absolute
+  HTTP(S) or mailto links.
+- Inline HTML: emphasis (``<i>``, ``<em>``, ``<var>``, ``<cite>``, ``<dfn>``), strong
+  text (``<b>``, ``<strong>``), code (``<code>``, ``<tt>``, ``<kbd>``, ``<samp>``),
+  ``<sup>``, ``<sub>`` and ``<small>``, which shows as plain text.
+
+``<pre>`` 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. Sphinx's smart quotes are off, so quotes and ``...`` stay as written.
-``@throws`` names link to the exception type.
+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
 ---------------

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/docs/schema.md

@@ -23,8 +23,11 @@ not a general XML document interchange service. No external entities are fetched
   or modifier, `kt` primitive type or `void`, `t` punctuation or spaces, `q` package
   qualifier, `n` declared name, `tv` type variable, `pname` parameter name, `v` constant
   or default value, `r` type reference, and `params` containing one `param` per
-  parameter or record component. `r` carries `target` (canonical ID) and the external
-  Javadoc `path`, `module` and `fragment`; its text is the nested simple name.
+  parameter or record component. Modifiers are those the standard doclet shows,
+  without implied ones such as `public` on interface members or `final` on records,
+  and without `native`, `synchronized` and `strictfp`. `r` carries `target`
+  (canonical ID) and the external Javadoc `path`, `module` and `fragment`; its text
+  is the nested simple name.
   Readers reject unknown tokens and malformed `r` targets.
 - `doc/part`: `kind` (`body`, `specifiedBy`, `overrides`, `param`, `typeparam`,
   `return`, `throws`, `see`, `since`, `deprecated`, `apiNote`, `implSpec`, `implNote`)
@@ -64,7 +67,10 @@ not a general XML document interchange service. No external entities are fetched
   `Map.Entry`, `String.format(String, Object...)` or `of(L, R)` within the same type.
   An unresolved link has no resolved location and has a diagnostic.
 - `diagnostic`: symbol-qualified warning text, including unsupported constructs.
-  Warnings survive cache hits and are re-emitted by Sphinx.
+  Warnings survive cache hits and are re-emitted by Sphinx. An optional `kind`
+  is `inherit` for an omitted part that no ancestor documents, or `extract`; a
+  diagnostic without `kind` is `extract`. Sphinx warns with the kind as subtype,
+  such as `java.inherit`. Readers reject other kinds. Additive in schema 1.
 
 Identity examples: `example.Outer.Inner`, `example.Outer#FIELD`,
 `example.Outer#find(java.lang.String,int[])`, `example.Outer#<init>()`.

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/docs/showcase.rst

@@ -17,8 +17,10 @@ JDK links and ``sphinx.ext.linkcode`` for :ref:`source links <source-links>` to
 GitHub at the pinned commit. For an example of every feature, see the
 :doc:`gallery/index`. The build reports |showcase-total| warnings:
 
-- |showcase-java.extract| ``java.extract``: overrides of JDK methods that cannot
-  inherit their documentation, and links to libraries not on the classpath.
+- |showcase-java.inherit| ``java.inherit``: overrides of JDK methods that cannot
+  inherit their documentation, because the JDK's sources are not available.
+- |showcase-java.extract| ``java.extract``: links to libraries not on the classpath,
+  and ``{@inheritDoc}`` with no ancestor source.
 - |showcase-java.html| ``java.html``: headings and other unsupported HTML.
 - |showcase-misc.highlighting_failure| highlighting failures: ``<pre>`` examples that
   are not Java.

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/docs/troubleshooting.rst

@@ -41,9 +41,24 @@ Unsupported tags, HTML, ``///`` Markdown comments and advanced snippets warn wit
 the symbol; see :doc:`javadoc-support`. To inherit a dependency's Javadoc, add its
 sources to ``java_sourcepath``.
 
-Warnings use the ``java.extract``, ``java.html``, ``java.type``, ``java.member``
-and related categories. Suppressing a warning does not add the missing content.
-Outside Sphinx, ``--warnings-as-errors`` makes extraction diagnostics fail.
+Warnings use the ``java.extract``, ``java.inherit``, ``java.html``, ``java.type``,
+``java.member`` and related categories. Suppressing a warning does not add the
+missing content. Outside Sphinx, ``--warnings-as-errors`` makes all extraction
+diagnostics fail, whatever their category.
+
+An overriding method without its own text for a part warns "Cannot inherit ..."
+as ``java.inherit`` when no ancestor documents that part. This is common for
+overrides of JDK methods such as ``toString``, ``equals`` and ``hashCode``: the
+JDK's sources ship as modules with ``module-info.java``, which ``java_sourcepath``
+rejects, so there is nothing to inherit from. Document the part, or silence only these
+warnings while keeping the others:
+
+.. code-block:: python
+
+   suppress_warnings = ["java.inherit"]
+
+An explicit ``{@inheritDoc}`` that cannot be resolved stays ``java.extract``,
+because it leaves an ``[unresolved inheritDoc]`` marker in the output.
 
 The extension refuses to overwrite a generated page
 ---------------------------------------------------

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/docs/usage.rst

@@ -38,7 +38,8 @@ Set these in ``conf.py``. Paths are relative to ``conf.py``, except
      - JDK 25 home; empty uses the runtime on ``PATH``.
    * - ``java_release``
      - ``""``
-     - Source/API release; empty uses the JDK default. Tested: 17, 21, 25.
+     - Source/API release, such as ``"17"`` or ``17``; empty uses the JDK default.
+       Tested: 17, 21, 25.
    * - ``java_generate``
      - ``""``
      - Directory for generated pages, such as ``"api"``. Empty generates no pages.
@@ -128,8 +129,11 @@ Roles
 
 ``java:obj`` accepts any kind. Targets are fully qualified: there are no imports
 or short-name guessing. Parameters are erased, fully qualified types, with ``[]``
-for varargs; constructors are ``<init>``. A method without a parameter list
-resolves only when it has one overload; otherwise it warns. References inside Java
+for varargs; constructors are ``<init>``. Roles, ``java:auto*`` arguments,
+``java:autosummary`` lines and ``:members:``/``:exclude-members:`` entries all
+ignore spaces and accept ``...`` for ``[]``, so ``find(java.lang.String, int)``
+works too. A method without a parameter list resolves only when it has one
+overload; otherwise it warns. References inside Java
 comments are resolved by the compiler as usual.
 
 .. _source-links:
@@ -177,8 +181,12 @@ Map package prefixes to Javadoc roots; the longest prefix wins:
 Javadoc 9+ URL structure; Javadoc 8 anchors are not supported. URLs are built
 without fetching or checking the remote site.
 
-A role that no source comment references has no module metadata. For those, map
-the exact package without ``{module}``:
+A role takes the module and location from the extracted model when the symbol
+appears there: in a comment link, a documented exception or a signature. Other
+roles have no module metadata. For those, map the package, or a prefix of it within one module, without ``{module}``. The type
+name starts at the first capitalized name, as Java naming conventions have it, so
+``vendor.api.util.Thing.Inner`` under ``vendor.api`` links to
+``vendor/api/util/Thing.Inner.html``:
 
 .. code-block:: python
 

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/examples/standalone/src/demo/Widget.java

@@ -29,6 +29,10 @@ import java.util.Map;
  * <td>Labelled {@value #LABEL}; long names such as
  * {@code com.example.widgets.configuration.DefaultWidgetLabelProvider} stay inside the table</td></tr>
  * </table>
+ * <h2>Terms</h2>
+ * <dl><dt><dfn>Label</dfn></dt><dd>Text shown with each value, up to 2<sup>31</sup> characters.</dd>
+ * <dt>Shortcut</dt><dd>Copy with <kbd>Ctrl</kbd>+<kbd>C</kbd>; files go to
+ * {@systemProperty user.home}.</dd></dl>
  * @see Point
  * @since 1.0
  */

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sphinx-java-autodoc"
-version = "0.6.0"
+version = "0.7.0"
 description = "Compiler-backed Java API documentation in native Sphinx nodes"
 readme = "README.md"
 requires-python = ">=3.12"

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/src/sphinx_java_autodoc/__init__.py

@@ -61,7 +61,9 @@ def prepare(app):
     app.env.java_model_path = str(model.path)
     use_model(root)
     for diagnostic in root.findall("diagnostic"):
-        LOGGER.warning(diagnostic.text, type="java", subtype="extract")
+        # The kind lets suppress_warnings = ["java.inherit"] keep the other warnings.
+        subtype = diagnostic.get("kind", "extract")
+        LOGGER.warning(diagnostic.text, type="java", subtype=subtype)
     if config.java_generate:
         directory = (Path(app.srcdir) / config.java_generate).resolve()
         if (
@@ -95,7 +97,6 @@ def setup(app):
         "java_encoding": "UTF-8",
         "java_exclude_packages": [],
         "java_jdk": "",
-        "java_release": "",
         "java_model": "",
         "java_generate": "",
         "java_visibility": "protected",
@@ -103,13 +104,16 @@ def setup(app):
         "java_maximum_signature_line_length": None,
     }.items():
         app.add_config_value(name, default, "env")
+    # A release is often written as a number, such as java_release = 17.
+    app.add_config_value("java_release", "", "env", types=frozenset({str, int}))
     app.add_domain(JavaDomain)
     add_linkcode_domain("java", ["fullname", "source", "line"])
     app.add_css_file("java-autodoc.css")
     app.connect("builder-inited", add_static_path)
     app.connect("builder-inited", prepare)
     app.connect("env-get-outdated", outdated)
-    app.connect("missing-reference", quiet_reference)
+    # After intersphinx (priority 500), whatever the extension order.
+    app.connect("missing-reference", quiet_reference, priority=900)
     return {
         "version": VERSION,
         "env_version": 4,

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/src/sphinx_java_autodoc/domain.py

@@ -118,15 +118,10 @@ def summary_type(element) -> list[nodes.Node]:
         else:
             tokens.append(sig[i])
         i += 1
-    owner = SYMBOLS.get(element.get("id").partition("#")[0])
-    interface = owner is not None and owner.get("kind") in {
-        "interface",
-        "annotation_type",
-    }
     modifiers = []
     while tokens and (tokens[0].tag == "k" or tokens[0].text == " "):
         text = tokens.pop(0).text
-        if text in SUMMARY_MODIFIERS and not (interface and text == "abstract"):
+        if text in SUMMARY_MODIFIERS:
             modifiers.append(text)
     if tokens and tokens[-1].tag == "t" and tokens[-1].text == " ":
         tokens.pop()
@@ -148,6 +143,11 @@ def display_name(symbol: str) -> str:
     return f"{owner}.{member_label(symbol)}" if member else symbol
 
 
+def canonical(spelling: str) -> str:
+    """A hand-written symbol as a model ID: no spaces, and varargs ``...`` as ``[]``."""
+    return re.sub(r"\s+", "", spelling).replace("...", "[]")
+
+
 class JavaDirective(SphinxDirective):
     def visible(self, element) -> bool:
         return visible(
@@ -246,10 +246,10 @@ class AutoClass(JavaDirective):
         if "members" in self.options:
             # Semicolons allow exact signatures containing commas.
             selected = {
-                s.strip() for s in self.options["members"].split(";") if s.strip()
+                canonical(s) for s in self.options["members"].split(";") if s.strip()
             }
             excluded = {
-                s.strip()
+                canonical(s)
                 for s in self.options.get("exclude-members", "").split(";")
                 if s.strip()
             }
@@ -287,8 +287,8 @@ class AutoMember(JavaDirective):
     option_spec = {"no-index": directives.flag}
 
     def run(self):
-        symbol = re.sub(r"\s+", "", self.arguments[0])
-        element = self.lookup(symbol.replace("...", "[]"), ("member",))
+        symbol = canonical(self.arguments[0])
+        element = self.lookup(symbol, ("member",))
         if element is None:
             self.missing("member", symbol, "member")
             return []
@@ -343,7 +343,7 @@ class AutoSummary(JavaDirective):
         table = nodes.table("", classes=["autosummary", "longtable", "java"])
         rows = []
         for line in self.content:
-            symbol = re.sub(r"\s+", "", line)
+            symbol = canonical(line)
             if not symbol:
                 continue
             element = self.lookup(symbol)
@@ -441,8 +441,9 @@ class JavaDomain(Domain):
             yield symbol, display_name(symbol), kind, docname, target, 0
 
     def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode):
+        # External Javadoc fragments keep the spelling's varargs.
         spelling = re.sub(r"\s+", "", target)
-        target = spelling.replace("...", "[]")
+        target = canonical(target)
         objects = self.data["objects"]
         # Only member names can omit their parameter list.
         if target not in objects and "#" in target and "(" not in target:

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/src/sphinx_java_autodoc/extractor.py

@@ -7,6 +7,7 @@ import json
 import os
 from pathlib import Path
 import re
+import secrets
 import shutil
 import subprocess
 import tempfile
@@ -16,9 +17,11 @@ from sphinx.errors import ExtensionError
 
 from .model import Model, read_model
 
-VERSION = "0.6.0"  # x-release-please-version
+VERSION = "0.7.0"  # x-release-please-version
 DOCLET = Path(__file__).parent / "java" / "SphinxDoclet.java"
 PACKAGE = re.compile(r"[^\W\d]\w*(?:\.[^\W\d]\w*)*")
+# The JVM announces options from variables such as JAVA_TOOL_OPTIONS on stderr.
+JVM_NOTICE = re.compile(r"(NOTE: )?Picked up \w+:")
 
 
 def run(arguments: list[str], *, cwd: Path | None = None) -> str:
@@ -50,15 +53,20 @@ def atomic_write(path: Path, data: bytes) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     if path.exists() and path.read_bytes() == data:
         return
-    with tempfile.NamedTemporaryFile(dir=path.parent, delete=False) as stream:
-        temporary = Path(stream.name)
-        try:
+    temporary = path.with_name(f".{path.name}.{secrets.token_hex(8)}.tmp")
+    # O_EXCL refuses an existing file or planted symlink; the umask applies to 0o666.
+    # Opened before the try, so the cleanup never removes a file it did not create.
+    fd = os.open(
+        temporary,
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0),
+        0o666,
+    )
+    try:
+        with os.fdopen(fd, "wb") as stream:
             stream.write(data)
-            stream.flush()
-            stream.close()
-            os.replace(temporary, path)
-        finally:
-            temporary.unlink(missing_ok=True)
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)
 
 
 def extract(
@@ -243,7 +251,12 @@ def extract(
             ),
             encoding="utf-8",
         )
-        diagnostics = run([tools["javadoc"], "@" + str(argfile)], cwd=work)
+        printed = run([tools["javadoc"], "@" + str(argfile)], cwd=work)
+        diagnostics = "".join(
+            line
+            for line in printed.splitlines(keepends=True)
+            if not JVM_NOTICE.match(line)
+        )
         root = read_model(output)
         root.set("extractor", VERSION)
         if diagnostics.strip():

{sphinx_java_autodoc-0.6.0 → sphinx_java_autodoc-0.7.0}/src/sphinx_java_autodoc/java/SphinxDoclet.java

@@ -46,7 +46,8 @@ public final class SphinxDoclet implements Doclet {
   private Types types;
   private Path output;
   private List<String> excluded = List.of();
-  private final Set<String> warnings = new TreeSet<>();
+  // Diagnostic text and its kind: "inherit" for an omitted part no ancestor documents.
+  private final Map<String, String> warnings = new TreeMap<>();
   private final Map<Element, Map<String, Part>> comments = new HashMap<>();
 
   /** Documentation content together with the declaration whose comment supplied it. */
@@ -214,10 +215,17 @@ public final class SphinxDoclet implements Doclet {
         if (env.getIncludedElements().stream()
             .noneMatch(
                 e -> excluded(pkg, elements.getPackageOf(e).getQualifiedName().toString()))) {
-          warnings.add("Excluded package %s matches no source package.".formatted(pkg));
+          warnings.put("Excluded package %s matches no source package.".formatted(pkg), "extract");
         }
       }
-      warnings.forEach(warning -> root.addText("diagnostic", warning));
+      warnings.forEach(
+          (warning, kind) -> {
+            var diagnostic = root.add("diagnostic");
+            if (!kind.equals("extract")) {
+              diagnostic.set("kind", kind);
+            }
+            diagnostic.node().setTextContent(Xml.safe(warning));
+          });
       var transformer = TransformerFactory.newInstance().newTransformer();
       transformer.setOutputProperty(OutputKeys.ENCODING, "UTF-8");
       transformer.setOutputProperty(OutputKeys.INDENT, "yes");
@@ -263,7 +271,12 @@ public final class SphinxDoclet implements Doclet {
 
   /** Records a diagnostic; {@code template} is a {@link String#format} pattern. */
   private void warn(Element owner, String template, Object... args) {
-    warnings.add(id(owner) + ": " + (args.length == 0 ? template : template.formatted(args)));
+    warn("extract", owner, template, args);
+  }
+
+  private void warn(String kind, Element owner, String template, Object... args) {
+    warnings.putIfAbsent(
+        id(owner) + ": " + (args.length == 0 ? template : template.formatted(args)), kind);
   }
 
   // Declarations and signatures
@@ -307,8 +320,10 @@ public final class SphinxDoclet implements Doclet {
       sig.addText("t", " ");
     }
     for (var modifier : e.getModifiers()) {
-      sig.addText("k", modifier.toString());
-      sig.addText("t", " ");
+      if (shown(e, modifier)) {
+        sig.addText("k", modifier.toString());
+        sig.addText("t", " ");
+      }
     }
     switch (e) {
       case TypeElement type -> typeSig(sig, type);
@@ -327,6 +342,27 @@ public final class SphinxDoclet implements Doclet {
     }
   }
 
+  /**
+   * Whether the standard doclet shows the modifier: it leaves out implementation details and
+   * modifiers that the declaration's kind implies, such as {@code public} on interface members.
+   */
+  private static boolean shown(Element e, Modifier modifier) {
+    var kind = e.getKind();
+    boolean interfaceMember =
+        !(e instanceof TypeElement) && e.getEnclosingElement().getKind().isInterface();
+    return switch (modifier) {
+      case NATIVE, SYNCHRONIZED, STRICTFP -> false;
+      case PUBLIC -> !interfaceMember;
+      case PROTECTED, PRIVATE, STATIC -> true;
+      case ABSTRACT ->
+          kind != ElementKind.ENUM
+              && !kind.isInterface()
+              && !(interfaceMember && e instanceof ExecutableElement);
+      case FINAL -> kind != ElementKind.ENUM && kind != ElementKind.RECORD;
+      default -> kind != ElementKind.ENUM;
+    };
+  }
+
   private void typeSig(Xml sig, TypeElement type) {
     var kind = type.getKind();
     sig.addText(
@@ -540,6 +576,15 @@ public final class SphinxDoclet implements Doclet {
   }
 
   private Xml declaration(Xml parent, String tag, Element e) {
+    try {
+      return declarationNode(parent, tag, e);
+    } catch (RuntimeException ex) {
+      // Names the declaration in "Sphinx extraction failed", so its comment can be found.
+      throw new IllegalStateException(id(e) + ": " + ex, ex);
+    }
+  }
+
+  private Xml declarationNode(Xml parent, String tag, Element e) {
     var node =
         parent
             .add(tag)
@@ -602,7 +647,10 @@ public final class SphinxDoclet implements Doclet {
             result.put(custom.getTagName() + ":" + note++, new Part(e, "", custom.getContent()));
         default -> {
           if (!OMITTED.contains(tag.getKind())) {
-            warn(e, "Unsupported block tag %s; retain it in handwritten guides.", tag.getKind());
+            // The tag as written, such as @todo, rather than its kind UNKNOWN_BLOCK_TAG.
+            Object name =
+                tag instanceof BlockTagTree block ? "@" + block.getTagName() : tag.getKind();
+            warn(e, "Unsupported block tag %s; retain it in handwritten guides.", name);
           }
         }
       }
@@ -638,6 +686,13 @@ public final class SphinxDoclet implements Doclet {
 
   private void putThrows(Map<String, Part> result, Element e, ThrowsTree thrown) {
     var target = resolve(e, thrown.getExceptionName());
+    if (target == null) {
+      // As for {@link}; the part keeps the name as written.
+      warn(
+          e,
+          "Unresolved Javadoc reference %s; check spelling, source paths and classpath.",
+          thrown.getExceptionName());
+    }
     String name = target == null ? thrown.getExceptionName().toString() : id(target);
     // Inheritance must copy every description of the same exception.
     result.merge(
@@ -815,6 +870,7 @@ public final class SphinxDoclet implements Doclet {
     if (part == null) {
       if (method != null) {
         warn(
+            "inherit",
             e,
             "Cannot inherit %s; provide the overridden method's source documentation or"
                 + " document this part explicitly.",
@@ -968,6 +1024,16 @@ public final class SphinxDoclet implements Doclet {
         case StartElementTree start -> startElement(parent, start);
         case EndElementTree end -> parent.add("end").set("name", end.getName().toString());
         case InheritDocTree inherit -> inheritDoc(parent, owner, key, inherit, chain);
+        // The standard doclet shows an index term and a summary as text, and a system
+        // property as code. A quoted index term, which may contain spaces, loses its quotes.
+        case IndexTree index -> {
+          String term = index.getSearchTerm().toString();
+          parent.addText(
+              "text", term.matches("\".*\"") ? term.substring(1, term.length() - 1) : term);
+        }
+        case SummaryTree summary -> emit(parent, owner, key, summary.getSummary(), chain);
+        case SystemPropertyTree property ->
+            parent.addText("code", property.getPropertyName().toString());
         case ReturnTree ret -> {
           parent.addText("text", "Returns ");
           emit(parent, owner, "return", ret.getDescription(), chain);
@@ -1023,8 +1089,27 @@ public final class SphinxDoclet implements Doclet {
       parent.addText("literal", "[missing link target]");
       return;
     }
-    var link = parent.add("link").set("plain", Boolean.toString(plain));
     var target = resolve(owner, ref);
+    // Type parameters and modules have no page in the model; they stay code text.
+    if (target instanceof TypeParameterElement || target instanceof ModuleElement) {
+      if (!plain) {
+        parent.add("start").set("name", "code").set("closed", "false");
+      }
+      if (label.isEmpty()) {
+        String name =
+            target instanceof ModuleElement module
+                ? module.getQualifiedName().toString()
+                : target.getSimpleName().toString();
+        parent.addText("text", name);
+      } else {
+        emit(parent, owner, "label", label, new HashSet<>());
+      }
+      if (!plain) {
+        parent.add("end").set("name", "code");
+      }
+      return;
+    }
+    var link = parent.add("link").set("plain", Boolean.toString(plain));
     link.set("target", target == null ? ref.toString() : id(target));
     if (target == null) {
       warn(