1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2025 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 java.util.Optional;
23
24 import com.puppycrawl.tools.checkstyle.StatelessCheck;
25 import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
26 import com.puppycrawl.tools.checkstyle.api.DetailAST;
27 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
28 import com.puppycrawl.tools.checkstyle.utils.CheckUtil;
29 import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
30
31 /**
32 * <div>
33 * Checks for missing package definition Javadoc comments in package-info.java files.
34 * </div>
35 *
36 * <p>
37 * Rationale: description and other related documentation for a package can be written up
38 * in the package-info.java file and it gets used in the production of the Javadocs.
39 * See <a
40 * href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#packagecomment"
41 * >link</a> for more info.
42 * </p>
43 *
44 * <p>
45 * This check specifically only validates package definitions. It will not validate any methods or
46 * interfaces declared in the package-info.java file.
47 * </p>
48 *
49 * @since 8.22
50 */
51 @StatelessCheck
52 public class MissingJavadocPackageCheck extends AbstractCheck {
53
54 /**
55 * A key is pointing to the warning message text in "messages.properties"
56 * file.
57 */
58 public static final String MSG_PKG_JAVADOC_MISSING = "package.javadoc.missing";
59
60 @Override
61 public int[] getDefaultTokens() {
62 return getRequiredTokens();
63 }
64
65 @Override
66 public int[] getAcceptableTokens() {
67 return getRequiredTokens();
68 }
69
70 @Override
71 public int[] getRequiredTokens() {
72 return new int[] {TokenTypes.PACKAGE_DEF};
73 }
74
75 @Override
76 public boolean isCommentNodesRequired() {
77 return true;
78 }
79
80 @Override
81 public void visitToken(DetailAST ast) {
82 if (CheckUtil.isPackageInfo(getFilePath()) && !hasJavadoc(ast)) {
83 log(ast, MSG_PKG_JAVADOC_MISSING);
84 }
85 }
86
87 /**
88 * Checks that there is javadoc before ast.
89 * Because of <a href="https://github.com/checkstyle/checkstyle/issues/4392">parser bug</a>
90 * parser can place javadoc comment either as previous sibling of package definition
91 * or (if there is annotation between package def and javadoc) inside package definition tree.
92 * So we should look for javadoc in both places.
93 *
94 * @param ast {@link TokenTypes#PACKAGE_DEF} token to check
95 * @return true if there is javadoc, false otherwise
96 */
97 private static boolean hasJavadoc(DetailAST ast) {
98 final boolean hasJavadocBefore = ast.getPreviousSibling() != null
99 && isJavadoc(ast.getPreviousSibling());
100 return hasJavadocBefore || hasJavadocAboveAnnotation(ast);
101 }
102
103 /**
104 * Checks javadoc existence in annotations list.
105 *
106 * @param ast package def
107 * @return true if there is a javadoc, false otherwise
108 */
109 private static boolean hasJavadocAboveAnnotation(DetailAST ast) {
110 final Optional<DetailAST> firstAnnotationChild = Optional.of(ast.getFirstChild())
111 .map(DetailAST::getFirstChild)
112 .map(DetailAST::getFirstChild);
113 boolean result = false;
114 if (firstAnnotationChild.isPresent()) {
115 for (DetailAST child = firstAnnotationChild.orElseThrow(); child != null;
116 child = child.getNextSibling()) {
117 if (isJavadoc(child)) {
118 result = true;
119 break;
120 }
121 }
122 }
123 return result;
124 }
125
126 /**
127 * Checks that ast is a javadoc comment.
128 *
129 * @param ast token to check
130 * @return true if ast is a javadoc comment, false otherwise
131 */
132 private static boolean isJavadoc(DetailAST ast) {
133 return ast.getType() == TokenTypes.BLOCK_COMMENT_BEGIN && JavadocUtil.isJavadocComment(ast);
134 }
135 }