001////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code for adherence to a set of rules.
003// Copyright (C) 2001-2014  Oliver Burn
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////////////////////////////////////////////////////////////////////////////////
019package com.puppycrawl.tools.checkstyle.checks.javadoc;
020
021import com.puppycrawl.tools.checkstyle.api.JavadocTagInfo;
022
023/**
024 * Represents a Javadoc tag. Provides methods to query what type of tag it is.
025 * @author Oliver Burn
026 */
027public class JavadocTag
028{
029    /** the line number of the tag **/
030    private final int lineNo;
031    /** the column number of the tag **/
032    private int columnNo;
033    /** an optional first argument. For example the parameter name. **/
034    private final String arg1;
035    /** the JavadocTagInfo representing this tag **/
036    private final JavadocTagInfo tagInfo;
037
038    /**
039     * Constructs the object.
040     * @param line the line number of the tag
041     * @param column the column number of the tag
042     * @param tag the tag string
043     * @param arg1 the tag argument
044     **/
045    public JavadocTag(int line, int column, String tag, String arg1)
046    {
047        lineNo = line;
048        columnNo = column;
049        this.arg1 = arg1;
050        tagInfo = JavadocTagInfo.fromName(tag);
051    }
052
053    /**
054     * Constructs the object.
055     * @param line the line number of the tag
056     * @param column the column number of the tag
057     * @param tag the tag string
058     **/
059    public JavadocTag(int line, int column, String tag)
060    {
061        this(line, column, tag, null);
062    }
063
064    /** @return the tag string **/
065    public String getTagName()
066    {
067        return tagInfo.getName();
068    }
069
070    /** @return the first argument. null if not set. **/
071    public String getArg1()
072    {
073        return arg1;
074    }
075
076    /** @return the line number **/
077    public int getLineNo()
078    {
079        return lineNo;
080    }
081
082    /** @return the column number */
083    public int getColumnNo()
084    {
085        return columnNo;
086    }
087
088    @Override
089    public String toString()
090    {
091        return "{Tag = '" + getTagName() + "', lineNo = " + getLineNo()
092            + ", columnNo=" + columnNo + ", Arg1 = '" + getArg1() + "'}";
093    }
094
095    /** @return whether the tag is an 'author' tag **/
096    public boolean isAuthorTag()
097    {
098        return JavadocTagInfo.AUTHOR.equals(tagInfo);
099    }
100
101    /** @return whether the tag is an 'return' tag **/
102    public boolean isReturnTag()
103    {
104        return JavadocTagInfo.RETURN.equals(tagInfo);
105    }
106
107    /** @return whether the tag is an 'param' tag **/
108    public boolean isParamTag()
109    {
110        return JavadocTagInfo.PARAM.equals(tagInfo);
111    }
112
113    /** @return whether the tag is an 'throws' or 'exception' tag **/
114    public boolean isThrowsTag()
115    {
116        return (JavadocTagInfo.THROWS.equals(tagInfo)
117            || JavadocTagInfo.EXCEPTION.equals(tagInfo));
118    }
119
120    /** @return whether the tag is a 'see' or 'inheritDoc' tag **/
121    public boolean isSeeOrInheritDocTag()
122    {
123        return (JavadocTagInfo.SEE.equals(tagInfo) || isInheritDocTag());
124    }
125
126    /** @return whether the tag is a 'inheritDoc' tag **/
127    public boolean isInheritDocTag()
128    {
129        return JavadocTagInfo.INHERIT_DOC.equals(tagInfo);
130    }
131
132    /** @return whether the tag can contain references to imported classes **/
133    public boolean canReferenceImports()
134    {
135        return (JavadocTagInfo.SEE.equals(tagInfo)
136                || JavadocTagInfo.LINK.equals(tagInfo)
137                || JavadocTagInfo.LINKPLAIN.equals(tagInfo)
138                || JavadocTagInfo.THROWS.equals(tagInfo)
139                || JavadocTagInfo.EXCEPTION.equals(tagInfo));
140    }
141}
142