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     * @param targets user's targets.
128     */
129    public void setTarget(String... targets) {
130        final List<Integer> customTarget = new ArrayList<>();
131        for (String temp : targets) {
132            customTarget.add(TokenUtil.getTokenId(temp.trim()));
133        }
134        target = customTarget;
135    }
136
137    /**
138     * Setter to specify the order by tags.
139     * @param orders user's orders.
140     */
141    public void setTagOrder(String... orders) {
142        final List<String> customOrder = new ArrayList<>();
143        for (String order : orders) {
144            customOrder.add(order.trim());
145        }
146        tagOrder = customOrder;
147    }
148
149    @Override
150    public int[] getDefaultJavadocTokens() {
151        return new int[] {
152            JavadocTokenTypes.JAVADOC,
153        };
154    }
155
156    @Override
157    public int[] getRequiredJavadocTokens() {
158        return getAcceptableJavadocTokens();
159    }
160
161    @Override
162    public void visitJavadocToken(DetailNode ast) {
163        final int parentType = getParentType(getBlockCommentAst());
164
165        if (target.contains(parentType)) {
166            checkOrderInTagSection(ast);
167        }
168    }
169
170    /**
171     * Checks order of atclauses in tag section node.
172     * @param javadoc Javadoc root node.
173     */
174    private void checkOrderInTagSection(DetailNode javadoc) {
175        int maxIndexOfPreviousTag = 0;
176
177        for (DetailNode node : javadoc.getChildren()) {
178            if (node.getType() == JavadocTokenTypes.JAVADOC_TAG) {
179                final String tagText = JavadocUtil.getFirstChild(node).getText();
180                final int indexOfCurrentTag = tagOrder.indexOf(tagText);
181
182                if (indexOfCurrentTag != -1) {
183                    if (indexOfCurrentTag < maxIndexOfPreviousTag) {
184                        log(node.getLineNumber(), MSG_KEY, tagOrder.toString());
185                    }
186                    else {
187                        maxIndexOfPreviousTag = indexOfCurrentTag;
188                    }
189                }
190            }
191        }
192    }
193
194    /**
195     * Returns type of parent node.
196     * @param commentBlock child node.
197     * @return parent type.
198     */
199    private static int getParentType(DetailAST commentBlock) {
200        final DetailAST parentNode = commentBlock.getParent();
201        int result = 0;
202        if (parentNode != null) {
203            result = parentNode.getType();
204            if (result == TokenTypes.TYPE || result == TokenTypes.MODIFIERS) {
205                result = parentNode.getParent().getType();
206            }
207        }
208        return result;
209    }
210
211}