1+ /*
2+ * Copyright (c) 2022, 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 8252717
27+ * @summary Integrate/merge legacy standard doclet diagnostics and doclint
28+ * @library ../../lib /tools/lib
29+ * @modules jdk.javadoc/jdk.javadoc.internal.tool
30+ * @build toolbox.ToolBox javadoc.tester.*
31+ * @run main TestDocLintDocletMessages
32+ */
33+
34+
35+ import javadoc .tester .JavadocTester ;
36+ import toolbox .ToolBox ;
37+
38+ import java .nio .file .Path ;
39+ import java .util .ArrayList ;
40+ import java .util .List ;
41+
42+ /**
43+ * Some conditions may be detected by both DocLint and the Standard Doclet.
44+ * This test is to verify that in such cases, only one of those generates
45+ * a message.
46+ */
47+ public class TestDocLintDocletMessages extends JavadocTester {
48+
49+ public static void main (String ... args ) throws Exception {
50+ TestDocLintDocletMessages tester = new TestDocLintDocletMessages ();
51+ tester .runTests ();
52+ }
53+
54+ final ToolBox tb = new ToolBox ();
55+
56+ @ Test
57+ public void testSyntaxError (Path base ) throws Exception {
58+ Path src = base .resolve ("src" );
59+ tb .writeJavaFiles (src , """
60+ /**
61+ * Comment.
62+ * Bad < HTML.
63+ * End of comment.
64+ */
65+ public class C {
66+ private C() { }
67+ }
68+ """ );
69+
70+ var doclintResult = new Result (Exit .ERROR ,"C.java:3: error: malformed HTML" );
71+ var docletResult = new Result (Exit .OK , "C.java:3: warning: invalid input: '<'" );
72+
73+ testSingle (base , "syntax" , doclintResult , docletResult );
74+ }
75+
76+ @ Test
77+ public void testReferenceNotFoundError (Path base ) throws Exception {
78+ Path src = base .resolve ("src" );
79+ tb .writeJavaFiles (src , """
80+ /**
81+ * Comment.
82+ * @see DoesNotExist
83+ */
84+ public class C {
85+ private C() { }
86+ }
87+ """ );
88+
89+ var doclintResult = new Result (Exit .ERROR , "C.java:3: error: reference not found" );
90+ var docletResult = new Result (Exit .OK , "C.java:3: warning: Tag @see: reference not found: DoesNotExist" );
91+
92+ testSingle (base , "reference" , doclintResult , docletResult );
93+ }
94+
95+ @ Test
96+ public void testParamNotFoundError (Path base ) throws Exception {
97+ Path src = base .resolve ("src" );
98+ tb .writeJavaFiles (src , """
99+ /**
100+ * Comment.
101+ */
102+ public class C {
103+ /**
104+ * Comment.
105+ * @param y wrong name
106+ */
107+ public C(int x) { }
108+ }
109+ """ );
110+
111+ var doclintResult = new Result (Exit .ERROR , "C.java:7: error: @param name not found" );
112+ var docletResult = new Result (Exit .OK , "C.java:7: warning: @param argument \" y\" is not a parameter name." );
113+
114+ testSingle (base , "reference" , doclintResult , docletResult );
115+ }
116+
117+ @ Test
118+ public void testParamDuplicateError (Path base ) throws Exception {
119+ Path src = base .resolve ("src" );
120+ tb .writeJavaFiles (src , """
121+ /**
122+ * Comment.
123+ */
124+ public class C {
125+ /**
126+ * Comment.
127+ * @param x first
128+ * @param x second
129+ */
130+ public C(int x) { }
131+ }
132+ """ );
133+
134+ var doclintResult = new Result (Exit .OK , "C.java:8: warning: @param \" x\" has already been specified" );
135+ var docletResult = new Result (Exit .OK , "C.java:8: warning: Parameter \" x\" is documented more than once." );
136+
137+ testSingle (base , "reference" , doclintResult , docletResult );
138+ }
139+
140+ @ Test
141+ public void testReturnOnVoid (Path base ) throws Exception {
142+ Path src = base .resolve ("src" );
143+ tb .writeJavaFiles (src , """
144+ /**
145+ * Comment.
146+ */
147+ public class C {
148+ private C() { }
149+ /**
150+ * Comment.
151+ * @return nothing
152+ */
153+ public void m() { }
154+ }
155+ """ );
156+
157+ var doclintResult = new Result (Exit .ERROR , "C.java:8: error: invalid use of @return" );
158+ var docletResult = new Result (Exit .OK , "C.java:10: warning: @return tag cannot be used in method with void return type." );
159+
160+ testSingle (base , "reference" , doclintResult , docletResult );
161+ }
162+
163+ /** Captures an expected exit code and diagnostic message. */
164+ record Result (Exit exit , String message ) { }
165+
166+ void testSingle (Path base , String group , Result doclintResult , Result docletResult ) {
167+ int index = 1 ;
168+
169+ // test options that should trigger the doclint message
170+ for (String o : List .of ("" , "-Xdoclint" , "-Xdoclint:" + group )) {
171+ testSingle (base , index ++, o .isEmpty () ? List .of () : List .of (o ), doclintResult , docletResult );
172+ }
173+
174+ // test options that should trigger the doclet message
175+ for (String o : List .of ("-Xdoclint:none" , "-Xdoclint:all,-" + group )) {
176+ testSingle (base , index ++, List .of (o ), docletResult , doclintResult );
177+ }
178+ }
179+
180+ void testSingle (Path base , int index , List <String > options , Result expect , Result doNotExpect ) {
181+ var allOptions = new ArrayList <String >();
182+ allOptions .addAll (List .of ("-d" , base .resolve ("out-" + index ).toString ()));
183+ allOptions .addAll (options );
184+ allOptions .addAll (List .of ("-noindex" , "-nohelp" )); // omit unnecessary files
185+ allOptions .add (base .resolve ("src" ).resolve ("C.java" ).toString ());
186+
187+ javadoc (allOptions .toArray (String []::new ));
188+ checkExit (expect .exit );
189+
190+ checkOutput (Output .OUT , true , expect .message );
191+
192+ // allow that the "other" result might be the same as the main result
193+ if (!doNotExpect .message .equals (expect .message )) {
194+ checkOutput (Output .OUT , false , doNotExpect .message );
195+ }
196+ }
197+ }
0 commit comments