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

[Nizar Benalla]

On Thu, 20 Feb 2025 16:54:33 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:
> 
>   respond to feedback

I didn't realize this earlier but the order of the references in the error message isn't always the same 

nizar-mac! $ cat One.java                                                                                
package p;
public interface One {
    /**
     * {@code One obj1}
     * {@snippet lang = java:
     * // @link substring="ab" target="One#ab" :
     * obj1.ab(a()); // @link substring="a" target="#a"
     *} class comment
     */
    int a();
    void ab(int i);
}% 

nizar-mac! $ /.../javadoc One.java
Loading source file One.java...
.....
One.java:5: error: snippet link tags: One#ab and #a overlap in obj1.ab(a());
     * {@snippet lang = java:
       ^
.....
nizar-mac! $ /.../javadoc One.java
Loading source file One.java...
....
One.java:5: error: snippet link tags: #a and One#ab overlap in obj1.ab(a());
     * {@snippet lang = java:
       ^
.....

I had to update the test slightly

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

PR Comment: https://git.openjdk.org/jdk/pull/23328#issuecomment-2674797755