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

Enum JavadocTagInfo

java.lang.Object

java.lang.Enum<JavadocTagInfo>

com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTagInfo

All Implemented Interfaces:

Serializable, Comparable<JavadocTagInfo>

public enum JavadocTagInfo
extends Enum<JavadocTagInfo>

This enum defines the various Javadoc tags and their properties.

This class was modeled after documentation located at javadoc and how to write.

Some of this documentation was a little incomplete (ex: valid placement of code, value, and literal tags).

Whenever an inconsistency was found the author's judgment was used.

For now, the number of required/optional tag arguments are not included because some Javadoc tags have very complex rules for determining this (ex: {@value} tag).

Also, the isValidOn method does not consider classes defined in a local code block (method, init block, etc.).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	JavadocTagInfo.Type	The Javadoc Type.

Enum Constant Summary

Enum Constants

Enum Constant	Description
AUTHOR	@author.
CODE	{@code}.
DEPRECATED	@deprecated.
DOC_ROOT	{@docRoot}.
EXCEPTION	@exception.
INHERIT_DOC	{@inheritDoc}.
LINK	{@link}.
LINKPLAIN	{@linkplain}.
LITERAL	{@literal}.
PARAM	@param.
RETURN	@return.
SEE	@see.
SERIAL	@serial.
SERIAL_DATA	@serialData.
SERIAL_FIELD	@serialField.
SINCE	@since.
THROWS	@throws.
VALUE	{@value}.
VERSION	@version.

Field Summary

Fields

Modifier and Type	Field	Description
private static final BitSet	DEF_TOKEN_TYPES	Default token types.
private static final BitSet	DEF_TOKEN_TYPES_DEPRECATED	Default token types for DEPRECATED Javadoc tag.
private final String	name	The tag name.
private static final Map<String,JavadocTagInfo>	NAME_TO_TAG	Holds tag name to tag enum mappings.
private final String	text	The tag text.
private static final Map<String,JavadocTagInfo>	TEXT_TO_TAG	Holds tag text to tag enum mappings.
private final JavadocTagInfo.Type	type	The tag type.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	JavadocTagInfo(String text, String name, JavadocTagInfo.Type type)	Sets the various properties of a Javadoc tag.

Method Summary

Modifier and Type	Method	Description
static JavadocTagInfo	fromName(String name)	Returns a JavadocTag from the tag name.
static JavadocTagInfo	fromText(String text)	Returns a JavadocTag from the tag text.
String	getName()	Gets the tag name.
String	getText()	Gets the tag text.
JavadocTagInfo.Type	getType()	Gets the Tag type defined by Type.
static boolean	isValidName(String name)	Returns whether the provided name is for a valid tag.
abstract boolean	isValidOn(DetailAST ast)	Checks if a particular Javadoc tag is valid within a Javadoc block of a given AST.
String	toString()
static JavadocTagInfo	valueOf(String name)	Returns the enum constant of this type with the specified name.
static JavadocTagInfo[]	values()	Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

AUTHOR

public static final JavadocTagInfo AUTHOR

@author.

CODE

public static final JavadocTagInfo CODE

{@code}.

DOC_ROOT

public static final JavadocTagInfo DOC_ROOT

{@docRoot}.

DEPRECATED

public static final JavadocTagInfo DEPRECATED

@deprecated.

EXCEPTION

public static final JavadocTagInfo EXCEPTION

@exception.

INHERIT_DOC

public static final JavadocTagInfo INHERIT_DOC

{@inheritDoc}.

LINK

public static final JavadocTagInfo LINK

{@link}.

LINKPLAIN

public static final JavadocTagInfo LINKPLAIN

{@linkplain}.

LITERAL

public static final JavadocTagInfo LITERAL

{@literal}.

PARAM

public static final JavadocTagInfo PARAM

@param.

RETURN

public static final JavadocTagInfo RETURN

@return.

SEE

public static final JavadocTagInfo SEE

@see.

SERIAL

public static final JavadocTagInfo SERIAL

@serial.

SERIAL_DATA

public static final JavadocTagInfo SERIAL_DATA

@serialData.

SERIAL_FIELD

public static final JavadocTagInfo SERIAL_FIELD

@serialField.

SINCE

public static final JavadocTagInfo SINCE

@since.

THROWS

public static final JavadocTagInfo THROWS

@throws.

VALUE

public static final JavadocTagInfo VALUE

{@value}.

VERSION

public static final JavadocTagInfo VERSION

@version.

Field Details

DEF_TOKEN_TYPES_DEPRECATED

private static final BitSet DEF_TOKEN_TYPES_DEPRECATED

Default token types for DEPRECATED Javadoc tag.

DEF_TOKEN_TYPES

private static final BitSet DEF_TOKEN_TYPES

Default token types.

TEXT_TO_TAG

private static final Map<String,JavadocTagInfo> TEXT_TO_TAG

Holds tag text to tag enum mappings.

NAME_TO_TAG

private static final Map<String,JavadocTagInfo> NAME_TO_TAG

Holds tag name to tag enum mappings.

text

private final String text

The tag text.

name

private final String name

The tag name.

type

private final JavadocTagInfo.Type type

The tag type.

Constructor Details

JavadocTagInfo

private JavadocTagInfo(String text,
 String name,
 JavadocTagInfo.Type type)

Sets the various properties of a Javadoc tag.

Parameters:

text - the tag text

name - the tag name

type - the type of tag

Method Details

values

public static JavadocTagInfo[] values()

Returns an array containing the constants of this enum type, in the order they are declared.

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static JavadocTagInfo valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

isValidOn

public abstract boolean isValidOn(DetailAST ast)

Checks if a particular Javadoc tag is valid within a Javadoc block of a given AST.

If passing in a DetailAST representing a non-void METHOD_DEF true would be returned. If passing in a DetailAST representing a CLASS_DEF false would be returned because CLASS_DEF's cannot return a value.

Parameters:

ast - the AST representing a type that can be Javadoc'd

Returns:

true if tag is valid.

getText

public String getText()

Gets the tag text.

Returns:

the tag text

getName

public String getName()

Gets the tag name.

Returns:

the tag name

getType

public JavadocTagInfo.Type getType()

Gets the Tag type defined by Type.

Returns:

the Tag type

fromText

public static JavadocTagInfo fromText(String text)

Returns a JavadocTag from the tag text.

Parameters:

text - String representing the tag text

Returns:

Returns a JavadocTag type from a String representing the tag

Throws:

NullPointerException - if the text is null

IllegalArgumentException - if the text is not a valid tag

fromName

public static JavadocTagInfo fromName(String name)

Returns a JavadocTag from the tag name.

Parameters:

name - String name of the tag

Returns:

Returns a JavadocTag type from a String representing the tag

Throws:

NullPointerException - if the text is null

IllegalArgumentException - if the text is not a valid tag. The name can be checked using isValidName(String)

isValidName

public static boolean isValidName(String name)

Returns whether the provided name is for a valid tag.

Parameters:

name - the tag name to check.

Returns:

whether the provided name is for a valid tag.

toString

public String toString()

Overrides:

toString in class Enum<JavadocTagInfo>