001//////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code for adherence to a set of rules. 003// Copyright (C) 2001-2019 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.regex.Matcher; 023import java.util.regex.Pattern; 024 025import com.puppycrawl.tools.checkstyle.StatelessCheck; 026import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 027import com.puppycrawl.tools.checkstyle.api.DetailAST; 028import com.puppycrawl.tools.checkstyle.api.FileContents; 029import com.puppycrawl.tools.checkstyle.api.SeverityLevel; 030import com.puppycrawl.tools.checkstyle.api.TextBlock; 031import com.puppycrawl.tools.checkstyle.api.TokenTypes; 032import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 033 034/** 035 * <p> 036 * Outputs a JavaDoc tag as information. Can be used e.g. with the stylesheets 037 * that sort the report by author name. 038 * To define the format for a tag, set property tagFormat to a 039 * regular expression. 040 * This check uses two different severity levels. The normal one is used for 041 * reporting when the tag is missing. The additional one (tagSeverity) is used 042 * for the level of reporting when the tag exists. The default value for 043 * tagSeverity is info. 044 * </p> 045 * <p> An example of how to configure the check for printing author name is: 046 *</p> 047 * <pre> 048 * <module name="WriteTag"> 049 * <property name="tag" value="@author"/> 050 * <property name="tagFormat" value="\S"/> 051 * </module> 052 * </pre> 053 * <p> An example of how to configure the check to print warnings if an 054 * "@incomplete" tag is found, and not print anything if it is not found: 055 *</p> 056 * <pre> 057 * <module name="WriteTag"> 058 * <property name="tag" value="@incomplete"/> 059 * <property name="tagFormat" value="\S"/> 060 * <property name="severity" value="ignore"/> 061 * <property name="tagSeverity" value="warning"/> 062 * </module> 063 * </pre> 064 * 065 */ 066@StatelessCheck 067public class WriteTagCheck 068 extends AbstractCheck { 069 070 /** 071 * A key is pointing to the warning message text in "messages.properties" 072 * file. 073 */ 074 public static final String MSG_MISSING_TAG = "type.missingTag"; 075 076 /** 077 * A key is pointing to the warning message text in "messages.properties" 078 * file. 079 */ 080 public static final String MSG_WRITE_TAG = "javadoc.writeTag"; 081 082 /** 083 * A key is pointing to the warning message text in "messages.properties" 084 * file. 085 */ 086 public static final String MSG_TAG_FORMAT = "type.tagFormat"; 087 088 /** Compiled regexp to match tag. **/ 089 private Pattern tagRegExp; 090 /** Compiled regexp to match tag content. **/ 091 private Pattern tagFormat; 092 093 /** Regexp to match tag. */ 094 private String tag; 095 /** The severity level of found tag reports. */ 096 private SeverityLevel tagSeverity = SeverityLevel.INFO; 097 098 /** 099 * Sets the tag to check. 100 * @param tag tag to check 101 */ 102 public void setTag(String tag) { 103 this.tag = tag; 104 tagRegExp = CommonUtil.createPattern(tag + "\\s*(.*$)"); 105 } 106 107 /** 108 * Set the tag format. 109 * @param pattern a {@code String} value 110 */ 111 public void setTagFormat(Pattern pattern) { 112 tagFormat = pattern; 113 } 114 115 /** 116 * Sets the tag severity level. 117 * 118 * @param severity The new severity level 119 * @see SeverityLevel 120 */ 121 public final void setTagSeverity(SeverityLevel severity) { 122 tagSeverity = severity; 123 } 124 125 @Override 126 public int[] getDefaultTokens() { 127 return new int[] {TokenTypes.INTERFACE_DEF, 128 TokenTypes.CLASS_DEF, 129 TokenTypes.ENUM_DEF, 130 TokenTypes.ANNOTATION_DEF, 131 }; 132 } 133 134 @Override 135 public int[] getAcceptableTokens() { 136 return new int[] {TokenTypes.INTERFACE_DEF, 137 TokenTypes.CLASS_DEF, 138 TokenTypes.ENUM_DEF, 139 TokenTypes.ANNOTATION_DEF, 140 TokenTypes.METHOD_DEF, 141 TokenTypes.CTOR_DEF, 142 TokenTypes.ENUM_CONSTANT_DEF, 143 TokenTypes.ANNOTATION_FIELD_DEF, 144 }; 145 } 146 147 @Override 148 public int[] getRequiredTokens() { 149 return CommonUtil.EMPTY_INT_ARRAY; 150 } 151 152 @Override 153 public void visitToken(DetailAST ast) { 154 final FileContents contents = getFileContents(); 155 final int lineNo = ast.getLineNo(); 156 final TextBlock cmt = 157 contents.getJavadocBefore(lineNo); 158 if (cmt == null) { 159 log(lineNo, MSG_MISSING_TAG, tag); 160 } 161 else { 162 checkTag(lineNo, cmt.getText()); 163 } 164 } 165 166 /** 167 * Verifies that a type definition has a required tag. 168 * @param lineNo the line number for the type definition. 169 * @param comment the Javadoc comment for the type definition. 170 */ 171 private void checkTag(int lineNo, String... comment) { 172 if (tagRegExp != null) { 173 boolean hasTag = false; 174 for (int i = 0; i < comment.length; i++) { 175 final String commentValue = comment[i]; 176 final Matcher matcher = tagRegExp.matcher(commentValue); 177 if (matcher.find()) { 178 hasTag = true; 179 final int contentStart = matcher.start(1); 180 final String content = commentValue.substring(contentStart); 181 if (tagFormat == null || tagFormat.matcher(content).find()) { 182 logTag(lineNo + i - comment.length, tag, content); 183 } 184 else { 185 log(lineNo + i - comment.length, MSG_TAG_FORMAT, tag, tagFormat.pattern()); 186 } 187 } 188 } 189 if (!hasTag) { 190 log(lineNo, MSG_MISSING_TAG, tag); 191 } 192 } 193 } 194 195 /** 196 * Log a message. 197 * 198 * @param line the line number where the error was found 199 * @param tagName the javadoc tag to be logged 200 * @param tagValue the contents of the tag 201 * 202 * @see java.text.MessageFormat 203 */ 204 private void logTag(int line, String tagName, String tagValue) { 205 final String originalSeverity = getSeverity(); 206 setSeverity(tagSeverity.getName()); 207 208 log(line, MSG_WRITE_TAG, tagName, tagValue); 209 210 setSeverity(originalSeverity); 211 } 212 213}