sphinx-java-autodoc 0.3.0__tar.gz → 0.5.0__tar.gz

{sphinx_java_autodoc-0.3.0 → sphinx_java_autodoc-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sphinx-java-autodoc
-Version: 0.3.0
+Version: 0.5.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

{sphinx_java_autodoc-0.3.0 → sphinx_java_autodoc-0.5.0}/docs/javadoc-support.rst

@@ -20,6 +20,11 @@ Tags and HTML
 ``@author``, ``@version`` and the ``@serial`` tags are omitted silently, as in the
 standard doclet's default output. Other custom tags warn.
 
+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.
+
 Constant values
 ---------------
 

{sphinx_java_autodoc-0.3.0 → sphinx_java_autodoc-0.5.0}/docs/schema.md

@@ -26,12 +26,20 @@ not a general XML document interchange service. No external entities are fetched
   parameter or record component. `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`, `param`, `typeparam`, `return`, `throws`, `see`,
-  `since`, `deprecated`, `apiNote`, `implSpec`, `implNote`) and a `label`. The three
-  note kinds are additive in schema 1: older renderers show them under their kind name. Parameter labels follow the child declaration
+- `doc/part`: `kind` (`body`, `specifiedBy`, `overrides`, `param`, `typeparam`,
+  `return`, `throws`, `see`, `since`, `deprecated`, `apiNote`, `implSpec`, `implNote`)
+  and a `label`. The three note kinds, `specifiedBy` and `overrides` are additive in
+  schema 1: older renderers show them under their kind name. `specifiedBy` and
+  `overrides` follow `body`: one `specifiedBy` per implemented interface method, then
+  the superclass method as `overrides`, or `specifiedBy` when it is abstract. Each
+  holds a method `link`, ` in class ` or ` in interface ` text, and a type `link`. Parameter labels follow the child declaration
   even when prose is inherited. Part contents are an ordered token sequence.
+  `typeparam` parts document the type parameters of generic types and methods.
   Throws labels name the overriding method's exception after generic substitution;
-  type variables use their declared names.
+  type variables use their declared names. A `throws` part whose exception is a type
+  also carries `target`, `role` and the external Javadoc `path`, `module` and
+  `fragment`, as `link` does, and its label is the type's name without its package.
+  These attributes are additive in schema 1.
   Repeated `throws` descriptions for one exception share a part, separated by
   paragraph tokens, so explicit and omitted inheritance preserve all descriptions.
 - Tokens: `text`, `literal`, `code`, `link`, `start`, `end`. Text is element text,
@@ -52,7 +60,9 @@ not a general XML document interchange service. No external entities are fetched
 - `link`: `target` is the compiler's canonical symbol ID; `role` identifies the
   domain object kind. `path`, `module`, `fragment` hold external Javadoc location
   metadata; `plain` distinguishes link/plainlink presentation. Children form the
-  label. An unresolved link has no resolved location and has a diagnostic.
+  label; a comment link without one gets the standard doclet's text, such as
+  `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.
 
@@ -61,8 +71,11 @@ Identity examples: `example.Outer.Inner`, `example.Outer#FIELD`,
 Parameters in canonical IDs are fully qualified erased types; varargs use `[]`.
 External Javadoc fragments instead preserve declared type variables and use `...`
 for varargs, as verified against the standard doclet. Return types and
-parameter names do not affect IDs. HTML anchors are `java-` plus UTF-8 bytes of the
-ID encoded in hexadecimal: deterministic, reversible and collision-free.
+parameter names do not affect IDs. HTML anchors are `java:` plus the ID, with `#`
+replaced by `-` and `<init>` by `new`, as in `java:example.Outer-find(java.lang.String,int[])`
+and `java:example.Outer-new()`. They are deterministic, reversible and collision-free:
+docutils never generates `:` in IDs, Java names never contain `-`, and the keyword
+`new` cannot name a method.
 
 Declarations and diagnostics are sorted; no build timestamp or source path is
 stored. Renderers derive a declaration's file from its package and top-level type

