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 mLineNo;
031    /** the column number of the tag **/
032    private int mColumnNo;
033    /** an optional first argument. For example the parameter name. **/
034    private final String mArg1;
035    /** the JavadocTagInfo representing this tag **/
036    private final JavadocTagInfo mTagInfo;
037
038    /**
039     * Constructs the object.
040     * @param aLine the line number of the tag
041     * @param aColumn the column number of the tag
042     * @param aTag the tag string
043     * @param aArg1 the tag argument
044     **/
045    public JavadocTag(int aLine, int aColumn, String aTag, String aArg1)
046    {
047        mLineNo = aLine;
048        mColumnNo = aColumn;
049        mArg1 = aArg1;
050        mTagInfo = JavadocTagInfo.fromName(aTag);
051    }
052
053    /**
054     * Constructs the object.
055     * @param aLine the line number of the tag
056     * @param aColumn the column number of the tag
057     * @param aTag the tag string
058     **/
059    public JavadocTag(int aLine, int aColumn, String aTag)
060    {
061        this(aLine, aColumn, aTag, null);
062    }
063
064    /** @return the tag string **/
065    public String getTagName()
066    {
067        return mTagInfo.getName();
068    }
069
070    /** @return the first argument. null if not set. **/
071    public String getArg1()
072    {
073        return mArg1;
074    }
075
076    /** @return the line number **/
077    public int getLineNo()
078    {
079        return mLineNo;
080    }
081
082    /** @return the column number */
083    public int getColumnNo()
084    {
085        return mColumnNo;
086    }
087
088    @Override
089    public String toString()
090    {
091        return "{Tag = '" + getTagName() + "', lineNo = " + getLineNo()
092            + ", columnNo=" + mColumnNo + ", Arg1 = '" + getArg1() + "'}";
093    }
094
095    /** @return whether the tag is an 'author' tag **/
096    public boolean isAuthorTag()
097    {
098        return JavadocTagInfo.AUTHOR.equals(mTagInfo);
099    }
100
101    /** @return whether the tag is an 'return' tag **/
102    public boolean isReturnTag()
103    {
104        return JavadocTagInfo.RETURN.equals(mTagInfo);
105    }
106
107    /** @return whether the tag is an 'param' tag **/
108    public boolean isParamTag()
109    {
110        return JavadocTagInfo.PARAM.equals(mTagInfo);
111    }
112
113    /** @return whether the tag is an 'throws' or 'exception' tag **/
114    public boolean isThrowsTag()
115    {
116        return (JavadocTagInfo.THROWS.equals(mTagInfo)
117            || JavadocTagInfo.EXCEPTION.equals(mTagInfo));
118    }
119
120    /** @return whether the tag is a 'see' or 'inheritDoc' tag **/
121    public boolean isSeeOrInheritDocTag()
122    {
123        return (JavadocTagInfo.SEE.equals(mTagInfo) || isInheritDocTag());
124    }
125
126    /** @return whether the tag is a 'inheritDoc' tag **/
127    public boolean isInheritDocTag()
128    {
129        return JavadocTagInfo.INHERIT_DOC.equals(mTagInfo);
130    }
131
132    /** @return whether the tag can contain references to imported classes **/
133    public boolean canReferenceImports()
134    {
135        return (JavadocTagInfo.SEE.equals(mTagInfo)
136                || JavadocTagInfo.LINK.equals(mTagInfo)
137                || JavadocTagInfo.LINKPLAIN.equals(mTagInfo)
138                || JavadocTagInfo.THROWS.equals(mTagInfo)
139                || JavadocTagInfo.EXCEPTION.equals(mTagInfo));
140    }
141}
142