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