View Javadoc
1   ////////////////////////////////////////////////////////////////////////////////
2   // checkstyle: Checks Java source code for adherence to a set of rules.
3   // Copyright (C) 2001-2018 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.utils;
21  
22  import static com.puppycrawl.tools.checkstyle.internal.utils.TestUtil.isUtilsClassHasPrivateConstructor;
23  import static org.junit.Assert.assertEquals;
24  import static org.junit.Assert.assertFalse;
25  import static org.junit.Assert.assertTrue;
26  import static org.junit.Assert.fail;
27  
28  import java.util.List;
29  
30  import org.junit.Test;
31  
32  import com.puppycrawl.tools.checkstyle.api.Comment;
33  import com.puppycrawl.tools.checkstyle.api.DetailAST;
34  import com.puppycrawl.tools.checkstyle.api.DetailNode;
35  import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
36  import com.puppycrawl.tools.checkstyle.api.TokenTypes;
37  import com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocNodeImpl;
38  import com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTag;
39  import com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTagInfo;
40  import com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTags;
41  
42  public class JavadocUtilsTest {
43  
44      @Test
45      public void testTags() {
46          final String[] text = {
47              "/** @see elsewhere ",
48              " * {@link List }, {@link List link text }",
49              "   {@link List#add(Object) link text}",
50              " * {@link Class link text}",
51          };
52          final Comment comment = new Comment(text, 1, 4, text[3].length());
53          final JavadocTags allTags =
54              JavadocUtils.getJavadocTags(comment, JavadocUtils.JavadocTagType.ALL);
55          assertEquals("Invalid valid tags size", 5, allTags.getValidTags().size());
56      }
57  
58      @Test
59      public void testBlockTag() {
60          final String[] text = {
61              "/** @see elsewhere ",
62              " */",
63          };
64          final Comment comment = new Comment(text, 1, 4, text[1].length());
65          final JavadocTags allTags =
66              JavadocUtils.getJavadocTags(comment, JavadocUtils.JavadocTagType.ALL);
67          assertEquals("Invalid valid tags size", 1, allTags.getValidTags().size());
68      }
69  
70      @Test
71      public void testTagType() {
72          final String[] text = {
73              "/** @see block",
74              " * {@link List inline}, {@link List#add(Object)}",
75          };
76          final Comment comment = new Comment(text, 1, 2, text[1].length());
77          final JavadocTags blockTags =
78              JavadocUtils.getJavadocTags(comment, JavadocUtils.JavadocTagType.BLOCK);
79          final JavadocTags inlineTags =
80              JavadocUtils.getJavadocTags(comment, JavadocUtils.JavadocTagType.INLINE);
81          assertEquals("Invalid valid tags size", 1, blockTags.getValidTags().size());
82          assertEquals("Invalid valid tags size", 2, inlineTags.getValidTags().size());
83      }
84  
85      @Test
86      public void testInlineTagLinkText() {
87          final String[] text = {
88              "/** {@link List link text }",
89          };
90          final Comment comment = new Comment(text, 1, 1, text[0].length());
91          final List<JavadocTag> tags = JavadocUtils.getJavadocTags(
92              comment, JavadocUtils.JavadocTagType.ALL).getValidTags();
93          assertEquals("Invalid first arg", "List link text", tags.get(0).getFirstArg());
94      }
95  
96      @Test
97      public void testInlineTagMethodRef() {
98          final String[] text = {
99              "/** {@link List#add(Object)}",
100         };
101         final Comment comment = new Comment(text, 1, 1, text[0].length());
102         final List<JavadocTag> tags = JavadocUtils.getJavadocTags(
103             comment, JavadocUtils.JavadocTagType.ALL).getValidTags();
104         assertEquals("Invalid first arg", "List#add(Object)", tags.get(0).getFirstArg());
105     }
106 
107     @Test
108     public void testTagPositions() {
109         final String[] text = {
110             "/** @see elsewhere",
111             "    also {@link Name value} */",
112         };
113         final Comment comment = new Comment(text, 1, 2, text[1].length());
114 
115         final List<JavadocTag> tags = JavadocUtils.getJavadocTags(
116             comment, JavadocUtils.JavadocTagType.ALL).getValidTags();
117 
118         assertEquals("Invalid tags size", 2, tags.size());
119 
120         final JavadocTag seeTag = tags.get(0);
121         assertEquals("Invalid tag name", JavadocTagInfo.SEE.getName(), seeTag.getTagName());
122         assertEquals("Invalid line number", 1, seeTag.getLineNo());
123         assertEquals("Invalid column number", 4, seeTag.getColumnNo());
124 
125         final JavadocTag linkTag = tags.get(1);
126         assertEquals("Invalid tag name", JavadocTagInfo.LINK.getName(), linkTag.getTagName());
127         assertEquals("Invalid line number", 2, linkTag.getLineNo());
128         assertEquals("Invalid column number", 10, linkTag.getColumnNo());
129     }
130 
131     @Test
132     public void testInlineTagPositions() {
133         final String[] text = {"/** Also {@link Name value} */"};
134         final Comment comment = new Comment(text, 1, 0, text[0].length());
135 
136         final List<JavadocTag> tags = JavadocUtils.getJavadocTags(
137             comment, JavadocUtils.JavadocTagType.INLINE).getValidTags();
138 
139         assertEquals("Invalid tags size", 1, tags.size());
140 
141         assertEquals("Unexpected line number", 0, tags.get(0).getLineNo());
142         assertEquals("Unexpected column number", 10, tags.get(0).getColumnNo());
143     }
144 
145     @Test
146     public void testInvalidTags() {
147         final String[] text = {
148             "/** @fake block",
149             " * {@bogus inline}",
150             " * {@link List valid}",
151         };
152         final Comment comment = new Comment(text, 1, 3, text[2].length());
153         final JavadocTags allTags =
154             JavadocUtils.getJavadocTags(comment, JavadocUtils.JavadocTagType.ALL);
155         assertEquals("Unexpected invalid tags size", 2, allTags.getInvalidTags().size());
156         assertEquals("Unexpected valid tags size", 1, allTags.getValidTags().size());
157     }
158 
159     @Test
160     public void testEmptyBlockComment() {
161         final String emptyComment = "";
162         assertFalse("Should return false when empty string is passed",
163                 JavadocUtils.isJavadocComment(emptyComment));
164     }
165 
166     @Test
167     public void testEmptyBlockCommentAst() {
168         final DetailAST commentBegin = new DetailAST();
169         commentBegin.setType(TokenTypes.BLOCK_COMMENT_BEGIN);
170         commentBegin.setText("/*");
171 
172         final DetailAST commentContent = new DetailAST();
173         commentContent.setType(TokenTypes.COMMENT_CONTENT);
174         commentContent.setText("");
175 
176         final DetailAST commentEnd = new DetailAST();
177         commentEnd.setType(TokenTypes.BLOCK_COMMENT_END);
178         commentEnd.setText("*/");
179 
180         commentBegin.setFirstChild(commentContent);
181         commentContent.setNextSibling(commentEnd);
182 
183         assertFalse("Should return false when empty block comment is passed",
184                 JavadocUtils.isJavadocComment(commentBegin));
185     }
186 
187     @Test
188     public void testEmptyJavadocComment() {
189         final String emptyJavadocComment = "*";
190         assertTrue("Should return true when empty javadoc comment is passed",
191                 JavadocUtils.isJavadocComment(emptyJavadocComment));
192     }
193 
194     @Test
195     public void testEmptyJavadocCommentAst() {
196         final DetailAST commentBegin = new DetailAST();
197         commentBegin.setType(TokenTypes.BLOCK_COMMENT_BEGIN);
198         commentBegin.setText("/*");
199 
200         final DetailAST javadocCommentContent = new DetailAST();
201         javadocCommentContent.setType(TokenTypes.COMMENT_CONTENT);
202         javadocCommentContent.setText("*");
203 
204         final DetailAST commentEnd = new DetailAST();
205         commentEnd.setType(TokenTypes.BLOCK_COMMENT_END);
206         commentEnd.setText("*/");
207 
208         commentBegin.setFirstChild(javadocCommentContent);
209         javadocCommentContent.setNextSibling(commentEnd);
210 
211         final DetailAST commentBeginParent = new DetailAST();
212         commentBeginParent.setType(TokenTypes.MODIFIERS);
213         commentBeginParent.setFirstChild(commentBegin);
214 
215         final DetailAST aJavadocPosition = new DetailAST();
216         aJavadocPosition.setType(TokenTypes.METHOD_DEF);
217         aJavadocPosition.setFirstChild(commentBeginParent);
218         assertTrue("Should return true when empty javadoc comment ast is passed",
219                 JavadocUtils.isJavadocComment(commentBegin));
220     }
221 
222     @Test
223     public void testIsProperUtilsClass() throws ReflectiveOperationException {
224         assertTrue("Constructor is not private",
225                 isUtilsClassHasPrivateConstructor(JavadocUtils.class, true));
226     }
227 
228     @Test
229     public void testBranchContains() {
230         final JavadocNodeImpl node = new JavadocNodeImpl();
231         final JavadocNodeImpl firstChild = new JavadocNodeImpl();
232         final JavadocNodeImpl secondChild = new JavadocNodeImpl();
233 
234         node.setType(JavadocTokenTypes.JAVADOC);
235         firstChild.setType(JavadocTokenTypes.BODY_TAG_START);
236         secondChild.setType(JavadocTokenTypes.CODE_LITERAL);
237 
238         node.setChildren(firstChild, secondChild);
239         assertFalse("Should return true when branch contains node passed",
240                 JavadocUtils.containsInBranch(node, JavadocTokenTypes.AUTHOR_LITERAL));
241 
242         firstChild.setParent(node);
243         secondChild.setParent(node);
244         assertFalse("Should return false when branch does not contain node passed",
245                 JavadocUtils.containsInBranch(node, JavadocTokenTypes.AUTHOR_LITERAL));
246 
247         secondChild.setType(JavadocTokenTypes.AUTHOR_LITERAL);
248         assertTrue("Should return true when branch contains node passed",
249                 JavadocUtils.containsInBranch(node, JavadocTokenTypes.AUTHOR_LITERAL));
250     }
251 
252     @Test
253     public void testGetTokenNameForId() {
254         assertEquals("Invalid token name",
255                 "EOF", JavadocUtils.getTokenName(JavadocTokenTypes.EOF));
256     }
257 
258     @Test
259     public void testGetTokenNameForLargeId() {
260         try {
261             JavadocUtils.getTokenName(30073);
262             fail("exception expected");
263         }
264         catch (IllegalArgumentException ex) {
265             assertEquals("Invalid exception message",
266                     "Unknown javadoc token id. Given id: 30073", ex.getMessage());
267         }
268     }
269 
270     @Test
271     public void testGetTokenNameForInvalidId() {
272         try {
273             JavadocUtils.getTokenName(100);
274             fail("exception expected");
275         }
276         catch (IllegalArgumentException ex) {
277             assertEquals("Invalid exception message",
278                     "Unknown javadoc token id. Given id: 100", ex.getMessage());
279         }
280     }
281 
282     @Test
283     public void testGetTokenNameForLowerBoundInvalidId() {
284         try {
285             JavadocUtils.getTokenName(10080);
286             fail("exception expected");
287         }
288         catch (IllegalArgumentException ex) {
289             assertEquals("Invalid exception message",
290                     "Unknown javadoc token id. Given id: 10080", ex.getMessage());
291         }
292     }
293 
294     @Test
295     public void testGetTokenIdThatIsUnknown() {
296         try {
297             JavadocUtils.getTokenId("");
298             fail("exception expected");
299         }
300         catch (IllegalArgumentException ex) {
301             assertEquals("Invalid exception message",
302                     "Unknown javadoc token name. Given name ", ex.getMessage());
303         }
304     }
305 
306     @Test
307     public void testGetTokenId() {
308         final int tokenId = JavadocUtils.getTokenId("JAVADOC");
309 
310         assertEquals("Invalid token id", JavadocTokenTypes.JAVADOC, tokenId);
311     }
312 
313     @Test
314     public void testGetJavadocCommentContent() {
315         final DetailAST detailAST = new DetailAST();
316         final DetailAST javadoc = new DetailAST();
317 
318         javadoc.setText("1javadoc");
319         detailAST.setFirstChild(javadoc);
320         final String commentContent = JavadocUtils.getJavadocCommentContent(detailAST);
321 
322         assertEquals("Invalid comment content", "javadoc", commentContent);
323     }
324 
325     @Test
326     public void testGetFirstToken() {
327         final JavadocNodeImpl javadocNode = new JavadocNodeImpl();
328         final JavadocNodeImpl basetag = new JavadocNodeImpl();
329         basetag.setType(JavadocTokenTypes.BASE_TAG);
330         final JavadocNodeImpl body = new JavadocNodeImpl();
331         body.setType(JavadocTokenTypes.BODY);
332 
333         body.setParent(javadocNode);
334         basetag.setParent(javadocNode);
335         javadocNode.setChildren(basetag, body);
336 
337         final DetailNode result = JavadocUtils.findFirstToken(javadocNode, JavadocTokenTypes.BODY);
338 
339         assertEquals("Invalid first token", body, result);
340     }
341 
342     @Test
343     public void testGetPreviousSibling() {
344         final JavadocNodeImpl root = new JavadocNodeImpl();
345 
346         final JavadocNodeImpl node = new JavadocNodeImpl();
347         node.setIndex(1);
348         node.setParent(root);
349 
350         final JavadocNodeImpl previousNode = new JavadocNodeImpl();
351         previousNode.setIndex(0);
352         node.setParent(root);
353 
354         root.setChildren(previousNode, node);
355 
356         assertEquals("Unexpected node", previousNode, JavadocUtils.getPreviousSibling(node));
357     }
358 
359     @Test
360     public void testGetTokenNames() {
361         assertEquals("Unexpected token name",
362             "WBR_TAG", JavadocUtils.getTokenName(10079));
363     }
364 
365     @Test
366     public void testEscapeAllControlChars() {
367         assertEquals("invalid result", "abc", JavadocUtils.escapeAllControlChars("abc"));
368         assertEquals("invalid result", "1\\r2\\n3\\t",
369                 JavadocUtils.escapeAllControlChars("1\\r2\\n3\\t"));
370     }
371 
372 }