001//////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code for adherence to a set of rules. 003// Copyright (C) 2001-2018 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.CommonUtils; 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 * @author Daniel Grenner 066 */ 067@StatelessCheck 068public class WriteTagCheck 069 extends AbstractCheck { 070 071 /** 072 * A key is pointing to the warning message text in "messages.properties" 073 * file. 074 */ 075 public static final String MSG_MISSING_TAG = "type.missingTag"; 076 077 /** 078 * A key is pointing to the warning message text in "messages.properties" 079 * file. 080 */ 081 public static final String MSG_WRITE_TAG = "javadoc.writeTag"; 082 083 /** 084 * A key is pointing to the warning message text in "messages.properties" 085 * file. 086 */ 087 public static final String MSG_TAG_FORMAT = "type.tagFormat"; 088 089 /** Compiled regexp to match tag. **/ 090 private Pattern tagRegExp; 091 /** Compiled regexp to match tag content. **/ 092 private Pattern tagFormat; 093 094 /** Regexp to match tag. */ 095 private String tag; 096 /** The severity level of found tag reports. */ 097 private SeverityLevel tagSeverity = SeverityLevel.INFO; 098 099 /** 100 * Sets the tag to check. 101 * @param tag tag to check 102 */ 103 public void setTag(String tag) { 104 this.tag = tag; 105 tagRegExp = CommonUtils.createPattern(tag + "\\s*(.*$)"); 106 } 107 108 /** 109 * Set the tag format. 110 * @param pattern a {@code String} value 111 */ 112 public void setTagFormat(Pattern pattern) { 113 tagFormat = pattern; 114 } 115 116 /** 117 * Sets the tag severity level. 118 * 119 * @param severity The new severity level 120 * @see SeverityLevel 121 */ 122 public final void setTagSeverity(SeverityLevel severity) { 123 tagSeverity = severity; 124 } 125 126 @Override 127 public int[] getDefaultTokens() { 128 return new int[] {TokenTypes.INTERFACE_DEF, 129 TokenTypes.CLASS_DEF, 130 TokenTypes.ENUM_DEF, 131 TokenTypes.ANNOTATION_DEF, 132 }; 133 } 134 135 @Override 136 public int[] getAcceptableTokens() { 137 return new int[] {TokenTypes.INTERFACE_DEF, 138 TokenTypes.CLASS_DEF, 139 TokenTypes.ENUM_DEF, 140 TokenTypes.ANNOTATION_DEF, 141 TokenTypes.METHOD_DEF, 142 TokenTypes.CTOR_DEF, 143 TokenTypes.ENUM_CONSTANT_DEF, 144 TokenTypes.ANNOTATION_FIELD_DEF, 145 }; 146 } 147 148 @Override 149 public int[] getRequiredTokens() { 150 return CommonUtils.EMPTY_INT_ARRAY; 151 } 152 153 @Override 154 public void visitToken(DetailAST ast) { 155 final FileContents contents = getFileContents(); 156 final int lineNo = ast.getLineNo(); 157 final TextBlock cmt = 158 contents.getJavadocBefore(lineNo); 159 if (cmt == null) { 160 log(lineNo, MSG_MISSING_TAG, tag); 161 } 162 else { 163 checkTag(lineNo, cmt.getText()); 164 } 165 } 166 167 /** 168 * Verifies that a type definition has a required tag. 169 * @param lineNo the line number for the type definition. 170 * @param comment the Javadoc comment for the type definition. 171 */ 172 private void checkTag(int lineNo, String... comment) { 173 if (tagRegExp != null) { 174 int tagCount = 0; 175 for (int i = 0; i < comment.length; i++) { 176 final String commentValue = comment[i]; 177 final Matcher matcher = tagRegExp.matcher(commentValue); 178 if (matcher.find()) { 179 tagCount += 1; 180 final int contentStart = matcher.start(1); 181 final String content = commentValue.substring(contentStart); 182 if (tagFormat == null || tagFormat.matcher(content).find()) { 183 logTag(lineNo + i - comment.length, tag, content); 184 } 185 else { 186 log(lineNo + i - comment.length, MSG_TAG_FORMAT, tag, tagFormat.pattern()); 187 } 188 } 189 } 190 if (tagCount == 0) { 191 log(lineNo, MSG_MISSING_TAG, tag); 192 } 193 } 194 } 195 196 /** 197 * Log a message. 198 * 199 * @param line the line number where the error was found 200 * @param tagName the javadoc tag to be logged 201 * @param tagValue the contents of the tag 202 * 203 * @see java.text.MessageFormat 204 */ 205 private void logTag(int line, String tagName, String tagValue) { 206 final String originalSeverity = getSeverity(); 207 setSeverity(tagSeverity.getName()); 208 209 log(line, MSG_WRITE_TAG, tagName, tagValue); 210 211 setSeverity(originalSeverity); 212 } 213 214}