{sphinx_java_autodoc-0.3.0 → sphinx_java_autodoc-0.5.0}/docs/usage.rst

@@ -95,7 +95,9 @@ Other directives work the same way:
 
 ``java:autopackage`` renders the ``package-info.java`` comment.
 ``java:autosummary`` lists each entry with a link and its first sentence; unknown
-entries warn as ``java.summary``. Generated pages consist of these directives.
+entries warn as ``java.summary``. As in Javadoc, members are listed with their
+declared parameters, and methods and fields get a column with their modifiers and
+type, such as ``static <L, R> Pair<L, R>``. Generated pages consist of these directives.
 
 What gets documented
 --------------------
@@ -105,7 +107,12 @@ What gets documented
   protected types.
 - Only declared members are listed. An overriding method inherits its ancestor's
   comment; other inherited methods stay on the declaring type's page.
+- As in Javadoc, an overriding method notes what it implements or overrides:
+  "Specified by: ``convert`` in interface ``Transformer``", or "Overrides:
+  ``hashCode`` in class ``Object``".
 - Nested types get their own pages.
+- Signatures show only ``@Documented`` annotations, as the standard doclet does, so
+  ``@Override`` and ``@SuppressWarnings`` are left out.
 
 Roles
 -----
@@ -147,7 +154,8 @@ source root, such as ``com/example/Widget.java``) and ``line``:
            f"{info['source']}#L{info['line']}"
        )
 
-``line`` is empty for compiler-generated members, such as an enum's ``values()``.
+``line`` is empty for packages and for compiler-generated members, such as an enum's
+``values()``.
 With several source roots, choose the root in ``linkcode_resolve``, for example by
 checking which root contains ``source``.
 

{sphinx_java_autodoc-0.3.0 → sphinx_java_autodoc-0.5.0}/examples/standalone/src/demo/Widget.java

