[r4sky0]

Stacked on #46. Retarget it to main once #46 merges.

Compared with Javadoc, member pages left out two things readers rely on: which method a declaration overrides or implements, and the return type and modifiers in the member summary. The summary also showed erased parameter types, such as of(Object, Object) for of(L left, R right).

Changes

• "Specified by" and "Overrides" notes. The doclet now writes specifiedBy and overrides parts right after the description, following the standard doclet's rules, which I checked against javadoc output:
  • One "Specified by" for each interface method the method implements, taken from the declaring type's interfaces and their superinterfaces. A listed method that another listed method overrides is dropped.
  • Then the nearest superclass method: "Overrides", or "Specified by" when that method is abstract. That is why record methods read "Specified by: equals in class Record".
  • Each part is a method link, then in class or in interface, then a type link. Links to ancestors outside the documented API fall back to text, as summary links already do, so the showcase gets no new warnings.
• Member summaries.
  • Methods and fields get a first column like Javadoc's "Modifier and Type", such as static <L, R> Pair<L, R>, final L and static final String. It is built from the signature tokens without annotations or public, and without abstract in interfaces. Its types link like signature types.
  • Member links show the declared parameters: of(L left, R right), Widget(String label).
  • Type summaries, constructor summaries and enum constants keep two columns.
• docs/schema.md describes the two new part kinds. They are additive in schema 1, so older renderers show them under their kind name. docs/usage.rst describes the notes and the summary column.
• Tests:
  • A new oracle test compares the notes and both summary columns with the standard doclet on an abstract generic class and a subclass.
  • The integration test checks the "Specified by" link on the fixture page.
  • The navigation test checks the new summary columns.

Not included

• Javadoc's type arguments on the ancestor (Map.Entry<T,T>) and the summary's filter tabs (static, instance, abstract).
• "Methods inherited from", the inheritance tree, known subclasses, and the class-use, tree and deprecated-list pages.

Checks run locally

• pre-commit hooks: pass.
• pytest -q: 137 passed.
• showcase/build.py: warning counts equal the baseline in every theme. Checked the Pair page by hand: hashCode reads "Specified by: hashCode in interface Map.Entry" and "Overrides: hashCode in class Object", as in Javadoc.
• sphinx-build -W --keep-going -n docs: passes. The text builder renders the three-column tables.
• Browser checks (tests/visual_check.py, after building the fixture in all five themes): pass.

[github-actions]

Documentation preview for dce26dc: https://r4sky0.github.io/sphinx-java-autodoc/pr-preview/pr-47/