RFR: 8346659: SnippetTaglet should report an error if provided ambiguous links [v8]

[Hannes Wallnöfer]

On Tue, 25 Feb 2025 17:39:24 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Some javadoc snippets can match multiple links to the same content, leading to different results in different javadoc runs.
>> This patch proposes emitting an error when such cases are encountered.
>> 
>> There is a very trivial, unrelated change in `TestGlobalHtml.java` because I noticed some whitespace wasn't right.
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   trim error message

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SnippetTaglet.java line 151:

> 149:                                 var body = tag.getBody().toString();
> 150:                                 var pos = ((DCSnippet) tag).getStartPosition()
> 151:                                         + Math.max(body.indexOf(linkTarget), body.indexOf(l.target()));

Doing a `String.indexOf` on the snippet body is not a good way to do this. It will often return the wrong result, especially if the link target is a class name. 

Sorry Nizar, I was not aware that we don't have any position information anymore at this point when I suggested to look into this. After reading the code, it seems we'd have to check for this condition earlier in the `snippet.Parser` code in order to get a reliable position within the snippet.

I suggest to for now go back to the previous version that just reports the start of the snippet tag, and maybe file a bug to find a better solution, but I would say it isn't a high priority issue.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/23328#discussion_r1971170031