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