001//////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code for adherence to a set of rules. 003// Copyright (C) 2001-2017 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.List; 025 026import com.puppycrawl.tools.checkstyle.api.DetailAST; 027import com.puppycrawl.tools.checkstyle.api.DetailNode; 028import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes; 029import com.puppycrawl.tools.checkstyle.api.TokenTypes; 030import com.puppycrawl.tools.checkstyle.utils.JavadocUtils; 031import com.puppycrawl.tools.checkstyle.utils.TokenUtils; 032 033/** 034 * <p> 035 * Checks the order of 036 * <a href="http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDBEFIF"> 037 * javadoc block-tags or javadoc tags</a>. 038 * </p> 039 * <p> 040 * Note: Google used term "at-clauses" for block tags in his guide till 2017-02-28. 041 * </p> 042 * 043 * <p> 044 * The check allows to configure itself by using the following properties: 045 * </p> 046 * <ul> 047 * <li> 048 * target - allows to specify targets to check at-clauses. 049 * </li> 050 * <li> 051 * tagOrder - allows to specify the order by tags. 052 * </li> 053 * </ul> 054 * <p> 055 * Default configuration: 056 * </p> 057 * <pre> 058 * <module name="AtclauseOrderCheck"> 059 * <property name="tagOrder" value="@author, @version, @param, 060 * @return, @throws, @exception, @see, @since, @serial, 061 * @serialField, @serialData, @deprecated"/> 062 * <property name="target" value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF, 063 * METHOD_DEF, CTOR_DEF, VARIABLE_DEF"/> 064 * </module> 065 * </pre> 066 * 067 * @author max 068 * 069 */ 070public class AtclauseOrderCheck extends AbstractJavadocCheck { 071 072 /** 073 * A key is pointing to the warning message text in "messages.properties" 074 * file. 075 */ 076 public static final String MSG_KEY = "at.clause.order"; 077 078 /** 079 * Default order of atclauses. 080 */ 081 private static final String[] DEFAULT_ORDER = { 082 "@author", "@version", 083 "@param", "@return", 084 "@throws", "@exception", 085 "@see", "@since", 086 "@serial", "@serialField", 087 "@serialData", "@deprecated", 088 }; 089 090 /** 091 * Default target of checking atclauses. 092 */ 093 private List<Integer> target = Arrays.asList( 094 TokenTypes.CLASS_DEF, 095 TokenTypes.INTERFACE_DEF, 096 TokenTypes.ENUM_DEF, 097 TokenTypes.METHOD_DEF, 098 TokenTypes.CTOR_DEF, 099 TokenTypes.VARIABLE_DEF 100 ); 101 102 /** 103 * Order of atclauses. 104 */ 105 private List<String> tagOrder = Arrays.asList(DEFAULT_ORDER); 106 107 /** 108 * Sets custom targets. 109 * @param targets user's targets. 110 */ 111 public void setTarget(String... targets) { 112 final List<Integer> customTarget = new ArrayList<>(); 113 for (String temp : targets) { 114 customTarget.add(TokenUtils.getTokenId(temp.trim())); 115 } 116 target = customTarget; 117 } 118 119 /** 120 * Sets custom order of atclauses. 121 * @param orders user's orders. 122 */ 123 public void setTagOrder(String... orders) { 124 final List<String> customOrder = new ArrayList<>(); 125 for (String order : orders) { 126 customOrder.add(order.trim()); 127 } 128 tagOrder = customOrder; 129 } 130 131 @Override 132 public int[] getDefaultJavadocTokens() { 133 return new int[] { 134 JavadocTokenTypes.JAVADOC, 135 }; 136 } 137 138 @Override 139 public int[] getRequiredJavadocTokens() { 140 return getAcceptableJavadocTokens(); 141 } 142 143 @Override 144 public int[] getAcceptableTokens() { 145 return new int[] {TokenTypes.BLOCK_COMMENT_BEGIN}; 146 } 147 148 @Override 149 public int[] getRequiredTokens() { 150 return getAcceptableTokens(); 151 } 152 153 @Override 154 public void visitJavadocToken(DetailNode ast) { 155 final int parentType = getParentType(getBlockCommentAst()); 156 157 if (target.contains(parentType)) { 158 checkOrderInTagSection(ast); 159 } 160 } 161 162 /** 163 * Checks order of atclauses in tag section node. 164 * @param javadoc Javadoc root node. 165 */ 166 private void checkOrderInTagSection(DetailNode javadoc) { 167 int maxIndexOfPreviousTag = 0; 168 169 for (DetailNode node : javadoc.getChildren()) { 170 if (node.getType() == JavadocTokenTypes.JAVADOC_TAG) { 171 final String tagText = JavadocUtils.getFirstChild(node).getText(); 172 final int indexOfCurrentTag = tagOrder.indexOf(tagText); 173 174 if (indexOfCurrentTag != -1) { 175 if (indexOfCurrentTag < maxIndexOfPreviousTag) { 176 log(node.getLineNumber(), MSG_KEY, tagOrder.toString()); 177 } 178 else { 179 maxIndexOfPreviousTag = indexOfCurrentTag; 180 } 181 } 182 } 183 } 184 } 185 186 /** 187 * Returns type of parent node. 188 * @param commentBlock child node. 189 * @return parent type. 190 */ 191 private static int getParentType(DetailAST commentBlock) { 192 final DetailAST parentNode = commentBlock.getParent(); 193 int type = parentNode.getType(); 194 if (type == TokenTypes.TYPE || type == TokenTypes.MODIFIERS) { 195 type = parentNode.getParent().getType(); 196 } 197 return type; 198 } 199}