Skip to content

feat: render more Javadoc HTML and inline tags natively, and highlight <pre> leniently - #72

Merged
r4sky0 merged 3 commits into
mainfrom
feat/more-javadoc-html
Nov 11, 2026
Merged

r4sky0 merged 3 commits into
mainfrom
feat/more-javadoc-html

Conversation

@r4sky0

@r4sky0 r4sky0 commented Nov 10, 2026

Copy link
Copy Markdown
Owner

Summary

Common Javadoc that was dropped, shown raw or warned about now renders as native nodes.

In the comment Before Now
2<sup>31</sup>, <sub> 231 and a warning superscript, subscript
<h1> to <h6> warning rubric: a heading outside the table of contents
<dl>, <dt>, <dd> warning definition list
<tt>, <kbd>, <samp> warning code
<var>, <cite>, <dfn> warning emphasis
<small> warning plain text
{@index term} the tag with its braces the term
{@summary text} the tag with its braces the text
{@systemProperty name} the tag with its braces the name as code
<pre> without lang a warning when the text is not Java highlighted as Java where possible, no warning
  • <pre> with a lang attribute still warns when the text does not match the language.
  • The Widget fixture comment gains a heading, a definition list, <sup>, <kbd> and {@systemProperty}, so the browser checks cover the new rendering.
  • docs/javadoc-support.rst and the limits in docs/compatibility.rst are updated.

Evidence

  • Before: test_more_javadoc_html_and_inline_tags_render_natively fails with three diagnostics. test_preformatted_text_without_lang_is_highlighted_leniently fails, and a strict build reports misc.highlighting_failure.
    After: both pass.
  • On this branch: pytest -q 141 passed, pre-commit run --all-files passes, sphinx-build -W --keep-going -n docs passes.
  • On a tree that holds this change together with six related ones, the showcase drops from 31 to 14 java.html warnings and from 20 to 0 highlighting failures, and the browser checks pass in all five themes. Neither was run on this branch alone.
  • This PR leaves showcase.json alone. Counts below the baseline pass; lowering it follows separately.

Merge Danger

Door: two-way

Blast Radius: rendering

Comments that used these elements change appearance on every page. Headings do not enter the page's table of contents. Content directly inside <dl>, outside <dt> and <dd>, warns.

A <pre> without lang was highlighted strictly as Java, so result tables
and other plain text warned misc.highlighting_failure (20 warnings in
the showcase), although Javadoc never highlights <pre>. Such blocks
keep Java but set force. Blocks with an explicit lang, including
snippets, stay strict.
2<sup>31</sup> rendered as 231, headings, <tt> and <dl> only warned, and
{@index}, {@summary} and {@systemProperty} appeared literally with
braces. <sup> and <sub> now become superscript and subscript, <h1> to
<h6> a rubric, <tt>, <kbd> and <samp> literals, <var>, <cite> and <dfn>
emphasis, <small> plain text, and <dl>, <dt> and <dd> a definition
list. The doclet emits an index term and a summary as text and a
system property as code, as the standard doclet shows them.
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

@r4sky0
r4sky0 enabled auto-merge (squash) November 11, 2026 06:23
@r4sky0
r4sky0 merged commit 6b851cb into main Nov 11, 2026
19 checks passed
@r4sky0
r4sky0 deleted the feat/more-javadoc-html branch November 11, 2026 06:35
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