JavadocMissingLeadingAsteriskCheck.java
////////////////////////////////////////////////////////////////////////////////
// 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;
/**
* <p>
* Checks if the javadoc has
* <a href="https://docs.oracle.com/en/java/javase/14/docs/specs/javadoc/doc-comment-spec.html#leading-asterisks">
* leading asterisks</a> on each line.
* </p>
* <p>
* 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.
* </p>
* <ul>
* <li>
* Property {@code violateExecutionOnNonTightHtml} - Control when to print violations if the
* Javadoc being examined by this check violates the tight html rules defined at
* <a href="https://checkstyle.org/writingjavadocchecks.html#Tight-HTML_rules">Tight-HTML Rules</a>.
* Type is {@code boolean}.
* Default value is {@code false}.
* </li>
* </ul>
* <p>
* To configure the check:
* </p>
* <pre>
* <module name="JavadocMissingLeadingAsterisk"/>
* </pre>
* <p>
* Example:
* </p>
* <pre>
* /**
* * 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 {}
* </pre>
* <p>
* Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
* </p>
* <p>
* Violation Message Keys:
* </p>
* <ul>
* <li>
* {@code javadoc.missed.html.close}
* </li>
* <li>
* {@code javadoc.missing.asterisk}
* </li>
* <li>
* {@code javadoc.parse.rule.error}
* </li>
* <li>
* {@code javadoc.wrong.singleton.html.tag}
* </li>
* </ul>
*
* @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;
}
}