View Javadoc
1   ////////////////////////////////////////////////////////////////////////////////
2   // checkstyle: Checks Java source code for adherence to a set of rules.
3   // Copyright (C) 2001-2017 the original author or authors.
4   //
5   // This library is free software; you can redistribute it and/or
6   // modify it under the terms of the GNU Lesser General Public
7   // License as published by the Free Software Foundation; either
8   // version 2.1 of the License, or (at your option) any later version.
9   //
10  // This library is distributed in the hope that it will be useful,
11  // but WITHOUT ANY WARRANTY; without even the implied warranty of
12  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  // Lesser General Public License for more details.
14  //
15  // You should have received a copy of the GNU Lesser General Public
16  // License along with this library; if not, write to the Free Software
17  // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18  ////////////////////////////////////////////////////////////////////////////////
19  
20  package com.puppycrawl.tools.checkstyle.checks.javadoc;
21  
22  import static com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTypeCheck.MSG_JAVADOC_MISSING;
23  import static com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTypeCheck.MSG_MISSING_TAG;
24  import static com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTypeCheck.MSG_TAG_FORMAT;
25  import static com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTypeCheck.MSG_UNKNOWN_TAG;
26  import static com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTypeCheck.MSG_UNUSED_TAG;
27  import static org.junit.Assert.assertArrayEquals;
28  
29  import org.junit.Test;
30  
31  import com.puppycrawl.tools.checkstyle.AbstractModuleTestSupport;
32  import com.puppycrawl.tools.checkstyle.DefaultConfiguration;
33  import com.puppycrawl.tools.checkstyle.api.Scope;
34  import com.puppycrawl.tools.checkstyle.api.TokenTypes;
35  import com.puppycrawl.tools.checkstyle.utils.CommonUtils;
36  
37  public class JavadocTypeCheckTest extends AbstractModuleTestSupport {
38      @Override
39      protected String getPackageLocation() {
40          return "com/puppycrawl/tools/checkstyle/checks/javadoc/javadoctype";
41      }
42  
43      @Test
44      public void testGetRequiredTokens() {
45          final JavadocTypeCheck javadocTypeCheck = new JavadocTypeCheck();
46          assertArrayEquals(
47              "JavadocTypeCheck#getRequiredTockens should return empty array by default",
48              CommonUtils.EMPTY_INT_ARRAY, javadocTypeCheck.getRequiredTokens());
49      }
50  
51      @Test
52      public void testGetAcceptableTokens() {
53          final JavadocTypeCheck javadocTypeCheck = new JavadocTypeCheck();
54  
55          final int[] actual = javadocTypeCheck.getAcceptableTokens();
56          final int[] expected = {
57              TokenTypes.INTERFACE_DEF,
58              TokenTypes.CLASS_DEF,
59              TokenTypes.ENUM_DEF,
60              TokenTypes.ANNOTATION_DEF,
61          };
62  
63          assertArrayEquals("Default acceptable tokens are invalid", expected, actual);
64      }
65  
66      @Test
67      public void testTags() throws Exception {
68          final DefaultConfiguration checkConfig =
69              createModuleConfig(JavadocTypeCheck.class);
70          final String[] expected = {
71              "8: " + getCheckMessage(MSG_JAVADOC_MISSING),
72              "302: " + getCheckMessage(MSG_JAVADOC_MISSING),
73              "327: " + getCheckMessage(MSG_JAVADOC_MISSING),
74          };
75          verify(checkConfig, getPath("InputJavadocTypeTags.java"), expected);
76      }
77  
78      @Test
79      public void testInner() throws Exception {
80          final DefaultConfiguration checkConfig =
81              createModuleConfig(JavadocTypeCheck.class);
82          final String[] expected = {
83              "14: " + getCheckMessage(MSG_JAVADOC_MISSING),
84              "21: " + getCheckMessage(MSG_JAVADOC_MISSING),
85              "27: " + getCheckMessage(MSG_JAVADOC_MISSING),
86          };
87          verify(checkConfig, getPath("InputJavadocTypeInner.java"), expected);
88      }
89  
90      @Test
91      public void testStrict() throws Exception {
92          final DefaultConfiguration checkConfig =
93              createModuleConfig(JavadocTypeCheck.class);
94          final String[] expected = {
95              "7: " + getCheckMessage(MSG_JAVADOC_MISSING),
96              "9: " + getCheckMessage(MSG_JAVADOC_MISSING),
97              "14: " + getCheckMessage(MSG_JAVADOC_MISSING),
98              "34: " + getCheckMessage(MSG_JAVADOC_MISSING),
99          };
100         verify(checkConfig, getPath("InputJavadocTypePublicOnly.java"), expected);
101     }
102 
103     @Test
104     public void testProtected() throws Exception {
105         final DefaultConfiguration checkConfig =
106             createModuleConfig(JavadocTypeCheck.class);
107         checkConfig.addAttribute("scope", Scope.PROTECTED.getName());
108         final String[] expected = {
109             "7: " + getCheckMessage(MSG_JAVADOC_MISSING),
110         };
111         verify(checkConfig, getPath("InputJavadocTypePublicOnly.java"), expected);
112     }
113 
114     @Test
115     public void testPublic() throws Exception {
116         final DefaultConfiguration checkConfig =
117             createModuleConfig(JavadocTypeCheck.class);
118         checkConfig.addAttribute("scope", Scope.PUBLIC.getName());
119         final String[] expected = {
120             "7: " + getCheckMessage(MSG_JAVADOC_MISSING),
121             "38: " + getCheckMessage(MSG_JAVADOC_MISSING),
122         };
123         verify(checkConfig,
124                getPath("InputJavadocTypeScopeInnerInterfaces.java"),
125                expected);
126     }
127 
128     @Test
129     public void testProtest() throws Exception {
130         final DefaultConfiguration checkConfig =
131             createModuleConfig(JavadocTypeCheck.class);
132         checkConfig.addAttribute("scope", Scope.PROTECTED.getName());
133         final String[] expected = {
134             "7: " + getCheckMessage(MSG_JAVADOC_MISSING),
135             "29: " + getCheckMessage(MSG_JAVADOC_MISSING),
136             "38: " + getCheckMessage(MSG_JAVADOC_MISSING),
137             "65: " + getCheckMessage(MSG_JAVADOC_MISSING),
138         };
139         verify(checkConfig,
140                getPath("InputJavadocTypeScopeInnerInterfaces.java"),
141                expected);
142     }
143 
144     @Test
145     public void testPkg() throws Exception {
146         final DefaultConfiguration checkConfig =
147             createModuleConfig(JavadocTypeCheck.class);
148         checkConfig.addAttribute(
149             "scope",
150             Scope.PACKAGE.getName());
151         final String[] expected = {
152             "18: " + getCheckMessage(MSG_JAVADOC_MISSING),
153             "20: " + getCheckMessage(MSG_JAVADOC_MISSING),
154             "22: " + getCheckMessage(MSG_JAVADOC_MISSING),
155         };
156         verify(checkConfig, getPath("InputJavadocTypeScopeInnerClasses.java"), expected);
157     }
158 
159     @Test
160     public void testEclipse() throws Exception {
161         final DefaultConfiguration checkConfig =
162             createModuleConfig(JavadocTypeCheck.class);
163         checkConfig.addAttribute(
164             "scope",
165             Scope.PUBLIC.getName());
166         final String[] expected = {
167             "18: " + getCheckMessage(MSG_JAVADOC_MISSING),
168         };
169         verify(checkConfig, getPath("InputJavadocTypeScopeInnerClasses.java"), expected);
170     }
171 
172     @Test
173     public void testAuthorRequired() throws Exception {
174         final DefaultConfiguration checkConfig =
175             createModuleConfig(JavadocTypeCheck.class);
176         checkConfig.addAttribute("authorFormat", "\\S");
177         final String[] expected = {
178             "13: " + getCheckMessage(MSG_MISSING_TAG, "@author"),
179         };
180         verify(checkConfig, getPath("InputJavadocTypeWhitespace.java"), expected);
181     }
182 
183     @Test
184     public void testAuthorRegularEx()
185             throws Exception {
186         final DefaultConfiguration checkConfig =
187             createModuleConfig(JavadocTypeCheck.class);
188         checkConfig.addAttribute("authorFormat", "0*");
189         final String[] expected = {
190             "22: " + getCheckMessage(MSG_MISSING_TAG, "@author"),
191             "58: " + getCheckMessage(MSG_MISSING_TAG, "@author"),
192             "94: " + getCheckMessage(MSG_MISSING_TAG, "@author"),
193         };
194         verify(checkConfig, getPath("InputJavadocTypeJavadoc.java"), expected);
195     }
196 
197     @Test
198     public void testAuthorRegularExError()
199             throws Exception {
200         final DefaultConfiguration checkConfig =
201             createModuleConfig(JavadocTypeCheck.class);
202         checkConfig.addAttribute("authorFormat", "ABC");
203         final String[] expected = {
204             "13: " + getCheckMessage(MSG_TAG_FORMAT, "@author", "ABC"),
205             "22: " + getCheckMessage(MSG_MISSING_TAG, "@author"),
206             "31: " + getCheckMessage(MSG_TAG_FORMAT, "@author", "ABC"),
207             "49: " + getCheckMessage(MSG_TAG_FORMAT, "@author", "ABC"),
208             "58: " + getCheckMessage(MSG_MISSING_TAG, "@author"),
209             "67: " + getCheckMessage(MSG_TAG_FORMAT, "@author", "ABC"),
210             "85: " + getCheckMessage(MSG_TAG_FORMAT, "@author", "ABC"),
211             "94: " + getCheckMessage(MSG_MISSING_TAG, "@author"),
212             "103: " + getCheckMessage(MSG_TAG_FORMAT, "@author", "ABC"),
213         };
214         verify(checkConfig, getPath("InputJavadocTypeJavadoc.java"), expected);
215     }
216 
217     @Test
218     public void testVersionRequired()
219             throws Exception {
220         final DefaultConfiguration checkConfig =
221             createModuleConfig(JavadocTypeCheck.class);
222         checkConfig.addAttribute("versionFormat", "\\S");
223         final String[] expected = {
224             "13: " + getCheckMessage(MSG_MISSING_TAG, "@version"),
225         };
226         verify(checkConfig, getPath("InputJavadocTypeWhitespace.java"), expected);
227     }
228 
229     @Test
230     public void testVersionRegularEx()
231             throws Exception {
232         final DefaultConfiguration checkConfig =
233             createModuleConfig(JavadocTypeCheck.class);
234         checkConfig.addAttribute("versionFormat", "^\\p{Digit}+\\.\\p{Digit}+$");
235         final String[] expected = {
236             "22: " + getCheckMessage(MSG_MISSING_TAG, "@version"),
237             "58: " + getCheckMessage(MSG_MISSING_TAG, "@version"),
238             "94: " + getCheckMessage(MSG_MISSING_TAG, "@version"),
239         };
240         verify(checkConfig, getPath("InputJavadocTypeJavadoc.java"), expected);
241     }
242 
243     @Test
244     public void testVersionRegularExError()
245             throws Exception {
246         final DefaultConfiguration checkConfig =
247             createModuleConfig(JavadocTypeCheck.class);
248         checkConfig.addAttribute("versionFormat", "\\$Revision.*\\$");
249         final String[] expected = {
250             "13: " + getCheckMessage(MSG_TAG_FORMAT, "@version", "\\$Revision.*\\$"),
251             "22: " + getCheckMessage(MSG_MISSING_TAG, "@version"),
252             "31: " + getCheckMessage(MSG_TAG_FORMAT, "@version", "\\$Revision.*\\$"),
253             "40: " + getCheckMessage(MSG_TAG_FORMAT, "@version", "\\$Revision.*\\$"),
254             "49: " + getCheckMessage(MSG_TAG_FORMAT, "@version", "\\$Revision.*\\$"),
255             "58: " + getCheckMessage(MSG_MISSING_TAG, "@version"),
256             "67: " + getCheckMessage(MSG_TAG_FORMAT, "@version", "\\$Revision.*\\$"),
257             "76: " + getCheckMessage(MSG_TAG_FORMAT, "@version", "\\$Revision.*\\$"),
258             "85: " + getCheckMessage(MSG_TAG_FORMAT, "@version", "\\$Revision.*\\$"),
259             "94: " + getCheckMessage(MSG_MISSING_TAG, "@version"),
260             "103: " + getCheckMessage(MSG_TAG_FORMAT, "@version", "\\$Revision.*\\$"),
261             "112: " + getCheckMessage(MSG_TAG_FORMAT, "@version", "\\$Revision.*\\$"),
262         };
263         verify(checkConfig, getPath("InputJavadocTypeJavadoc.java"), expected);
264     }
265 
266     @Test
267     public void testScopes() throws Exception {
268         final DefaultConfiguration checkConfig =
269             createModuleConfig(JavadocTypeCheck.class);
270         final String[] expected = {
271             "3: " + getCheckMessage(MSG_JAVADOC_MISSING),
272             "15: " + getCheckMessage(MSG_JAVADOC_MISSING),
273             "27: " + getCheckMessage(MSG_JAVADOC_MISSING),
274             "39: " + getCheckMessage(MSG_JAVADOC_MISSING),
275             "52: " + getCheckMessage(MSG_JAVADOC_MISSING),
276             "63: " + getCheckMessage(MSG_JAVADOC_MISSING),
277             "75: " + getCheckMessage(MSG_JAVADOC_MISSING),
278             "87: " + getCheckMessage(MSG_JAVADOC_MISSING),
279             "99: " + getCheckMessage(MSG_JAVADOC_MISSING),
280             "111: " + getCheckMessage(MSG_JAVADOC_MISSING),
281         };
282         verify(checkConfig,
283                getPath("InputJavadocTypeNoJavadoc.java"),
284                expected);
285     }
286 
287     @Test
288     public void testLimitViolationsBySpecifyingTokens() throws Exception {
289         final DefaultConfiguration checkConfig =
290             createModuleConfig(JavadocTypeCheck.class);
291         checkConfig.addAttribute("tokens", "INTERFACE_DEF");
292         final String[] expected = {
293             "4: " + getCheckMessage(MSG_JAVADOC_MISSING),
294         };
295         verify(checkConfig,
296                getPath("InputJavadocTypeNoJavadocOnInterface.java"),
297                expected);
298     }
299 
300     @Test
301     public void testScopes2() throws Exception {
302         final DefaultConfiguration checkConfig =
303             createModuleConfig(JavadocTypeCheck.class);
304         checkConfig.addAttribute("scope", Scope.PROTECTED.getName());
305         final String[] expected = {
306             "3: " + getCheckMessage(MSG_JAVADOC_MISSING),
307             "15: " + getCheckMessage(MSG_JAVADOC_MISSING),
308         };
309         verify(checkConfig,
310                getPath("InputJavadocTypeNoJavadoc.java"),
311                expected);
312     }
313 
314     @Test
315     public void testExcludeScope() throws Exception {
316         final DefaultConfiguration checkConfig =
317             createModuleConfig(JavadocTypeCheck.class);
318         checkConfig.addAttribute("scope", Scope.PRIVATE.getName());
319         checkConfig.addAttribute("excludeScope", Scope.PROTECTED.getName());
320         final String[] expected = {
321             "27: " + getCheckMessage(MSG_JAVADOC_MISSING),
322             "39: " + getCheckMessage(MSG_JAVADOC_MISSING),
323             "52: " + getCheckMessage(MSG_JAVADOC_MISSING),
324             "63: " + getCheckMessage(MSG_JAVADOC_MISSING),
325             "75: " + getCheckMessage(MSG_JAVADOC_MISSING),
326             "87: " + getCheckMessage(MSG_JAVADOC_MISSING),
327             "99: " + getCheckMessage(MSG_JAVADOC_MISSING),
328             "111: " + getCheckMessage(MSG_JAVADOC_MISSING),
329         };
330         verify(checkConfig,
331                getPath("InputJavadocTypeNoJavadoc.java"),
332                expected);
333     }
334 
335     @Test
336     public void testTypeParameters() throws Exception {
337         final DefaultConfiguration checkConfig =
338             createModuleConfig(JavadocTypeCheck.class);
339         final String[] expected = {
340             "7:4: " + getCheckMessage(MSG_UNUSED_TAG, "@param", "<D123>"),
341             "11: " + getCheckMessage(MSG_MISSING_TAG, "@param <C456>"),
342             "44:8: " + getCheckMessage(MSG_UNUSED_TAG, "@param", "<C>"),
343             "47: " + getCheckMessage(MSG_MISSING_TAG, "@param <B>"),
344             "60:5: " + getCheckMessage(MSG_UNUSED_TAG, "@param", "<x>"),
345         };
346         verify(checkConfig, getPath("InputJavadocTypeTypeParamsTags.java"), expected);
347     }
348 
349     @Test
350     public void testAllowMissingTypeParameters() throws Exception {
351         final DefaultConfiguration checkConfig =
352             createModuleConfig(JavadocTypeCheck.class);
353         checkConfig.addAttribute("allowMissingParamTags", "true");
354         final String[] expected = {
355             "7:4: " + getCheckMessage(MSG_UNUSED_TAG, "@param", "<D123>"),
356             "44:8: " + getCheckMessage(MSG_UNUSED_TAG, "@param", "<C>"),
357             "60:5: " + getCheckMessage(MSG_UNUSED_TAG, "@param", "<x>"),
358         };
359         verify(checkConfig, getPath("InputJavadocTypeTypeParamsTags.java"), expected);
360     }
361 
362     @Test
363     public void testDontAllowUnusedParameterTag() throws Exception {
364         final DefaultConfiguration checkConfig =
365                 createModuleConfig(JavadocTypeCheck.class);
366         final String[] expected = {
367             "6:4: " + getCheckMessage(MSG_UNUSED_TAG, "@param", "<BAD>"),
368             "7:4: " + getCheckMessage(MSG_UNUSED_TAG, "@param", "<BAD>"),
369         };
370         verify(checkConfig,
371                 getPath("InputJavadocTypeUnusedParamInJavadocForClass.java"),
372                 expected);
373     }
374 
375     @Test
376     public void testBadTag() throws Exception {
377         final DefaultConfiguration checkConfig =
378             createModuleConfig(JavadocTypeCheck.class);
379         final String[] expected = {
380             "5:4: " + getCheckMessage(MSG_UNKNOWN_TAG, "mytag"),
381         };
382         verify(checkConfig,
383                getPath("InputJavadocTypeBadTag.java"),
384                expected);
385     }
386 
387     @Test
388     public void testBadTagSuppress() throws Exception {
389         final DefaultConfiguration checkConfig =
390             createModuleConfig(JavadocTypeCheck.class);
391         checkConfig.addAttribute("allowUnknownTags", "true");
392         final String[] expected = CommonUtils.EMPTY_STRING_ARRAY;
393         verify(checkConfig,
394                 getPath("InputJavadocTypeBadTag.java"),
395                 expected);
396     }
397 }