Source code

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