RFR: 8346659: SnippetTaglet should report an error if provided ambiguous links [v7]
Nizar Benalla
nbenalla at openjdk.org
Tue Feb 25 13:56:54 UTC 2025
On Tue, 25 Feb 2025 13:45:31 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 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
More information about the javadoc-dev
mailing list