RFR: JDK-8289332: Auto-generate ids for user-defined headings

[Jonathan Gibbons]

On Mon, 25 Jul 2022 15:10:36 GMT, Hannes Wallnöfer <hannesw at openjdk.org> 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