@@ -50,7 +50,7 @@ public class Widget implements Transformer<String> {
      * @throws IllegalArgumentException {@inheritDoc}
      */
     @Override public String convert(String renamed) throws IllegalArgumentException { return renamed; }
-    /** Converts a number to text.
+    /** Converts a number to text, such as "42"...
      * @param number the number
      * @return decimal text
      */

{sphinx_java_autodoc-0.3.0 → sphinx_java_autodoc-0.5.0}/pyproject.toml

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

{sphinx_java_autodoc-0.3.0 → sphinx_java_autodoc-0.5.0}/src/sphinx_java_autodoc/domain.py

@@ -29,7 +29,9 @@ LOGGER = logging.getLogger(__name__)
 
 
 def anchor(symbol: str) -> str:
-    return "java-" + symbol.encode("utf-8").hex()
+    # Docutils IDs never contain ":", Java names never contain "-", and the keyword
+    # "new" cannot name a method, so these readable anchors cannot collide.
+    return "java:" + symbol.replace("#<init>(", "#new(").replace("#", "-")
 
 
 def role_for(element):
@@ -98,6 +100,49 @@ def signature_nodes(tokens) -> list[nodes.Node]:
     return result
 
 
+# Javadoc's "Modifier and Type" column leaves out visibility and implementation details.
+SUMMARY_MODIFIERS = {"protected", "static", "final", "abstract", "default"}
+
+
+def summary_type(element) -> list[nodes.Node]:
+    """A member's modifiers, type parameters and type, as in Javadoc's summary column."""
+    tokens = []
+    sig = list(element.find("sig"))
+    i = 0
+    while i < len(sig) and sig[i].tag != "n":
+        if sig[i].tag == "t" and sig[i].text == "@":
+            # An annotation: "@", its type, optional arguments and a space.
+            i += 2
+            if i < len(sig) and sig[i].tag == "t" and sig[i].text.startswith("("):
+                i += 1
+        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"):
+            modifiers.append(text)
+    if tokens and tokens[-1].tag == "t" and tokens[-1].text == " ":
+        tokens.pop()
+    prefix = [nodes.Text(" ".join(modifiers) + " ")] if modifiers else []
+    return prefix + signature_nodes(tokens)
+
+
+def summary_label(element) -> str:
+    """A member's name with declared parameters, as in Javadoc's summaries."""
+    params = element.find("sig/params")
+    if element.tag == "type" or params is None:
+        return local_name(element)
+    declared = ("".join(t.text or "" for t in param) for param in params)
+    return f"{element.find('sig/n').text}({', '.join(declared)})"
+
+
 def display_name(symbol: str) -> str:
     owner, _, member = symbol.partition("#")
     return f"{owner}.{member_label(symbol)}" if member else symbol
@@ -261,34 +306,49 @@ class AutoPackage(JavaDirective):
             self.missing("package", package, "package")
             return []
         domain = self.env.get_domain("java")
-        target = nodes.target("", "", ids=[anchor(package)])
-        self.state.document.note_explicit_target(target)
-        domain.data["objects"][package] = (self.env.docname, anchor(package), "package")
+        target = anchor(package)
+        # Javadoc's package pages open with this declaration; as an object description,
+        # the package's notes and fields look like those of its types in every theme.
+        desc = addnodes.desc(
+            "",
+            domain="java",
+            objtype="package",
+            desctype="package",
+            classes=["java", "package"],
+        )
+        sig = addnodes.desc_signature("", "", ids=[target], fullname=package)
+        sig += addnodes.desc_sig_keyword("package", "package")
+        sig += addnodes.desc_sig_space()
+        sig += addnodes.desc_name(package, package)
+        self.state.document.note_explicit_target(sig)
+        desc += sig
+        desc += addnodes.desc_content("", *documentation(element, self.get_location()))
+        domain.data["objects"][package] = (self.env.docname, target, "package")
         index = addnodes.index(
-            entries=[("single", f"{package} (Java package)", anchor(package), "", None)]
+            entries=[("single", f"{package} (Java package)", target, "", None)]
         )
-        return [index, target, *documentation(element, self.get_location())]
+        return [index, desc]
 
 
 class AutoSummary(JavaDirective):
-    """A table of linked names and first sentences, like sphinx.ext.autosummary."""
+    """A table of linked names and first sentences, like sphinx.ext.autosummary.
+
+    Methods and fields get a first column with their modifiers and type, as in Javadoc.
+    """
 
     has_content = True
 
     def run(self):
         self.env.note_dependency(self.env.java_model_path)
         table = nodes.table("", classes=["autosummary", "longtable", "java"])
-        group = nodes.tgroup("", cols=2)
-        group += nodes.colspec("", colwidth=10)
-        group += nodes.colspec("", colwidth=90)
-        body = nodes.tbody()
+        rows = []
         for line in self.content:
             symbol = re.sub(r"\s+", "", line)
             if not symbol:
                 continue
             element = self.lookup(symbol)
             if element is not None:
-                label = local_name(element)
+                label = summary_label(element)
             elif symbol in PACKAGES:
                 element, label = PACKAGES[symbol], symbol
             else:
@@ -303,17 +363,32 @@ class AutoSummary(JavaDirective):
                 refexplicit=True,
                 refwarn=True,
             )
-            text = nodes.paragraph("")
+            text = nodes.paragraph("", support_smartquotes=False)
             if deprecated(element):
                 text += [nodes.strong("", "Deprecated."), nodes.Text(" ")]
             text.extend(summary(element, self.get_location()))
-            body += nodes.row(
-                "",
-                nodes.entry("", nodes.paragraph("", "", link)),
-                nodes.entry("", text),
-            )
-        if not body.children:
+            typed = element.tag == "member" and element.get("kind") in {
+                "method",
+                "field",
+            }
+            kind = nodes.literal("", "", *summary_type(element)) if typed else None
+            rows.append((kind, nodes.paragraph("", "", link), text))
+        if not rows:
             return []
