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 * <p> 033 * Checks for missing package definition Javadoc comments in package-info.java files. 034 * </p> 035 * <p> 036 * Rationale: description and other related documentation for a package can be written up 037 * in the package-info.java file and it gets used in the production of the Javadocs. 038 * See <a 039 * href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#packagecomment" 040 * >link</a> for more info. 041 * </p> 042 * <p> 043 * This check specifically only validates package definitions. It will not validate any methods or 044 * interfaces declared in the package-info.java file. 045 * </p> 046 * <p> 047 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 048 * </p> 049 * <p> 050 * Violation Message Keys: 051 * </p> 052 * <ul> 053 * <li> 054 * {@code package.javadoc.missing} 055 * </li> 056 * </ul> 057 * 058 * @since 8.22 059 */ 060@StatelessCheck 061public class MissingJavadocPackageCheck extends AbstractCheck { 062 063 /** 064 * A key is pointing to the warning message text in "messages.properties" 065 * file. 066 */ 067 public static final String MSG_PKG_JAVADOC_MISSING = "package.javadoc.missing"; 068 069 @Override 070 public int[] getDefaultTokens() { 071 return getRequiredTokens(); 072 } 073 074 @Override 075 public int[] getAcceptableTokens() { 076 return getRequiredTokens(); 077 } 078 079 @Override 080 public int[] getRequiredTokens() { 081 return new int[] {TokenTypes.PACKAGE_DEF}; 082 } 083 084 @Override 085 public boolean isCommentNodesRequired() { 086 return true; 087 } 088 089 @Override 090 public void visitToken(DetailAST ast) { 091 if (CheckUtil.isPackageInfo(getFilePath()) && !hasJavadoc(ast)) { 092 log(ast, MSG_PKG_JAVADOC_MISSING); 093 } 094 } 095 096 /** 097 * Checks that there is javadoc before ast. 098 * Because of <a href="https://github.com/checkstyle/checkstyle/issues/4392">parser bug</a> 099 * parser can place javadoc comment either as previous sibling of package definition 100 * or (if there is annotation between package def and javadoc) inside package definition tree. 101 * So we should look for javadoc in both places. 102 * 103 * @param ast {@link TokenTypes#PACKAGE_DEF} token to check 104 * @return true if there is javadoc, false otherwise 105 */ 106 private static boolean hasJavadoc(DetailAST ast) { 107 final boolean hasJavadocBefore = ast.getPreviousSibling() != null 108 && isJavadoc(ast.getPreviousSibling()); 109 return hasJavadocBefore || hasJavadocAboveAnnotation(ast); 110 } 111 112 /** 113 * Checks javadoc existence in annotations list. 114 * 115 * @param ast package def 116 * @return true if there is a javadoc, false otherwise 117 */ 118 private static boolean hasJavadocAboveAnnotation(DetailAST ast) { 119 final Optional<DetailAST> firstAnnotationChild = Optional.of(ast.getFirstChild()) 120 .map(DetailAST::getFirstChild) 121 .map(DetailAST::getFirstChild); 122 boolean result = false; 123 if (firstAnnotationChild.isPresent()) { 124 for (DetailAST child = firstAnnotationChild.orElseThrow(); child != null; 125 child = child.getNextSibling()) { 126 if (isJavadoc(child)) { 127 result = true; 128 break; 129 } 130 } 131 } 132 return result; 133 } 134 135 /** 136 * Checks that ast is a javadoc comment. 137 * 138 * @param ast token to check 139 * @return true if ast is a javadoc comment, false otherwise 140 */ 141 private static boolean isJavadoc(DetailAST ast) { 142 return ast.getType() == TokenTypes.BLOCK_COMMENT_BEGIN && JavadocUtil.isJavadocComment(ast); 143 } 144}