001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2024 the original author or authors. 004// 005// This library is free software; you can redistribute it and/or 006// modify it under the terms of the GNU Lesser General Public 007// License as published by the Free Software Foundation; either 008// version 2.1 of the License, or (at your option) any later version. 009// 010// This library is distributed in the hope that it will be useful, 011// but WITHOUT ANY WARRANTY; without even the implied warranty of 012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013// Lesser General Public License for more details. 014// 015// You should have received a copy of the GNU Lesser General Public 016// License along with this library; if not, write to the Free Software 017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 018/////////////////////////////////////////////////////////////////////////////////////////////// 019 020package com.puppycrawl.tools.checkstyle.checks.javadoc; 021 022import java.util.Optional; 023 024import com.puppycrawl.tools.checkstyle.StatelessCheck; 025import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 026import com.puppycrawl.tools.checkstyle.api.DetailAST; 027import com.puppycrawl.tools.checkstyle.api.TokenTypes; 028import com.puppycrawl.tools.checkstyle.utils.CheckUtil; 029import com.puppycrawl.tools.checkstyle.utils.JavadocUtil; 030 031/** 032 * <div> 033 * Checks for missing package definition Javadoc comments in package-info.java files. 034 * </div> 035 * 036 * <p> 037 * Rationale: description and other related documentation for a package can be written up 038 * in the package-info.java file and it gets used in the production of the Javadocs. 039 * See <a 040 * href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#packagecomment" 041 * >link</a> for more info. 042 * </p> 043 * 044 * <p> 045 * This check specifically only validates package definitions. It will not validate any methods or 046 * interfaces declared in the package-info.java file. 047 * </p> 048 * 049 * <p> 050 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 051 * </p> 052 * 053 * <p> 054 * Violation Message Keys: 055 * </p> 056 * <ul> 057 * <li> 058 * {@code package.javadoc.missing} 059 * </li> 060 * </ul> 061 * 062 * @since 8.22 063 */ 064@StatelessCheck 065public class MissingJavadocPackageCheck extends AbstractCheck { 066 067 /** 068 * A key is pointing to the warning message text in "messages.properties" 069 * file. 070 */ 071 public static final String MSG_PKG_JAVADOC_MISSING = "package.javadoc.missing"; 072 073 @Override 074 public int[] getDefaultTokens() { 075 return getRequiredTokens(); 076 } 077 078 @Override 079 public int[] getAcceptableTokens() { 080 return getRequiredTokens(); 081 } 082 083 @Override 084 public int[] getRequiredTokens() { 085 return new int[] {TokenTypes.PACKAGE_DEF}; 086 } 087 088 @Override 089 public boolean isCommentNodesRequired() { 090 return true; 091 } 092 093 @Override 094 public void visitToken(DetailAST ast) { 095 if (CheckUtil.isPackageInfo(getFilePath()) && !hasJavadoc(ast)) { 096 log(ast, MSG_PKG_JAVADOC_MISSING); 097 } 098 } 099 100 /** 101 * Checks that there is javadoc before ast. 102 * Because of <a href="https://github.com/checkstyle/checkstyle/issues/4392">parser bug</a> 103 * parser can place javadoc comment either as previous sibling of package definition 104 * or (if there is annotation between package def and javadoc) inside package definition tree. 105 * So we should look for javadoc in both places. 106 * 107 * @param ast {@link TokenTypes#PACKAGE_DEF} token to check 108 * @return true if there is javadoc, false otherwise 109 */ 110 private static boolean hasJavadoc(DetailAST ast) { 111 final boolean hasJavadocBefore = ast.getPreviousSibling() != null 112 && isJavadoc(ast.getPreviousSibling()); 113 return hasJavadocBefore || hasJavadocAboveAnnotation(ast); 114 } 115 116 /** 117 * Checks javadoc existence in annotations list. 118 * 119 * @param ast package def 120 * @return true if there is a javadoc, false otherwise 121 */ 122 private static boolean hasJavadocAboveAnnotation(DetailAST ast) { 123 final Optional<DetailAST> firstAnnotationChild = Optional.of(ast.getFirstChild()) 124 .map(DetailAST::getFirstChild) 125 .map(DetailAST::getFirstChild); 126 boolean result = false; 127 if (firstAnnotationChild.isPresent()) { 128 for (DetailAST child = firstAnnotationChild.orElseThrow(); child != null; 129 child = child.getNextSibling()) { 130 if (isJavadoc(child)) { 131 result = true; 132 break; 133 } 134 } 135 } 136 return result; 137 } 138 139 /** 140 * Checks that ast is a javadoc comment. 141 * 142 * @param ast token to check 143 * @return true if ast is a javadoc comment, false otherwise 144 */ 145 private static boolean isJavadoc(DetailAST ast) { 146 return ast.getType() == TokenTypes.BLOCK_COMMENT_BEGIN && JavadocUtil.isJavadocComment(ast); 147 } 148}