Summary

Some javadoc may contain multiple conflicting links applied to the same content. This overlap can result in inconsistent behavior, as different runs of javadoc may resolve the links differently.

Problem

Consider a case where a developer tries to link text to a declaration but matches the same text to more than one substring or regex

public interface Test {
    /**
    * {@code Test obj1}
    * {@snippet lang = java:
    * // @link substring="ab" target="Test#ab" :
    * obj1.ab(a()); // @link substring="a" target="#a"
    *}
    */
    int a();
    void ab(int i);
}

javadoc cannot reliably determine which link to resolve and may select different links based on arbitrary factors. This behavior is unintended and results from user errors.

Solution

Javadoc will reject snippets containing multiple links applied to the same text.

Here is an example of the error message :

```
Test.java:4: error: Snippet link tags: Test#ab and #a overlap in obj1.ab(a());
                             * {@snippet lang = java:
                               ^
```

Specification

The specification is updated to explicitly prohibit overlapping links

diff --git a/doc-comment-spec.md b/doc-comment-spec.md
--- a/javadoc/doc-comment-spec.md
+++ b/javadoc/doc-comment-spec.md
@@ -1469,6 +1469,11 @@
 Specify the target with the `target` parameter.  The form of its value is the
 same as used by the standard inline `link` tag.

+##### <span id="overlapping-link">Overlapping links</span>
+
+If multiple `@link` tags apply to the same text within a snippet, javadoc emits an error.
+Overlapping links - whether from `substring` or `regex` - are not permitted
+
 <hr style="width:10%; margin:1em 0 0 0">

 Introduced in JDK 18.