jdk
1/*
2* Copyright (c) 2012, 2024, Oracle and/or its affiliates. All rights reserved.
3* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4*
5* This code is free software; you can redistribute it and/or modify it
6* under the terms of the GNU General Public License version 2 only, as
7* published by the Free Software Foundation.
8*
9* This code is distributed in the hope that it will be useful, but WITHOUT
10* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12* version 2 for more details (a copy is included in the LICENSE file that
13* accompanied this code).
14*
15* You should have received a copy of the GNU General Public License version
16* 2 along with this work; if not, write to the Free Software Foundation,
17* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18*
19* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20* or visit www.oracle.com if you need additional information or have any
21* questions.
22*/
23
24/*
25* @test
26* @bug 7021614 8278373 8164094
27* @summary extend com.sun.source API to support parsing javadoc comments
28* @summary check references in at-see and {at-link} tags
29* @modules jdk.compiler
30* @build ReferenceTest
31* @compile -processor ReferenceTest -proc:only ReferenceTest.java
32*/
33
34import com.sun.source.doctree.DocCommentTree;35import com.sun.source.doctree.DocTree;36import com.sun.source.doctree.LinkTree;37import com.sun.source.doctree.ReferenceTree;38import com.sun.source.doctree.SeeTree;39import com.sun.source.doctree.TextTree;40import com.sun.source.util.DocTreePath;41import com.sun.source.util.DocTreePathScanner;42import com.sun.source.util.DocTrees;43import com.sun.source.util.TreePath;44
45import java.util.List;46import java.util.Set;47import java.util.stream.Collectors;48import javax.annotation.processing.AbstractProcessor;49import javax.annotation.processing.ProcessingEnvironment;50import javax.annotation.processing.RoundEnvironment;51import javax.annotation.processing.SupportedAnnotationTypes;52import javax.lang.model.SourceVersion;53import javax.lang.model.element.Element;54import javax.lang.model.element.ExecutableElement;55import javax.lang.model.element.QualifiedNameable;56import javax.lang.model.element.TypeElement;57import javax.lang.model.type.DeclaredType;58import javax.lang.model.type.TypeMirror;59import javax.tools.Diagnostic.Kind;60
61/**
62* {@link java.lang Package}
63* {@link java.lang.ERROR Bad}
64* {@link java.lang#ERROR Bad}
65*
66* {@link java.lang.String Class}
67* {@link String Class}
68* {@link java.lang.String#CASE_INSENSITIVE_ORDER Field}
69* {@link java.lang.String#String Constructor}
70* {@link java.lang.String#String(byte[]) Constructor}
71* {@link java.lang.String#String(byte[] bytes) Constructor}
72* {@link java.lang.String#String(byte[], String) Constructor}
73* {@link java.lang.String#String(byte[] bytes, String charSetName) Constructor}
74* {@link java.lang.String#isEmpty Method}
75* {@link java.lang.String#isEmpty() Method}
76* {@link java.lang.String#ERROR Bad}
77* {@link java.lang.String#equals(Object) Method}
78*
79* {@link AbstractProcessor Class}
80*
81* {@link List#add(Object) Method}
82*
83* {@link #trees Field}
84* {@link #getSupportedSourceVersion Method}
85* {@link #init(ProcessingEnvironment Method}
86*
87* @see java.lang Package
88* @see java.lang.ERROR Bad
89* @see java.lang#ERROR Bad
90*
91* @see java.lang.String Class
92* @see String Class
93* @see java.lang.String#CASE_INSENSITIVE_ORDER Field
94* @see java.lang.String#String Constructor
95* @see java.lang.String#String(byte[]) Constructor
96* @see java.lang.String#String(byte[] bytes) Constructor
97* @see java.lang.String#String(byte[],String) Constructor
98* @see java.lang.String#String(byte[] bytes, String charsetName) Constructor
99* @see java.lang.String#isEmpty Method
100* @see java.lang.String#isEmpty() Method
101* @see java.lang.String#ERROR Bad
102* @see java.lang.String#equals(Object) Method
103*
104* @see AbstractProcessor Class
105*
106* @see List#add(Object) Method
107*
108* @see #trees Field
109* @see #getSupportedSourceVersion Method
110* @see #init(ProcessingEnvironment) Method
111*
112* @see java.io.BufferedInputStream#BufferedInputStream(InputStream) Constructor
113*/
114@SupportedAnnotationTypes("*")115public class ReferenceTest extends AbstractProcessor {116DocTrees trees;117
118@Override119public SourceVersion getSupportedSourceVersion() {120return SourceVersion.latest();121}122
123@Override124public void init(ProcessingEnvironment pEnv) {125super.init(pEnv);126trees = DocTrees.instance(pEnv);127}128
129@Override130public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {131for (Element e: roundEnv.getRootElements()) {132new DocCommentScanner(trees.getPath(e)).scan();133for (Element enc: e.getEnclosedElements()) {134TreePath path = trees.getPath(enc);135if (trees.getDocCommentTree(path) != null) {136new DocCommentScanner(path).scan();137}138}139}140return true;141}142
143class DocCommentScanner extends DocTreePathScanner<Void, Void> {144TreePath path;145DocCommentTree dc;146
147DocCommentScanner(TreePath path) {148this.path = path;149}150
151void scan() {152dc = trees.getDocCommentTree(path);153scan(new DocTreePath(path, dc), null);154}155
156@Override157public Void visitLink(LinkTree tree, Void ignore) {158checkReference(tree.getReference(), tree.getLabel());159return null;160}161
162@Override163public Void visitSee(SeeTree tree, Void ignore) {164List<? extends DocTree> refLabel = tree.getReference();165if (refLabel.size() > 1 && (refLabel.get(0) instanceof ReferenceTree)) {166ReferenceTree ref = (ReferenceTree) refLabel.get(0);167List<? extends DocTree> label = refLabel.subList(1, refLabel.size());168checkReference(ref, label);169}170return null;171}172
173void checkReference(ReferenceTree tree, List<? extends DocTree> label) {174String sig = tree.getSignature();175
176Element found = trees.getElement(new DocTreePath(getCurrentPath(), tree));177if (found == null) {178System.err.println(sig + " NOT FOUND");179} else {180System.err.println(sig + " found " + found.getKind() + " " + found);181}182
183String expect = "UNKNOWN";184if (label.size() > 0 && label.get(0) instanceof TextTree)185expect = ((TextTree) label.get(0)).getBody();186
187if (expect.startsWith("signature:")) {188expect = expect.substring("signature:".length());189
190String signature = found.getKind().name() + ":" + elementSignature(found);191
192if (!expect.equalsIgnoreCase(signature)) {193error(tree, "Unexpected value found: " + signature +", expected: " + expect);194}195} else {196if (!expect.equalsIgnoreCase(found == null ? "bad" : found.getKind().name())) {197error(tree, "Unexpected value found: " + found +", expected: " + expect);198}199}200}201
202void error(DocTree tree, String msg) {203trees.printMessage(Kind.ERROR, msg, tree, dc, path.getCompilationUnit());204}205}206
207String elementSignature(Element el) {208return switch (el.getKind()) {209case METHOD -> elementSignature(el.getEnclosingElement()) + "." + el.getSimpleName() + "(" + executableParamNames((ExecutableElement) el) + ")";210case CLASS, INTERFACE -> ((QualifiedNameable) el).getQualifiedName().toString();211default -> throw new AssertionError("Unhandled Element kind: " + el.getKind());212};213}214
215String executableParamNames(ExecutableElement ee) {216return ee.getParameters()217.stream()218.map(p -> type2Name(p.asType()))219.collect(Collectors.joining(", "));220}221
222String type2Name(TypeMirror type) {223return switch (type.getKind()) {224case DECLARED -> elementSignature(((DeclaredType) type).asElement());225case INT, LONG -> type.toString();226default -> throw new AssertionError("Unhandled type kind: " + type.getKind());227};228}229}
230
231/**
232* @see ReferenceTestExtras Class
233* @see #ReferenceTestExtras Field
234* @see #ReferenceTestExtras() Constructor
235*
236* @see #X Field
237* @see #X() Method
238*
239* @see #m Method
240*
241* @see #varargs(int...) Method
242* @see #varargs(int... args) Method
243* @see #varargs(int[]) Method
244* @see #varargs(int[] args) Method
245*
246* @see #methodSearch(String) signature:METHOD:ReferenceTestExtras.methodSearch(java.lang.String)
247* @see #methodSearch(StringBuilder) signature:METHOD:ReferenceTestExtras.methodSearch(java.lang.CharSequence)
248* @see #methodSearchPrimitive1(int, int) signature:METHOD:ReferenceTestExtras.methodSearchPrimitive1(int, int)
249* @see #methodSearchPrimitive1(long, int) signature:METHOD:ReferenceTestExtras.methodSearchPrimitive1(long, int)
250* @see #methodSearchPrimitive1(int, long) signature:METHOD:ReferenceTestExtras.methodSearchPrimitive1(int, long)
251* @see #methodSearchPrimitive1(long, long) signature:METHOD:ReferenceTestExtras.methodSearchPrimitive1(long, long)
252* @see #methodSearchPrimitive2(int, int) signature:METHOD:ReferenceTestExtras.methodSearchPrimitive2(int, int)
253* @see #methodSearchPrimitive2(long, int) signature:METHOD:ReferenceTestExtras.methodSearchPrimitive2(long, int)
254* @see #methodSearchPrimitive2(int, long) signature:METHOD:ReferenceTestExtras.methodSearchPrimitive2(int, long)
255* @see #methodSearchPrimitive2(long, long) signature:METHOD:ReferenceTestExtras.methodSearchPrimitive2(long, long)
256*
257* @see Inner#X Bad
258* @see Inner#X() Bad
259* @see Inner#m Bad
260*/
261class ReferenceTestExtras {262int ReferenceTestExtras; // field263ReferenceTestExtras() { } // constructor264void ReferenceTestExtras() { } // method265
266int X;267void X() { }268static class X { }269
270void m() { }271void m(int i) { }272void m(int i, int j) { }273
274void varargs(int... args) { }275
276void methodSearch(Object o) {}277void methodSearch(String s) {}278void methodSearch(CharSequence cs) {}279
280void methodSearchPrimitive1(int i, int j) {}281void methodSearchPrimitive1(long i, int j) {}282void methodSearchPrimitive1(int i, long j) {}283void methodSearchPrimitive1(long i, long j) {}284
285void methodSearchPrimitive2(long i, long j) {}286void methodSearchPrimitive2(int i, long j) {}287void methodSearchPrimitive2(long i, int j) {}288void methodSearchPrimitive2(int i, int j) {}289
290/**291* @see #X Field
292* @see #X() Method
293* @see #m Method
294* @see Inner#X Bad
295* @see Inner#X() Bad
296* @see Inner#m Bad
297*/
298interface Inner {}299}
300
301
302