Package com.puppycrawl.tools.checkstyle.checks.javadoc

Class JavadocParamOrderCheck

java.lang.Object

com.puppycrawl.tools.checkstyle.AbstractAutomaticBean

com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter

com.puppycrawl.tools.checkstyle.api.AbstractCheck

com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck

com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocParamOrderCheck

All Implemented Interfaces:

Configurable, Contextualizable

public class JavadocParamOrderCheck
extends AbstractJavadocCheck

Checks that @param tags in Javadoc comments are in the same order as the parameters in the declaration.

Type parameters must come before regular parameters. For record declarations, record components are treated as regular parameters and must be documented after type parameters. For compact constructors, the expected parameter order is the order of the record components in the record declaration.

The check does not validate missing, extra, or duplicate @param tags. It reports only tags that move backward in the declaration order.

Since:

14.1.0

Nested Class Summary

Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean

AbstractAutomaticBean.OutputStreamOptions

Field Summary

Fields

Modifier and Type	Field	Description
private static final String	ELEMENT_END	Html element end symbol.
private static final String	ELEMENT_START	Html element start symbol.
private final Map<DetailNode,String>	javadocTags	Javadoc param tag names, mapped by their corresponding Javadoc node.
static final String	MSG_KEY	A key is pointing to the warning message text in "messages.properties" file.

Fields inherited from class com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck

MSG_JAVADOC_PARSE_RULE_ERROR, MSG_KEY_UNCLOSED_HTML_TAG

Constructor Summary

Constructors

Constructor	Description
JavadocParamOrderCheck()	Creates a new JavadocParamOrderCheck instance.

Method Summary

Modifier and Type	Method	Description
private static void	addParameterName(Collection<String> paramNames, DetailAST paramDef)	Adds a parameter name from the supplied parameter definition AST node.
private static void	addParameterNames(Collection<String> paramNames, DetailAST ast)	Adds parameter names from the supplied method or constructor AST node.
private static void	addRecordComponentNames(Collection<String> paramNames, DetailAST recordDef)	Adds record component names from the supplied record AST node.
private static void	addTypeParameterNames(Collection<String> paramNames, DetailAST ast)	Adds type parameter names from the supplied AST node.
private void	collectParam(DetailNode ast)	Collects a param tag.
int[]	getDefaultJavadocTokens()	Returns the default javadoc token types a check is interested in.
int[]	getDefaultTokens()	Returns the default token a check is interested in.
private static List<String>	getExpectedParamOrder(DetailAST ast)	Gets expected param tag order for the current AST node.
private List<Map.Entry<DetailNode,String>>	getMisorderedParamTags(DetailAST ast)	Gets collected Javadoc param tags that violate the expected declaration order.
private static List<DetailAST>	getRecordComponents(DetailAST recordDef)	Gets record component identifier nodes from a record definition.
private static DetailAST	getRecordDef(DetailAST ast)	Finds the nearest ancestor record definition node for the given AST node.
int[]	getRequiredJavadocTokens()	The javadoc tokens that this check must be registered for.
final int[]	getRequiredTokens()	The tokens that this check must be registered for.
void	visitJavadocToken(DetailNode ast)	Called to process a Javadoc token.
final void	visitToken(DetailAST ast)	Called to process a token.

Methods inherited from class com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck

acceptJavadocWithNonTightHtml, beginJavadocTree, beginTree, destroy, finishJavadocTree, getAcceptableJavadocTokens, getAcceptableTokens, getBlockCommentAst, init, isCommentNodesRequired, leaveJavadocToken, log, setJavadocTokens, setViolateExecutionOnNonTightHtml

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractCheck

clearViolations, finishTree, getFileContents, getFilePath, getLine, getLineCodePoints, getLines, getTabWidth, getTokenNames, getViolations, leaveToken, log, log, log, setFileContents, setTabWidth, setTokens

Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter

finishLocalSetup, getCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, setId, setSeverity

Methods inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean

configure, contextualize, getConfiguration, setupChild

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MSG_KEY

public static final String MSG_KEY

A key is pointing to the warning message text in "messages.properties" file.

See Also:

• Constant Field Values

ELEMENT_START

private static final String ELEMENT_START

