Skip to content

feat: report implicit inheritance failures as java.inherit and warn about unresolved @throws - #73

Merged
r4sky0 merged 4 commits into
mainfrom
feat/inherit-warning-category
Nov 11, 2026
Merged

r4sky0 merged 4 commits into
mainfrom
feat/inherit-warning-category

Conversation

@r4sky0

@r4sky0 r4sky0 commented Nov 10, 2026

Copy link
Copy Markdown
Owner

Summary

Extraction warnings that the user cannot fix get their own category, and two warnings say what is wrong.

 toString() overrides Object.toString() and has no comment
-  WARNING: ... Cannot inherit ...            [java.extract]
+  WARNING: ... Cannot inherit ...            [java.inherit]

 @todo later
-  Unsupported block tag UNKNOWN_BLOCK_TAG
+  Unsupported block tag @todo

 @throws MissingEx when ...
-  no warning
+  Unresolved Javadoc reference MissingEx     [java.extract]
  • In the showcase, 98 of 106 extraction warnings are "Cannot inherit": overrides of JDK methods, whose sources cannot be supplied. suppress_warnings = ["java.inherit"] now silences these and keeps the rest.
  • <diagnostic> gains an optional kind: inherit, or extract when absent. Readers reject other kinds. The attribute is additive in schema 1; docs/schema.md and docs/troubleshooting.rst describe it.
  • A failed explicit {@inheritDoc} stays java.extract, because it leaves a marker in the output.
  • The CLI's --warnings-as-errors still fails on every diagnostic.
  • The showcase baseline records java.extract 8 and java.inherit 98.

Evidence

  • Before: test_implicit_inheritance_warnings_have_their_own_category, test_model_accepts_only_known_diagnostic_kinds and test_unresolved_throws_names_warn_like_links fail. test_unknown_block_tags_still_warn expected the old text.
    After: all pass.
  • On this branch: pytest -q 142 passed, pre-commit run --all-files passes, sphinx-build -W --keep-going -n docs passes.
  • showcase/build.py on this branch: every category equals the new baseline in Furo, Read the Docs and Alabaster. Lumina added one local warning, "npx not found", because Node was not on PATH on the machine used.
  • Not run on this branch alone: the browser checks.

Merge Danger

Door: two-way

Blast Radius: warnings

An upgrade can turn a passing -W build red in two ways:

  • A project that suppresses java.extract to hide "Cannot inherit" sees those warnings again until it adds java.inherit.
  • A @throws name that does not resolve now warns.

If the first counts as breaking, the title needs feat!.

Most extraction warnings in ordinary projects are "Cannot inherit" for
overrides of JDK methods such as toString, whose sources cannot be
added. They shared java.extract with unresolved links and malformed
Javadoc, so silencing them hid real problems. <diagnostic> gains an
optional kind, inherit or extract, which Sphinx uses as the warning
subtype, so suppress_warnings = ["java.inherit"] works. The schema
stays version 1; read_model validates the kind. Explicit inheritDoc
failures stay extract because they leave a marker in the output.
"Unsupported block tag UNKNOWN_BLOCK_TAG" hid which tag was meant; the
warning now names the tag as written, such as @todo. A @throws or
@exception name that does not resolve, such as a misspelled exception,
now warns like an unresolved {@link}; the part is unchanged.
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

@r4sky0
r4sky0 enabled auto-merge (squash) November 11, 2026 06:36
@r4sky0
r4sky0 merged commit a940118 into main Nov 11, 2026
19 checks passed
@r4sky0
r4sky0 deleted the feat/inherit-warning-category branch November 11, 2026 06:47
r4sky0 added a commit that referenced this pull request Nov 14, 2026
🤖 I have created a release *beep* *boop*
---


##
[0.7.0](v0.6.0...v0.7.0)
(2026-11-11)


### Features

* render more Javadoc HTML and inline tags natively, and highlight
&lt;pre&gt; leniently
([#72](#72))
([6b851cb](6b851cb))
* report implicit inheritance failures as java.inherit and warn about
unresolved [@throws](https://github.com/throws)
([#73](#73))
([a940118](a940118))


### Bug Fixes

* publish files with the umask's permissions, ignore JVM option notices
and accept an integer java_release
([#70](#70))
([99b9a76](99b9a76))
* resolve summary links through intersphinx, nested external types,
signature-only types and spaced member spellings
([#74](#74))
([b75a4ce](b75a4ce))
* show modifiers, field order and &lt;br&gt; summaries as the standard
doclet does
([#71](#71))
([cd7cd85](cd7cd85))
* survive links to type parameters and modules, and table rows without
cells ([#69](#69))
([b4127fc](b4127fc))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: r4sky0 <9093316+r4sky0@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant