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