+        typed = any(kind is not None for kind, _, _ in rows)
+        widths = (15, 25, 60) if typed else (10, 90)
+        group = nodes.tgroup("", cols=len(widths))
+        group.extend(nodes.colspec("", colwidth=width) for width in widths)
+        body = nodes.tbody()
+        for kind, name, text in rows:
+            cells = []
+            if typed:
+                cells.append(
+                    nodes.entry()
+                    if kind is None
+                    else nodes.entry("", nodes.paragraph("", "", kind))
+                )
+            body += nodes.row("", *cells, nodes.entry("", name), nodes.entry("", text))
         group += body
         table += group
         return [table]

{sphinx_java_autodoc-0.3.0 → sphinx_java_autodoc-0.5.0}/src/sphinx_java_autodoc/extractor.py

@@ -16,7 +16,7 @@ from sphinx.errors import ExtensionError
 
 from .model import Model, read_model
 
-VERSION = "0.3.0"  # x-release-please-version
+VERSION = "0.5.0"  # x-release-please-version
 DOCLET = Path(__file__).parent / "java" / "SphinxDoclet.java"
 PACKAGE = re.compile(r"[^\W\d]\w*(?:\.[^\W\d]\w*)*")
 

{sphinx_java_autodoc-0.3.0 → sphinx_java_autodoc-0.5.0}/src/sphinx_java_autodoc/java/SphinxDoclet.java

@@ -3,6 +3,7 @@ package sphinxjava;
 import com.sun.source.doctree.*;
 import com.sun.source.util.DocTreePath;
 import com.sun.source.util.DocTrees;
+import java.lang.annotation.Documented;
 import java.nio.file.*;
 import java.util.*;
 import java.util.function.Consumer;
