On Mon, 25 Jul 2022 15:10:36 GMT, Hannes Wallnöfer <[email protected]> wrote:
> This is a simple change to automatically generate `id` attributes for HTML
> headers in documentation comments.
>
> I decided to leave the functionality in `HtmlDocletWriter` rather than moving
> it to `HtmlIds` because it uses the same helper methods
> as`commentTagsToContent`.
>
> The value of the `id` attribute id derived from the content of the header tag
> with spaces and other non-word characters replaced by `-`. A `-hdr` suffix is
> appended to avoid collisions with other ids. If there are duplicate values an
> int counter is appended to make them unique.
Some inline comments/questions.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
line 1762:
> 1760: private boolean hasIdAttribute(StartElementTree node) {
> 1761: return node.getAttributes().stream().anyMatch(
> 1762: dt -> equalsIgnoreCase(((AttributeTree)dt).getName(),
> "id"));
Do you need to filter/map the stream to ensure no class cast exceptions?
Can the attributes include `ErroneousTree`?
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
line 1791:
> 1789: if (!idValue.isEmpty()) {
> 1790: // Make id unique
> 1791: idValue = idValue + "-hdr";
Would it be better to use `header` rather than just `hdr` ?
Better still, `heading` seems to be the term in the HTML spec; `header` is also
used, but not for headings.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
line 1800:
> 1798: }
> 1799: content.add("id=\"").add(idValue).add("\"");
> 1800: }
This part of the algorithm, to create an `id` from the text contents of a
header, still feels like it belongs in `HtmlIds`. It feels like we should have
HtmlIds.getIdForHeader(CharSequence headerText)
or something like that
-------------
PR: https://git.openjdk.org/jdk/pull/9627
