001///////////////////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
003// Copyright (C) 2001-2024 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
022/**
023 * Represents a Javadoc tag. Provides methods to query what type of tag it is.
024 */
025public class JavadocTag {
026
027    /** The line number of the tag. **/
028    private final int lineNo;
029    /** The column number of the tag. **/
030    private final int columnNo;
031    /** An optional first argument. For example the parameter name. **/
032    private final String firstArg;
033    /** The JavadocTagInfo representing this tag. **/
034    private final JavadocTagInfo tagInfo;
035
036    /**
037     * Constructs the object.
038     *
039     * @param line the line number of the tag
040     * @param column the column number of the tag
041     * @param tag the tag string
042     * @param firstArg the tag argument
043     **/
044    public JavadocTag(int line, int column, String tag, String firstArg) {
045        lineNo = line;
046        columnNo = column;
047        this.firstArg = firstArg;
048        tagInfo = JavadocTagInfo.fromName(tag);
049    }
050
051    /**
052     * Constructs the object.
053     *
054     * @param line the line number of the tag
055     * @param column the column number of the tag
056     * @param tag the tag string
057     **/
058    public JavadocTag(int line, int column, String tag) {
059        this(line, column, tag, null);
060    }
061
062    /**
063     * Gets tag name.
064     *
065     * @return the tag string
066     */
067    public String getTagName() {
068        return tagInfo.getName();
069    }
070
071    /**
072     * Returns first argument.
073     *
074     * @return the first argument. null if not set.
075     */
076    public String getFirstArg() {
077        return firstArg;
078    }
079
080    /**
081     * Gets the line number.
082     *
083     * @return the line number
084     */
085    public int getLineNo() {
086        return lineNo;
087    }
088
089    /**
090     * Gets column number.
091     *
092     * @return the column number
093     */
094    public int getColumnNo() {
095        return columnNo;
096    }
097
098    @Override
099    public String toString() {
100        return "JavadocTag[tag='" + tagInfo.getName()
101                + "' lineNo=" + lineNo
102                + ", columnNo=" + columnNo
103                + ", firstArg='" + firstArg + "']";
104    }
105
106    /**
107     * Checks that the tag is an 'return' tag.
108     *
109     * @return whether the tag is an 'return' tag
110     */
111    public boolean isReturnTag() {
112        return tagInfo == JavadocTagInfo.RETURN;
113    }
114
115    /**
116     * Checks that the tag is an 'param' tag.
117     *
118     * @return whether the tag is an 'param' tag
119     */
120    public boolean isParamTag() {
121        return tagInfo == JavadocTagInfo.PARAM;
122    }
123
124    /**
125     * Checks that the tag is an 'throws' or 'exception' tag.
126     *
127     * @return whether the tag is an 'throws' or 'exception' tag
128     */
129    public boolean isThrowsTag() {
130        return tagInfo == JavadocTagInfo.THROWS
131            || tagInfo == JavadocTagInfo.EXCEPTION;
132    }
133
134    /**
135     * Checks that the tag is a 'see' or 'inheritDoc' tag.
136     *
137     * @return whether the tag is a 'see' or 'inheritDoc' tag
138     */
139    public boolean isSeeOrInheritDocTag() {
140        return tagInfo == JavadocTagInfo.SEE || isInheritDocTag();
141    }
142
143    /**
144     * Checks that the tag is a 'inheritDoc' tag.
145     *
146     * @return whether the tag is a 'inheritDoc' tag
147     */
148    public boolean isInheritDocTag() {
149        return tagInfo == JavadocTagInfo.INHERIT_DOC;
150    }
151
152    /**
153     * Checks that the tag can contain references to imported classes.
154     *
155     * @return whether the tag can contain references to imported classes
156     */
157    public boolean canReferenceImports() {
158        return tagInfo == JavadocTagInfo.SEE
159                || tagInfo == JavadocTagInfo.LINK
160                || tagInfo == JavadocTagInfo.VALUE
161                || tagInfo == JavadocTagInfo.LINKPLAIN
162                || tagInfo == JavadocTagInfo.THROWS
163                || tagInfo == JavadocTagInfo.EXCEPTION;
164    }
165
166}