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