1 /////////////////////////////////////////////////////////////////////////////////////////////// 2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules. 3 // Copyright (C) 2001-2024 the original author or authors. 4 // 5 // This library is free software; you can redistribute it and/or 6 // modify it under the terms of the GNU Lesser General Public 7 // License as published by the Free Software Foundation; either 8 // version 2.1 of the License, or (at your option) any later version. 9 // 10 // This library is distributed in the hope that it will be useful, 11 // but WITHOUT ANY WARRANTY; without even the implied warranty of 12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 // Lesser General Public License for more details. 14 // 15 // You should have received a copy of the GNU Lesser General Public 16 // License along with this library; if not, write to the Free Software 17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 18 /////////////////////////////////////////////////////////////////////////////////////////////// 19 20 package com.puppycrawl.tools.checkstyle.checks.javadoc; 21 22 import java.util.Arrays; 23 import java.util.Set; 24 import java.util.regex.Matcher; 25 import java.util.regex.Pattern; 26 import java.util.stream.Collectors; 27 28 import com.puppycrawl.tools.checkstyle.StatelessCheck; 29 import com.puppycrawl.tools.checkstyle.api.DetailNode; 30 import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes; 31 32 /** 33 * <p> 34 * Checks that a 35 * <a href="https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html#block-tags"> 36 * javadoc block tag</a> appears only at the beginning of a line, ignoring 37 * leading asterisks and white space. A block tag is a token that starts with 38 * {@code @} symbol and is preceded by a whitespace. This check ignores block 39 * tags in comments and inside inline tags {@code } and {@literal }. 40 * </p> 41 * <p> 42 * Rationale: according to 43 * <a href="https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html#block-tags"> 44 * the specification</a> all javadoc block tags should be placed at the beginning 45 * of a line. Tags that are not placed at the beginning are treated as plain text. 46 * To recognize intentional tag placement to text area it is better to escape the 47 * {@code @} symbol, and all non-escaped tags should be located at the beginning 48 * of the line. See NOTE section for details on how to escape. 49 * </p> 50 * <p> 51 * To place a tag explicitly as text, escape the {@code @} symbol with HTML entity 52 * &#64; or place it inside {@code {@code }}, for example: 53 * </p> 54 * <pre> 55 * /** 56 * * &#64;serial literal in {@code @serial} Javadoc tag. 57 * */ 58 * </pre> 59 * <ul> 60 * <li> 61 * Property {@code tags} - Specify the javadoc tags to process. 62 * Type is {@code java.lang.String[]}. 63 * Default value is {@code author, deprecated, exception, hidden, param, provides, 64 * return, see, serial, serialData, serialField, since, throws, uses, version}. 65 * </li> 66 * <li> 67 * Property {@code violateExecutionOnNonTightHtml} - Control when to print violations 68 * if the Javadoc being examined by this check violates the tight html rules defined at 69 * <a href="https://checkstyle.org/writingjavadocchecks.html#Tight-HTML_rules">Tight-HTML Rules</a>. 70 * Type is {@code boolean}. 71 * Default value is {@code false}. 72 * </li> 73 * </ul> 74 * <p> 75 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 76 * </p> 77 * <p> 78 * Violation Message Keys: 79 * </p> 80 * <ul> 81 * <li> 82 * {@code javadoc.blockTagLocation} 83 * </li> 84 * <li> 85 * {@code javadoc.missed.html.close} 86 * </li> 87 * <li> 88 * {@code javadoc.parse.rule.error} 89 * </li> 90 * <li> 91 * {@code javadoc.unclosedHtml} 92 * </li> 93 * <li> 94 * {@code javadoc.wrong.singleton.html.tag} 95 * </li> 96 * </ul> 97 * 98 * @since 8.24 99 */ 100 @StatelessCheck 101 public class JavadocBlockTagLocationCheck extends AbstractJavadocCheck { 102 103 /** 104 * A key is pointing to the warning message text in "messages.properties" file. 105 */ 106 public static final String MSG_BLOCK_TAG_LOCATION = "javadoc.blockTagLocation"; 107 108 /** 109 * This regexp is used to extract the javadoc tags. 110 */ 111 private static final Pattern JAVADOC_BLOCK_TAG_PATTERN = Pattern.compile("\\s@(\\w+)"); 112 113 /** 114 * Block tags from Java 11 115 * <a href="https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html"> 116 * Documentation Comment Specification</a>. 117 */ 118 private static final String[] DEFAULT_TAGS = { 119 "author", 120 "deprecated", 121 "exception", 122 "hidden", 123 "param", 124 "provides", 125 "return", 126 "see", 127 "serial", 128 "serialData", 129 "serialField", 130 "since", 131 "throws", 132 "uses", 133 "version", 134 }; 135 136 /** 137 * Specify the javadoc tags to process. 138 */ 139 private Set<String> tags; 140 141 /** 142 * Creates a new {@code JavadocBlockTagLocationCheck} instance with default settings. 143 */ 144 public JavadocBlockTagLocationCheck() { 145 setTags(DEFAULT_TAGS); 146 } 147 148 /** 149 * Setter to specify the javadoc tags to process. 150 * 151 * @param values user's values. 152 * @since 8.24 153 */ 154 public final void setTags(String... values) { 155 tags = Arrays.stream(values).collect(Collectors.toUnmodifiableSet()); 156 } 157 158 /** 159 * The javadoc tokens that this check must be registered for. According to 160 * <a href="https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html#block-tags"> 161 * the specs</a> each block tag must appear at the beginning of a line, otherwise 162 * it will be interpreted as a plain text. This check looks for a block tag 163 * in the javadoc text, thus it needs the {@code TEXT} tokens. 164 * 165 * @return the javadoc token set this must be registered for. 166 * @see JavadocTokenTypes 167 */ 168 @Override 169 public int[] getRequiredJavadocTokens() { 170 return new int[] { 171 JavadocTokenTypes.TEXT, 172 }; 173 } 174 175 @Override 176 public int[] getAcceptableJavadocTokens() { 177 return getRequiredJavadocTokens(); 178 } 179 180 @Override 181 public int[] getDefaultJavadocTokens() { 182 return getRequiredJavadocTokens(); 183 } 184 185 @Override 186 public void visitJavadocToken(DetailNode ast) { 187 if (!isCommentOrInlineTag(ast.getParent())) { 188 final Matcher tagMatcher = JAVADOC_BLOCK_TAG_PATTERN.matcher(ast.getText()); 189 while (tagMatcher.find()) { 190 final String tagName = tagMatcher.group(1); 191 if (tags.contains(tagName)) { 192 log(ast.getLineNumber(), MSG_BLOCK_TAG_LOCATION, tagName); 193 } 194 } 195 } 196 } 197 198 /** 199 * Checks if the node can contain an unescaped block tag without violation. 200 * 201 * @param node to check 202 * @return {@code true} if node is {@code @code}, {@code @literal} or HTML comment. 203 */ 204 private static boolean isCommentOrInlineTag(DetailNode node) { 205 return node.getType() == JavadocTokenTypes.JAVADOC_INLINE_TAG 206 || node.getType() == JavadocTokenTypes.HTML_COMMENT; 207 } 208 209 }