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.BitSet; 24 import java.util.List; 25 26 import com.puppycrawl.tools.checkstyle.PropertyType; 27 import com.puppycrawl.tools.checkstyle.StatelessCheck; 28 import com.puppycrawl.tools.checkstyle.XdocsPropertyType; 29 import com.puppycrawl.tools.checkstyle.api.DetailAST; 30 import com.puppycrawl.tools.checkstyle.api.DetailNode; 31 import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes; 32 import com.puppycrawl.tools.checkstyle.api.TokenTypes; 33 import com.puppycrawl.tools.checkstyle.utils.JavadocUtil; 34 import com.puppycrawl.tools.checkstyle.utils.TokenUtil; 35 36 /** 37 * <p> 38 * Checks the order of 39 * <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDBEFIF"> 40 * javadoc block-tags or javadoc tags</a>. 41 * </p> 42 * <p> 43 * Note: Google used the term "at-clauses" for block tags in their guide till 2017-02-28. 44 * </p> 45 * 46 * <ul> 47 * <li> 48 * Property {@code tagOrder} - Specify the order by tags. 49 * Type is {@code java.lang.String[]}. 50 * Default value is 51 * {@code @author, @deprecated, @exception, @param, @return, @see, @serial, @serialData, @serialField, @since, @throws, @version}. 52 * </li> 53 * <li> 54 * Property {@code target} - Specify block tags targeted. 55 * Type is {@code java.lang.String[]}. 56 * Validation type is {@code tokenTypesSet}. 57 * Default value is 58 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF"> 59 * CLASS_DEF</a>, 60 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#COMPACT_CTOR_DEF"> 61 * COMPACT_CTOR_DEF</a>, 62 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF"> 63 * CTOR_DEF</a>, 64 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF"> 65 * ENUM_DEF</a>, 66 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF"> 67 * INTERFACE_DEF</a>, 68 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF"> 69 * METHOD_DEF</a>, 70 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF"> 71 * RECORD_DEF</a>, 72 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#VARIABLE_DEF"> 73 * VARIABLE_DEF</a>. 74 * </li> 75 * <li> 76 * Property {@code violateExecutionOnNonTightHtml} - Control when to print violations if the 77 * Javadoc being examined by this check violates the tight html rules defined at 78 * <a href="https://checkstyle.org/writingjavadocchecks.html#Tight-HTML_rules">Tight-HTML Rules</a>. 79 * Type is {@code boolean}. 80 * Default value is {@code false}. 81 * </li> 82 * </ul> 83 * <p> 84 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 85 * </p> 86 * <p> 87 * Violation Message Keys: 88 * </p> 89 * <ul> 90 * <li> 91 * {@code at.clause.order} 92 * </li> 93 * <li> 94 * {@code javadoc.missed.html.close} 95 * </li> 96 * <li> 97 * {@code javadoc.parse.rule.error} 98 * </li> 99 * <li> 100 * {@code javadoc.unclosedHtml} 101 * </li> 102 * <li> 103 * {@code javadoc.wrong.singleton.html.tag} 104 * </li> 105 * </ul> 106 * 107 * @since 6.0 108 */ 109 @StatelessCheck 110 public class AtclauseOrderCheck extends AbstractJavadocCheck { 111 112 /** 113 * A key is pointing to the warning message text in "messages.properties" 114 * file. 115 */ 116 public static final String MSG_KEY = "at.clause.order"; 117 118 /** 119 * Default order of atclauses. 120 */ 121 private static final String[] DEFAULT_ORDER = { 122 "@author", "@version", 123 "@param", "@return", 124 "@throws", "@exception", 125 "@see", "@since", 126 "@serial", "@serialField", 127 "@serialData", "@deprecated", 128 }; 129 130 /** 131 * Specify block tags targeted. 132 */ 133 @XdocsPropertyType(PropertyType.TOKEN_ARRAY) 134 private BitSet target = TokenUtil.asBitSet( 135 TokenTypes.CLASS_DEF, 136 TokenTypes.INTERFACE_DEF, 137 TokenTypes.ENUM_DEF, 138 TokenTypes.METHOD_DEF, 139 TokenTypes.CTOR_DEF, 140 TokenTypes.VARIABLE_DEF, 141 TokenTypes.RECORD_DEF, 142 TokenTypes.COMPACT_CTOR_DEF 143 ); 144 145 /** 146 * Specify the order by tags. 147 */ 148 private List<String> tagOrder = Arrays.asList(DEFAULT_ORDER); 149 150 /** 151 * Setter to specify block tags targeted. 152 * 153 * @param targets user's targets. 154 * @since 6.0 155 */ 156 public void setTarget(String... targets) { 157 target = TokenUtil.asBitSet(targets); 158 } 159 160 /** 161 * Setter to specify the order by tags. 162 * 163 * @param orders user's orders. 164 * @since 6.0 165 */ 166 public void setTagOrder(String... orders) { 167 tagOrder = Arrays.asList(orders); 168 } 169 170 @Override 171 public int[] getDefaultJavadocTokens() { 172 return new int[] { 173 JavadocTokenTypes.JAVADOC, 174 }; 175 } 176 177 @Override 178 public int[] getRequiredJavadocTokens() { 179 return getAcceptableJavadocTokens(); 180 } 181 182 @Override 183 public void visitJavadocToken(DetailNode ast) { 184 final int parentType = getParentType(getBlockCommentAst()); 185 186 if (target.get(parentType)) { 187 checkOrderInTagSection(ast); 188 } 189 } 190 191 /** 192 * Checks order of atclauses in tag section node. 193 * 194 * @param javadoc Javadoc root node. 195 */ 196 private void checkOrderInTagSection(DetailNode javadoc) { 197 int maxIndexOfPreviousTag = 0; 198 199 for (DetailNode node : javadoc.getChildren()) { 200 if (node.getType() == JavadocTokenTypes.JAVADOC_TAG) { 201 final String tagText = JavadocUtil.getFirstChild(node).getText(); 202 final int indexOfCurrentTag = tagOrder.indexOf(tagText); 203 204 if (indexOfCurrentTag != -1) { 205 if (indexOfCurrentTag < maxIndexOfPreviousTag) { 206 log(node.getLineNumber(), MSG_KEY, tagOrder.toString()); 207 } 208 else { 209 maxIndexOfPreviousTag = indexOfCurrentTag; 210 } 211 } 212 } 213 } 214 } 215 216 /** 217 * Returns type of parent node. 218 * 219 * @param commentBlock child node. 220 * @return parent type. 221 */ 222 private static int getParentType(DetailAST commentBlock) { 223 final DetailAST parentNode = commentBlock.getParent(); 224 int result = parentNode.getType(); 225 if (result == TokenTypes.TYPE || result == TokenTypes.MODIFIERS) { 226 result = parentNode.getParent().getType(); 227 } 228 else if (parentNode.getParent() != null 229 && parentNode.getParent().getType() == TokenTypes.MODIFIERS) { 230 result = parentNode.getParent().getParent().getType(); 231 } 232 return result; 233 } 234 235 }