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