@@ -301,7 +302,7 @@ public final class SphinxDoclet implements Doclet {
 
   private void sig(Xml parent, Element e) {
     var sig = parent.add("sig");
-    for (var annotation : e.getAnnotationMirrors()) {
+    for (var annotation : documented(e.getAnnotationMirrors())) {
       annotation(sig, annotation);
       sig.addText("t", " ");
     }
@@ -344,7 +345,7 @@ public final class SphinxDoclet implements Doclet {
       var params = sig.add("params");
       for (var component : type.getRecordComponents()) {
         var param = params.add("param");
-        for (var annotation : component.getAnnotationMirrors()) {
+        for (var annotation : documented(component.getAnnotationMirrors())) {
           annotation(param, annotation);
           param.addText("t", " ");
         }
@@ -380,7 +381,7 @@ public final class SphinxDoclet implements Doclet {
     for (int i = 0; i < parameters.size(); i++) {
       var parameter = parameters.get(i);
       var param = params.add("param");
-      for (var annotation : parameter.getAnnotationMirrors()) {
+      for (var annotation : documented(parameter.getAnnotationMirrors())) {
         annotation(param, annotation);
         param.addText("t", " ");
       }
@@ -448,7 +449,7 @@ public final class SphinxDoclet implements Doclet {
   }
 
   private void typeTokens(Xml sig, TypeMirror type) {
-    for (var annotation : type.getAnnotationMirrors()) {
+    for (var annotation : documented(type.getAnnotationMirrors())) {
       annotation(sig, annotation);
       sig.addText("t", " ");
     }
@@ -501,13 +502,24 @@ public final class SphinxDoclet implements Doclet {
 
   /** A link to a type: its compiler ID, external Javadoc location and nested simple name. */
   private void typeReference(Xml sig, TypeElement type) {
-    String pkg = elements.getPackageOf(type).getQualifiedName().toString();
-    String name = type.getQualifiedName().toString();
     var reference = sig.add("r").set("target", id(type));
     javadocLocation(reference, type);
-    reference
-        .node()
-        .setTextContent(Xml.safe(pkg.isEmpty() ? name : name.substring(pkg.length() + 1)));
+    reference.node().setTextContent(Xml.safe(localName(type)));
+  }
+
+  /** The type's name without its package, such as {@code Map.Entry}. */
+  private String localName(TypeElement type) {
+    String pkg = elements.getPackageOf(type).getQualifiedName().toString();
+    String name = type.getQualifiedName().toString();
+    return pkg.isEmpty() ? name : name.substring(pkg.length() + 1);
+  }
+
+  /** The standard doclet shows only annotations whose type is {@code @Documented}. */
+  private static List<? extends AnnotationMirror> documented(
+      List<? extends AnnotationMirror> annotations) {
+    return annotations.stream()
+        .filter(a -> a.getAnnotationType().asElement().getAnnotation(Documented.class) != null)
+        .toList();
   }
 
   private void annotation(Xml sig, AnnotationMirror annotation) {
@@ -601,8 +613,14 @@ public final class SphinxDoclet implements Doclet {
   private void putParam(Map<String, Part> result, Element e, ParamTree param) {
     String name = param.getName().toString();
     String key = "param:" + name;
-    if (e instanceof ExecutableElement method) {
-      var declared = param.isTypeParameter() ? method.getTypeParameters() : method.getParameters();
+    List<? extends Element> declared = null;
+    if (param.isTypeParameter() && e instanceof Parameterizable generic) {
+      declared = generic.getTypeParameters();
+    } else if (e instanceof ExecutableElement method) {
+      declared = method.getParameters();
+    }
+    // Record components keep their names; positions follow renamed overriding parameters.
+    if (declared != null) {
       int index = -1;
       for (int i = 0; i < declared.size(); i++) {
         if (declared.get(i).getSimpleName().contentEquals(name)) {
@@ -761,8 +779,9 @@ public final class SphinxDoclet implements Doclet {
   private void documentation(Xml node, Element e) {
     var doc = node.add("doc");
     var own = parts(e);
-    var keys = new LinkedHashSet<>(own.keySet());
+    var keys = new LinkedHashSet<String>();
     keys.add("body");
+    keys.addAll(own.keySet());
     var method = overridingMethod(e);
     if (method != null) {
       for (int i = 0; i < method.getParameters().size(); i++) {
@@ -779,26 +798,121 @@ public final class SphinxDoclet implements Doclet {
       }
     }
     for (var key : keys) {
-      Part part = own.get(key);
-      if (part == null && method != null) {
-        part = findPart(e, key, new HashSet<>());
+      part(doc, e, own, method, key);
+      // The standard doclet notes overridden methods between the description and the tags.
+      if (key.equals("body")) {
+        overrides(doc, e);
+      }
+    }
+  }
+
+  private void part(
+      Xml doc, Element e, Map<String, Part> own, ExecutableElement method, String key) {
+    Part part = own.get(key);
+    if (part == null && method != null) {
+      part = findPart(e, key, new HashSet<>());
+    }
+    if (part == null) {
+      if (method != null) {
+        warn(
+            e,
+            "Cannot inherit %s; provide the overridden method's source documentation or"
+                + " document this part explicitly.",
+            key);
       }
-      if (part == null) {
-        if (method != null) {
-          warn(
-              e,
-              "Cannot inherit %s; provide the overridden method's source documentation or"
-                  + " document this part explicitly.",
-              key);
+      return;
+    }
+    var xml = doc.add("part").set("kind", key.split(":", 2)[0]).set("label", label(e, key, part));
+    if (key.startsWith(THROWS)
+        && elements.getTypeElement(key.substring(THROWS.length())) instanceof TypeElement thrown) {
+      xml.set("label", localName(thrown)).set("target", id(thrown)).set("role", "type");
+      javadocLocation(xml, thrown);
+    }
+    String context = key.startsWith(THROWS) ? THROWS + part.label() : key;
+    emit(xml, part.owner(), context, part.trees(), new HashSet<>());
+  }
+
+  /**
+   * The standard doclet's notes: "Specified by" for each implemented interface method, then
+   * "Overrides" for the superclass method, or "Specified by" when that method is abstract.
+   */
+  private void overrides(Xml doc, Element e) {
+    if (!(e instanceof ExecutableElement method)
+        || method.getKind() != ElementKind.METHOD
+        || method.getModifiers().contains(Modifier.STATIC)) {
+      return;
+    }
+    var owner = (TypeElement) method.getEnclosingElement();
+    var specified = new ArrayList<ExecutableElement>();
+    implemented(method, owner, owner.getInterfaces(), specified, new HashSet<>());
+    // An interface method that another listed method overrides adds nothing.
+    specified.removeIf(
+        a ->
+            specified.stream()
+                .anyMatch(
+                    b ->
+                        b != a && elements.overrides(b, a, (TypeElement) b.getEnclosingElement())));
+    specified.forEach(ancestor -> overridePart(doc, "specifiedBy", ancestor));
+    for (var type = owner.getSuperclass();
+        types.asElement(type) instanceof TypeElement superclass;
+        type = superclass.getSuperclass()) {
+      for (var candidate : superclass.getEnclosedElements()) {
+        if (candidate instanceof ExecutableElement ancestor
+            && ancestor.getKind() == ElementKind.METHOD
+            && visible(ancestor, false)
+            && elements.overrides(method, ancestor, owner)) {
+          boolean specifies = ancestor.getModifiers().contains(Modifier.ABSTRACT);
+          overridePart(doc, specifies ? "specifiedBy" : "overrides", ancestor);
+          return;
         }
+      }
+    }
+  }
+
+  /** Collects the methods of {@code interfaces} and their superinterfaces that method overrides. */
+  private void implemented(
+      ExecutableElement method,
+      TypeElement owner,
+      List<? extends TypeMirror> interfaces,
+      List<ExecutableElement> result,
+      Set<Element> seen) {
+    for (var type : interfaces) {
+      var face = (TypeElement) types.asElement(type);
+      if (!seen.add(face)) {
         continue;
       }
-      var xml = doc.add("part").set("kind", key.split(":", 2)[0]).set("label", label(e, key, part));
-      String context = key.startsWith(THROWS) ? THROWS + part.label() : key;
-      emit(xml, part.owner(), context, part.trees(), new HashSet<>());
+      for (var candidate : face.getEnclosedElements()) {
+        if (candidate instanceof ExecutableElement ancestor
+            && ancestor.getKind() == ElementKind.METHOD
+            && visible(ancestor, false)
+            && elements.overrides(method, ancestor, owner)) {
+          result.add(ancestor);
+        }
+      }
+      implemented(method, owner, face.getInterfaces(), result, seen);
     }
   }
 
+  /** A note such as "{@code hashCode} in class {@code Object}", linking both names. */
+  private void overridePart(Xml doc, String kind, ExecutableElement ancestor) {
+    var holder = (TypeElement) ancestor.getEnclosingElement();
+    var part = doc.add("part").set("kind", kind).set("label", "");
+    link(part, ancestor, ancestor.getSimpleName().toString());
+    part.addText("text", holder.getKind().isInterface() ? " in interface " : " in class ");
+    link(part, holder, localName(holder));
+  }
+
+  private void link(Xml parent, Element target, String text) {
+    var link =
+        parent
+            .add("link")
+            .set("plain", "false")
+            .set("target", id(target))
+            .set("role", role(target));
+    javadocLocation(link, target);
+    link.addText("text", text);
+  }
+
   /** Labels follow the documented declaration, even when the prose is inherited. */
   private static String label(Element e, String key, Part part) {
     if (key.startsWith(THROWS)) {
@@ -918,23 +1032,57 @@ public final class SphinxDoclet implements Doclet {
           "Unresolved Javadoc reference %s; check spelling, source paths and classpath.",
           ref);
     } else {
-      String role =
-          switch (target) {
-            case TypeElement _ -> "type";
-            case ExecutableElement _ -> "method";
-            case PackageElement _ -> "package";
-            default -> "field";
-          };
-      link.set("role", role);
+      link.set("role", role(target));
       javadocLocation(link, target);
     }
     if (label.isEmpty()) {
-      link.addText("text", ref.toString());
+      link.addText("text", target == null ? ref.toString() : linkLabel(owner, ref, target));
     } else {
       emit(link, owner, "label", label, new HashSet<>());
     }
   }
 
+  /**
+   * The standard doclet's text for a link without a label: {@code Map.Entry}, {@code
+   * String.format(String, Object...)}, or {@code of(L, R)} for a member of the same type.
+   */
+  private String linkLabel(Element owner, ReferenceTree ref, Element target) {
+    if (target instanceof PackageElement pkg) {
+      return pkg.getQualifiedName().toString();
+    }
+    if (target instanceof TypeElement type) {
+      return localName(type);
+    }
+    String signature = ref.getSignature();
+    String member = signature.substring(signature.indexOf('#') + 1);
+    if (target instanceof ExecutableElement method && !member.contains("(")) {
+      member +=
+          method.getParameters().stream()
+              .map(p -> linkType(p.asType()).replaceAll("^.*\\.", ""))
+              .collect(Collectors.joining(", ", "(", ")"));
+      if (method.isVarArgs()) {
+        member = member.substring(0, member.length() - 3) + "...)";
+      }
+    }
+    Element scope = owner;
+    while (scope != null && !(scope instanceof TypeElement)) {
+      scope = scope.getEnclosingElement();
+    }
+    var type = (TypeElement) target.getEnclosingElement();
+    return target.getKind() == ElementKind.CONSTRUCTOR || type.equals(scope)
+        ? member
+        : localName(type) + "." + member;
+  }
+
+  private static String role(Element target) {
+    return switch (target) {
+      case TypeElement _ -> "type";
+      case ExecutableElement _ -> "method";
+      case PackageElement _ -> "package";
+      default -> "field";
+    };
+  }
+
   /** Records where standard Javadoc publishes the target, for external Javadoc links. */
   private void javadocLocation(Xml link, Element target) {
     Element type = target;

{sphinx_java_autodoc-0.3.0 → sphinx_java_autodoc-0.5.0}/src/sphinx_java_autodoc/render.py

@@ -356,6 +356,9 @@ def comment(part: ET.Element, location, quiet: bool = False) -> list[nodes.Node]
             )
         elif not p.astext().strip():
             p.parent.remove(p)
+    # Javadoc prints comment text as written; Sphinx would curl quotes and join dots.
+    for node in root.children:
+        node["support_smartquotes"] = False
     return root.children
 
 
@@ -408,6 +411,8 @@ def quiet_reference(app, env, node, contnode):
 
 
 FIELD_TITLES = {
+    "specifiedBy": "Specified by",
+    "overrides": "Overrides",
     "param": "Parameters",
     "typeparam": "Type parameters",
     "return": "Returns",
@@ -427,10 +432,11 @@ def field(kind: str, items) -> nodes.field:
     for label, content in items:
         content = list(content)
         if label:
+            label = nodes.strong("", "", label)
             if content and isinstance(content[0], nodes.paragraph):
-                content[0].insert(0, [nodes.strong("", label), nodes.Text(" – ")])
+                content[0].insert(0, [label, nodes.Text(" – ")])
             else:
-                content.insert(0, nodes.paragraph("", "", nodes.strong("", label)))
+                content.insert(0, nodes.paragraph("", "", label))
         bodies.append(content)
     if len(bodies) == 1:
         body = nodes.field_body("", *bodies[0])
@@ -453,12 +459,22 @@ def documentation(element: ET.Element, location) -> list[nodes.Node]:
     for part in element.findall("doc/part"):
         content = comment(part, location)
         kind = part.get("kind")
+        if kind in {"specifiedBy", "overrides"}:
+            # Ancestors outside the documented API stay text, as in summaries.
+            for node in content:
+                for xref in node.findall(addnodes.pending_xref):
+                    xref["java:quiet"] = True
         if kind == "body":
             result.extend(content)
         elif kind == "deprecated":
             notice.extend(content)
         else:
-            fields_by_kind.setdefault(kind, []).append((part.get("label"), content))
+            label = part.get("label") and nodes.Text(part.get("label"))
+            if label and part.get("target"):
+                # A documented exception links to its type, as in signatures.
+                label = reference(part, [label])
+                label["refwarn"] = False
+            fields_by_kind.setdefault(kind, []).append((label, content))
     for kind, items in fields_by_kind.items():
         fields += field(kind, items)
     if notice is not None: