001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2023 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.ArrayList; 023import java.util.Arrays; 024import java.util.BitSet; 025import java.util.List; 026 027import com.puppycrawl.tools.checkstyle.PropertyType; 028import com.puppycrawl.tools.checkstyle.StatelessCheck; 029import com.puppycrawl.tools.checkstyle.XdocsPropertyType; 030import com.puppycrawl.tools.checkstyle.api.DetailAST; 031import com.puppycrawl.tools.checkstyle.api.DetailNode; 032import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes; 033import com.puppycrawl.tools.checkstyle.api.TokenTypes; 034import com.puppycrawl.tools.checkstyle.utils.JavadocUtil; 035import com.puppycrawl.tools.checkstyle.utils.TokenUtil; 036 037/** 038 * <p> 039 * Checks the order of 040 * <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDBEFIF"> 041 * javadoc block-tags or javadoc tags</a>. 042 * </p> 043 * <p> 044 * Note: Google used the term "at-clauses" for block tags in their guide till 2017-02-28. 045 * </p> 046 * 047 * <ul> 048 * <li> 049 * Property {@code violateExecutionOnNonTightHtml} - Control when to print violations if the 050 * Javadoc being examined by this check violates the tight html rules defined at 051 * <a href="https://checkstyle.org/writingjavadocchecks.html#Tight-HTML_rules">Tight-HTML Rules</a>. 052 * Type is {@code boolean}. 053 * Default value is {@code false}. 054 * </li> 055 * <li> 056 * Property {@code target} - Specify block tags targeted. 057 * Type is {@code java.lang.String[]}. 058 * Validation type is {@code tokenTypesSet}. 059 * Default value is 060 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF"> 061 * CLASS_DEF</a>, 062 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#COMPACT_CTOR_DEF"> 063 * COMPACT_CTOR_DEF</a>, 064 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF"> 065 * CTOR_DEF</a>, 066 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF"> 067 * ENUM_DEF</a>, 068 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF"> 069 * INTERFACE_DEF</a>, 070 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF"> 071 * METHOD_DEF</a>, 072 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF"> 073 * RECORD_DEF</a>, 074 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#VARIABLE_DEF"> 075 * VARIABLE_DEF</a>. 076 * </li> 077 * <li> 078 * Property {@code tagOrder} - Specify the order by tags. 079 * Type is {@code java.lang.String[]}. 080 * Default value is 081 * {@code @author, @deprecated, @exception, @param, @return, @see, @serial, @serialData, @serialField, @since, @throws, @version}. 082 * </li> 083 * </ul> 084 * <p> 085 * To configure the default check: 086 * </p> 087 * <pre> 088 * <module name="AtclauseOrder"/> 089 * </pre> 090 * <p> 091 * Example: 092 * </p> 093 * <pre> 094 * /** 095 * * Some javadoc. // OK 096 * * 097 * * @author Some javadoc. // OK 098 * * @version Some javadoc. // OK 099 * * @param Some javadoc. // OK 100 * * @return Some javadoc. // OK 101 * * @throws Some javadoc. // OK 102 * * @exception Some javadoc. // OK 103 * * @see Some javadoc. // OK 104 * * @since Some javadoc. // OK 105 * * @serial Some javadoc. // OK 106 * * @serialField // OK 107 * * @serialData // OK 108 * * @deprecated Some javadoc. // OK 109 * */ 110 * 111 * class Valid implements Serializable 112 * { 113 * } 114 * 115 * /** 116 * * Some javadoc. 117 * * 118 * * @since Some javadoc. // OK 119 * * @version Some javadoc. // Violation - wrong order 120 * * @deprecated 121 * * @see Some javadoc. // Violation - wrong order 122 * * @author Some javadoc. // Violation - wrong order 123 * */ 124 * 125 * class Invalid implements Serializable 126 * { 127 * } 128 * </pre> 129 * <p> 130 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 131 * </p> 132 * <p> 133 * Violation Message Keys: 134 * </p> 135 * <ul> 136 * <li> 137 * {@code at.clause.order} 138 * </li> 139 * <li> 140 * {@code javadoc.missed.html.close} 141 * </li> 142 * <li> 143 * {@code javadoc.parse.rule.error} 144 * </li> 145 * <li> 146 * {@code javadoc.wrong.singleton.html.tag} 147 * </li> 148 * </ul> 149 * 150 * @since 6.0 151 */ 152@StatelessCheck 153public class AtclauseOrderCheck extends AbstractJavadocCheck { 154 155 /** 156 * A key is pointing to the warning message text in "messages.properties" 157 * file. 158 */ 159 public static final String MSG_KEY = "at.clause.order"; 160 161 /** 162 * Default order of atclauses. 163 */ 164 private static final String[] DEFAULT_ORDER = { 165 "@author", "@version", 166 "@param", "@return", 167 "@throws", "@exception", 168 "@see", "@since", 169 "@serial", "@serialField", 170 "@serialData", "@deprecated", 171 }; 172 173 /** 174 * Specify block tags targeted. 175 */ 176 @XdocsPropertyType(PropertyType.TOKEN_ARRAY) 177 private BitSet target = TokenUtil.asBitSet( 178 TokenTypes.CLASS_DEF, 179 TokenTypes.INTERFACE_DEF, 180 TokenTypes.ENUM_DEF, 181 TokenTypes.METHOD_DEF, 182 TokenTypes.CTOR_DEF, 183 TokenTypes.VARIABLE_DEF, 184 TokenTypes.RECORD_DEF, 185 TokenTypes.COMPACT_CTOR_DEF 186 ); 187 188 /** 189 * Specify the order by tags. 190 */ 191 private List<String> tagOrder = Arrays.asList(DEFAULT_ORDER); 192 193 /** 194 * Setter to specify block tags targeted. 195 * 196 * @param targets user's targets. 197 */ 198 public void setTarget(String... targets) { 199 target = TokenUtil.asBitSet(targets); 200 } 201 202 /** 203 * Setter to specify the order by tags. 204 * 205 * @param orders user's orders. 206 */ 207 public void setTagOrder(String... orders) { 208 final List<String> customOrder = new ArrayList<>(orders.length); 209 for (String order : orders) { 210 customOrder.add(order.trim()); 211 } 212 tagOrder = customOrder; 213 } 214 215 @Override 216 public int[] getDefaultJavadocTokens() { 217 return new int[] { 218 JavadocTokenTypes.JAVADOC, 219 }; 220 } 221 222 @Override 223 public int[] getRequiredJavadocTokens() { 224 return getAcceptableJavadocTokens(); 225 } 226 227 @Override 228 public void visitJavadocToken(DetailNode ast) { 229 final int parentType = getParentType(getBlockCommentAst()); 230 231 if (target.get(parentType)) { 232 checkOrderInTagSection(ast); 233 } 234 } 235 236 /** 237 * Checks order of atclauses in tag section node. 238 * 239 * @param javadoc Javadoc root node. 240 */ 241 private void checkOrderInTagSection(DetailNode javadoc) { 242 int maxIndexOfPreviousTag = 0; 243 244 for (DetailNode node : javadoc.getChildren()) { 245 if (node.getType() == JavadocTokenTypes.JAVADOC_TAG) { 246 final String tagText = JavadocUtil.getFirstChild(node).getText(); 247 final int indexOfCurrentTag = tagOrder.indexOf(tagText); 248 249 if (indexOfCurrentTag != -1) { 250 if (indexOfCurrentTag < maxIndexOfPreviousTag) { 251 log(node.getLineNumber(), MSG_KEY, tagOrder.toString()); 252 } 253 else { 254 maxIndexOfPreviousTag = indexOfCurrentTag; 255 } 256 } 257 } 258 } 259 } 260 261 /** 262 * Returns type of parent node. 263 * 264 * @param commentBlock child node. 265 * @return parent type. 266 */ 267 private static int getParentType(DetailAST commentBlock) { 268 final DetailAST parentNode = commentBlock.getParent(); 269 int result = parentNode.getType(); 270 if (result == TokenTypes.TYPE || result == TokenTypes.MODIFIERS) { 271 result = parentNode.getParent().getType(); 272 } 273 else if (parentNode.getParent() != null 274 && parentNode.getParent().getType() == TokenTypes.MODIFIERS) { 275 result = parentNode.getParent().getParent().getType(); 276 } 277 return result; 278 } 279 280}