com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocMissingLeadingAsteriskCheck Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of checkstyle Show documentation
Show all versions of checkstyle Show documentation
Checkstyle is a development tool to help programmers write Java code
that adheres to a coding standard
////////////////////////////////////////////////////////////////////////////////
// checkstyle: Checks Java source code for adherence to a set of rules.
// Copyright (C) 2001-2021 the original author or authors.
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
////////////////////////////////////////////////////////////////////////////////
package com.puppycrawl.tools.checkstyle.checks.javadoc;
import com.puppycrawl.tools.checkstyle.StatelessCheck;
import com.puppycrawl.tools.checkstyle.api.DetailNode;
import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
/**
*
* Checks if the javadoc has
*
* leading asterisks on each line.
*
*
* The check does not require asterisks on the first line, nor on the last line if it is blank.
* All other lines in a Javadoc should start with {@code *}, including blank lines and code blocks.
*
*
* -
* Property {@code violateExecutionOnNonTightHtml} - Control when to print violations if the
* Javadoc being examined by this check violates the tight html rules defined at
* Tight-HTML Rules.
* Type is {@code boolean}.
* Default value is {@code false}.
*
*
*
* To configure the check:
*
*
* <module name="JavadocMissingLeadingAsterisk"/>
*
*
* Example:
*
*
* /**
* * Valid Java-style comment.
* *
* * <pre>
* * int value = 0;
* * </pre>
* */
* class JavaStyle {} // ok
*
* /** Valid Scala-style comment.
* * Some description here.
* **/
* class ScalaStyle {} // ok
*
* /** **
* * Asterisks on first and last lines are optional.
* * */
* class Asterisks {} // ok
*
* /** No asterisks are required for single-line comments. */
* class SingleLine {} // ok
*
* /** // violation on next blank line, javadoc has lines without leading asterisk.
*
* */
* class BlankLine {}
*
* /** Wrapped
* single-line comment */ // violation, javadoc has lines without leading asterisk.
* class Wrapped {}
*
* /**
* * <pre>
* int value; // violation, javadoc has lines without leading asterisk.
* * </pre>
* */
* class Code {}
*
*
* Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
*
*
* Violation Message Keys:
*
*
* -
* {@code javadoc.missed.html.close}
*
* -
* {@code javadoc.missing.asterisk}
*
* -
* {@code javadoc.parse.rule.error}
*
* -
* {@code javadoc.wrong.singleton.html.tag}
*
*
*
* @since 8.38
*/
@StatelessCheck
public class JavadocMissingLeadingAsteriskCheck extends AbstractJavadocCheck {
/**
* A key is pointing to the warning message text in "messages.properties"
* file.
*/
public static final String MSG_MISSING_ASTERISK = "javadoc.missing.asterisk";
@Override
public int[] getRequiredJavadocTokens() {
return new int[] {
JavadocTokenTypes.NEWLINE,
};
}
@Override
public int[] getAcceptableJavadocTokens() {
return getRequiredJavadocTokens();
}
@Override
public int[] getDefaultJavadocTokens() {
return getRequiredJavadocTokens();
}
@Override
public void visitJavadocToken(DetailNode detailNode) {
DetailNode nextSibling = getNextNode(detailNode);
// Till https://github.com/checkstyle/checkstyle/issues/9005
// Due to bug in the Javadoc parser there may be phantom description nodes.
while (TokenUtil.isOfType(nextSibling.getType(),
JavadocTokenTypes.DESCRIPTION, JavadocTokenTypes.WS)) {
nextSibling = getNextNode(nextSibling);
}
if (!isLeadingAsterisk(nextSibling) && !isLastLine(nextSibling)) {
log(nextSibling.getLineNumber(), MSG_MISSING_ASTERISK);
}
}
/**
* Gets next node in the ast (sibling or parent sibling for the last node).
*
* @param detailNode the node to process
* @return next node.
*/
private static DetailNode getNextNode(DetailNode detailNode) {
DetailNode node = JavadocUtil.getFirstChild(detailNode);
if (node == null) {
node = JavadocUtil.getNextSibling(detailNode);
if (node == null) {
DetailNode parent = detailNode;
do {
parent = parent.getParent();
node = JavadocUtil.getNextSibling(parent);
} while (node == null);
}
}
return node;
}
/**
* Checks whether the given node is a leading asterisk.
*
* @param detailNode the node to process
* @return {@code true} if the node is {@link JavadocTokenTypes#LEADING_ASTERISK}
*/
private static boolean isLeadingAsterisk(DetailNode detailNode) {
return detailNode.getType() == JavadocTokenTypes.LEADING_ASTERISK;
}
/**
* Checks whether this node is the end of a Javadoc comment,
* optionally preceded by blank text.
*
* @param detailNode the node to process
* @return {@code true} if the node is {@link JavadocTokenTypes#EOF}
*/
private static boolean isLastLine(DetailNode detailNode) {
final DetailNode node;
if (detailNode.getType() == JavadocTokenTypes.TEXT
&& CommonUtil.isBlank(detailNode.getText())) {
node = getNextNode(detailNode);
}
else {
node = detailNode;
}
return node.getType() == JavadocTokenTypes.EOF;
}
}