Html element start symbol.

See Also:

• Constant Field Values

ELEMENT_END

private static final String ELEMENT_END

Html element end symbol.

See Also:

• Constant Field Values

javadocTags

private final Map<DetailNode,String> javadocTags

Javadoc param tag names, mapped by their corresponding Javadoc node.

Constructor Details

JavadocParamOrderCheck

public JavadocParamOrderCheck()

Creates a new JavadocParamOrderCheck instance.

Method Details

getDefaultTokens

public int[] getDefaultTokens()

Description copied from class: AbstractCheck

Returns the default token a check is interested in. Only used if the configuration for a check does not define the tokens.

Overrides:

getDefaultTokens in class AbstractJavadocCheck

Returns:

the default tokens

See Also:

• TokenTypes

getRequiredTokens

public final int[] getRequiredTokens()

Description copied from class: AbstractCheck

The tokens that this check must be registered for.

Overrides:

getRequiredTokens in class AbstractJavadocCheck

Returns:

the token set this must be registered for.

See Also:

• TokenTypes

getDefaultJavadocTokens

public int[] getDefaultJavadocTokens()

Description copied from class: AbstractJavadocCheck

Returns the default javadoc token types a check is interested in.

Specified by:

getDefaultJavadocTokens in class AbstractJavadocCheck

Returns:

the default javadoc token types

See Also:

• JavadocCommentsTokenTypes

getRequiredJavadocTokens

public int[] getRequiredJavadocTokens()

Description copied from class: AbstractJavadocCheck

The javadoc tokens that this check must be registered for.

Overrides:

getRequiredJavadocTokens in class AbstractJavadocCheck

Returns:

the javadoc token set this must be registered for.

See Also:

• JavadocCommentsTokenTypes

visitToken

public final void visitToken(DetailAST ast)

Description copied from class: AbstractCheck

Called to process a token.

Overrides:

visitToken in class AbstractJavadocCheck

Parameters:

ast - the token to process

visitJavadocToken

public void visitJavadocToken(DetailNode ast)

Description copied from class: AbstractJavadocCheck

Called to process a Javadoc token.

Specified by:

visitJavadocToken in class AbstractJavadocCheck

Parameters:

ast - the token to process

collectParam

private void collectParam(DetailNode ast)

Collects a param tag.

Parameters:

ast - the param tag node

getMisorderedParamTags

private List<Map.Entry<DetailNode,String>> getMisorderedParamTags(DetailAST ast)

Gets collected Javadoc param tags that violate the expected declaration order.

Parameters:

ast - Java AST node whose Javadoc is being checked

Returns:

collected Javadoc param tags that violate the expected declaration order

getExpectedParamOrder

private static List<String> getExpectedParamOrder(DetailAST ast)

Gets expected param tag order for the current AST node.

Parameters:

ast - Java AST node whose Javadoc is being checked

Returns:

expected param tag order

addTypeParameterNames

private static void addTypeParameterNames(Collection<String> paramNames,
 DetailAST ast)

Adds type parameter names from the supplied AST node.

Parameters:

paramNames - destination list

ast - node to inspect

addParameterNames

private static void addParameterNames(Collection<String> paramNames,
 DetailAST ast)

Adds parameter names from the supplied method or constructor AST node.

Parameters:

paramNames - destination list

ast - node to inspect

addParameterName

private static void addParameterName(Collection<String> paramNames,
 DetailAST paramDef)

Adds a parameter name from the supplied parameter definition AST node.

Parameters:

paramNames - destination list

paramDef - parameter definition node

addRecordComponentNames

private static void addRecordComponentNames(Collection<String> paramNames,
 DetailAST recordDef)

Adds record component names from the supplied record AST node.

Parameters:

paramNames - destination list

recordDef - record definition node

getRecordDef

private static DetailAST getRecordDef(DetailAST ast)

Finds the nearest ancestor record definition node for the given AST node.

Parameters:

ast - the AST node to start searching from

Returns:

the nearest RECORD_DEF AST node

getRecordComponents

private static List<DetailAST> getRecordComponents(DetailAST recordDef)

Gets record component identifier nodes from a record definition.

Parameters:

recordDef - record definition node

Returns:

record component identifier nodes