On Tue, 25 Feb 2025 13:45:31 GMT, Nizar Benalla <nbena...@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 with a new target base due to a > merge or a rebase. The incremental webrev excludes the unrelated changes > brought in by the merge/rebase. The pull request contains nine additional > commits since the last revision: > > - Improve error message by pointing to location of links > - Merge branch 'master' into snippet-non-rep > - fix test bug > - respond to feedback > - Merge remote-tracking branch 'origin/master' into snippet-non-rep > - Merge remote-tracking branch 'upstream/master' into snippet-non-rep > - adjusting error message > - Merge remote-tracking branch 'upstream/master' into snippet-non-rep > - emit error when encountering ambigious link The carret position points to the second link (of the two conflicting links) Here are some examples, there is some text after the carret but I found it hard to deal with. nizar-mac! $ cat One.java package p; public interface One { int j=0; /** * * {@code One obj1} * {@snippet lang = java: * // @link substring="ab" target="One#ab" : * var temp = obj1.ab(a()); // @link substring="a" target="#a" *} class comment */ int a(); void ab(int i); } nizar-mac! $ javadoc -d ./out One.java Loading source file One.java... Constructing Javadoc information... Building index for all the packages and classes... Standard Doclet version 25-internal-LTS-2025-02-20-1634195.nizarbenalla... Building tree for all the packages and classes... Generating ./out/p/One.html... One.java:12: warning: no @return int a(); ^ One.java:2: warning: no comment public interface One { ^ One.java:3: warning: no comment int j=0; ^ One.java:8: error: snippet link tags: One#ab and #a overlap in * // @link substring="ab" target="One#ab" : ^ var temp = obj1.ab(a()); One.java:13: warning: no comment void ab(int i); ^ Generating ./out/p/package-summary.html... Generating ./out/p/package-tree.html... Generating ./out/constant-values.html... Generating ./out/overview-tree.html... Generating ./out/allclasses-index.html... Building index for all classes... Generating ./out/allpackages-index.html... Generating ./out/index-all.html... Generating ./out/search.html... Generating ./out/index.html... Generating ./out/help-doc.html... 1 error 4 warnings nizar-mac! $ cat Two.java package p; import java.lang.classfile.CodeBuilder; import java.lang.classfile.CodeElement; import java.lang.classfile.CodeModel; import java.lang.classfile.CodeTransform; import java.lang.classfile.Label; import java.lang.classfile.PseudoInstruction; import java.lang.classfile.attribute.CodeAttribute; public interface Two { int j=0; /** * {@snippet lang=java : * cob.with(lt); // @link substring="with" target="CodeBuilder#with" * // @link substring="labelBinding" target="CodeBuilder#labelBinding" : * cob.labelBinding(lt.label()); // @link substring="label" target="#label" * } */ int a(); void ab(int i); } nizar-mac! $ javadoc -d ./out Two.java Loading source file Two.java... Constructing Javadoc information... Building index for all the packages and classes... Standard Doclet version 25-internal-LTS-2025-02-20-1634195.nizarbenalla... Building tree for all the packages and classes... Generating ./out/p/Two.html... Two.java:20: warning: no @return int a(); ^ Two.java:11: warning: no comment public interface Two { ^ Two.java:12: warning: no comment int j=0; ^ Two.java:16: error: snippet link tags: #label and CodeBuilder#labelBinding overlap in cob.with(lt); * // @link substring="labelBinding" target="CodeBuilder#labelBinding" : ^ cob.labelBinding(lt.label()); Two.java:21: warning: no comment void ab(int i); ^ Generating ./out/p/package-summary.html... Generating ./out/p/package-tree.html... Generating ./out/constant-values.html... Generating ./out/overview-tree.html... Generating ./out/allclasses-index.html... Building index for all classes... Generating ./out/allpackages-index.html... Generating ./out/index-all.html... Generating ./out/search.html... Generating ./out/index.html... Generating ./out/help-doc.html... The generated documentation contains diagnostic markers for invalid input. 1 error 4 warnings ------------- PR Comment: https://git.openjdk.org/jdk/pull/23328#issuecomment-2682056417