KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > puppycrawl > tools > checkstyle > checks > javadoc > WriteTagCheck


1 ////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code for adherence to a set of rules.
3 // Copyright (C) 2001-2005 Oliver Burn
4 //
5 // This library is free software; you can redistribute it and/or
6 // modify it under the terms of the GNU Lesser General Public
7 // License as published by the Free Software Foundation; either
8 // version 2.1 of the License, or (at your option) any later version.
9 //
10 // This library is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 // Lesser General Public License for more details.
14 //
15 // You should have received a copy of the GNU Lesser General Public
16 // License along with this library; if not, write to the Free Software
17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 ////////////////////////////////////////////////////////////////////////////////
19 package com.puppycrawl.tools.checkstyle.checks.javadoc;
20
21 import com.puppycrawl.tools.checkstyle.api.Check;
22 import com.puppycrawl.tools.checkstyle.api.DetailAST;
23 import com.puppycrawl.tools.checkstyle.api.FileContents;
24 import com.puppycrawl.tools.checkstyle.api.SeverityLevel;
25 import com.puppycrawl.tools.checkstyle.api.TextBlock;
26 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
27 import com.puppycrawl.tools.checkstyle.api.Utils;
28 import java.util.regex.Matcher JavaDoc;
29 import java.util.regex.Pattern JavaDoc;
30 import java.util.regex.PatternSyntaxException JavaDoc;
31 import org.apache.commons.beanutils.ConversionException;
32
33 /**
34  * <p>
35  * Outputs a JavaDoc tag as information. Can be used e.g. with the stylesheets
36  * that sort the report by author name.
37  * To define the format for a tag, set property tagFormat to a
38  * regular expression.
39  * This check uses two different severity levels. The normal one is used for
40  * reporting when the tag is missing. The additional one (tagSeverity) is used
41  * for the level of reporting when the tag exists. The default value for
42  * tagSeverity is info.
43  * </p>
44  * <p> An example of how to configure the check for printing author name is:
45  *</p>
46  * <pre>
47  * &lt;module name="WriteTag"&gt;
48  * &lt;property name="tag" value="@author"/&gt;
49  * &lt;property name="tagFormat" value="\S"/&gt;
50  * &lt;/module&gt;
51  * </pre>
52  * <p> An example of how to configure the check to print warnings if an
53  * "@incomplete" tag is found, and not print anything if it is not found:
54  *</p>
55  * <pre>
56  * &lt;module name="WriteTag"&gt;
57  * &lt;property name="tag" value="@incomplete"/&gt;
58  * &lt;property name="tagFormat" value="\S"/&gt;
59  * &lt;property name="severity" value="ignore"/&gt;
60  * &lt;property name="tagSeverity" value="warning"/&gt;
61  * &lt;/module&gt;
62  * </pre>
63  *
64  * @author Daniel Grenner
65  * @version 1.0
66  */
67 public class WriteTagCheck
68     extends Check
69 {
70     /** compiled regexp to match tag **/
71     private Pattern JavaDoc mTagRE;
72     /** compiled regexp to match tag content **/
73     private Pattern JavaDoc mTagFormatRE;
74
75     /** regexp to match tag */
76     private String JavaDoc mTag;
77     /** regexp to match tag content */
78     private String JavaDoc mTagFormat;
79     /** the severity level of found tag reports */
80     private SeverityLevel mTagSeverityLevel = SeverityLevel.INFO;
81
82     /**
83      * Sets the tag to check.
84      * @param aTag tag to check
85      * @throws ConversionException If the tag is not a valid regular exception.
86      */
87     public void setTag(String JavaDoc aTag)
88         throws ConversionException
89     {
90         try {
91             mTag = aTag;
92             mTagRE = Utils.getPattern(aTag + "\\s+(.*$)");
93         }
94         catch (final PatternSyntaxException JavaDoc e) {
95             throw new ConversionException("unable to parse " + aTag, e);
96         }
97     }
98
99     /**
100      * Set the tag format.
101      * @param aFormat a <code>String</code> value
102      * @throws ConversionException unable to parse aFormat
103      */
104     public void setTagFormat(String JavaDoc aFormat)
105         throws ConversionException
106     {
107         try {
108             mTagFormat = aFormat;
109             mTagFormatRE = Utils.getPattern(aFormat);
110         }
111         catch (final PatternSyntaxException JavaDoc e) {
112             throw new ConversionException("unable to parse " + aFormat, e);
113         }
114     }
115
116     /**
117      * Sets the tag severity level. The string should be one of the names
118      * defined in the <code>SeverityLevel</code> class.
119      *
120      * @param aSeverity The new severity level
121      * @see SeverityLevel
122      */
123     public final void setTagSeverity(String JavaDoc aSeverity)
124     {
125         mTagSeverityLevel = SeverityLevel.getInstance(aSeverity);
126     }
127
128     /** {@inheritDoc} */
129     public int[] getDefaultTokens()
130     {
131         return new int[] {TokenTypes.INTERFACE_DEF, TokenTypes.CLASS_DEF, };
132     }
133
134     /** {@inheritDoc} */
135     public int[] getAcceptableTokens()
136     {
137         return new int[] {TokenTypes.INTERFACE_DEF,
138                           TokenTypes.CLASS_DEF,
139                           TokenTypes.METHOD_DEF,
140         };
141     }
142
143     /** {@inheritDoc} */
144     public void visitToken(DetailAST aAST)
145     {
146         final FileContents contents = getFileContents();
147         final int lineNo = aAST.getLineNo();
148         final TextBlock cmt =
149             contents.getJavadocBefore(lineNo);
150         if (cmt == null) {
151             log(lineNo, "type.missingTag", mTag);
152         }
153         else {
154             checkTag(lineNo, cmt.getText(), mTag, mTagRE, mTagFormatRE,
155                 mTagFormat);
156         }
157     }
158
159     /**
160      * Verifies that a type definition has a required tag.
161      * @param aLineNo the line number for the type definition.
162      * @param aCmt the Javadoc comment for the type definition.
163      * @param aTag the required tag name.
164      * @param aTagRE regexp for the full tag.
165      * @param aFormatRE regexp for the tag value.
166      * @param aFormat pattern for the tag value.
167      */
168     private void checkTag(
169             int aLineNo,
170             String JavaDoc[] aCmt,
171             String JavaDoc aTag,
172             Pattern JavaDoc aTagRE,
173             Pattern JavaDoc aFormatRE,
174             String JavaDoc aFormat)
175     {
176         if (aTagRE == null) {
177             return;
178         }
179
180         int tagCount = 0;
181         for (int i = 0; i < aCmt.length; i++) {
182             final String JavaDoc s = aCmt[i];
183             final Matcher JavaDoc matcher = aTagRE.matcher(s);
184             if (matcher.find()) {
185                 tagCount += 1;
186                 final int contentStart = matcher.start(1);
187                 final String JavaDoc content = s.substring(contentStart);
188                 if ((aFormatRE != null) && !aFormatRE.matcher(content).find()) {
189                     log(aLineNo + i - aCmt.length, "type.tagFormat", aTag,
190                         aFormat);
191                 }
192                 else {
193                     logTag(aLineNo + i - aCmt.length, aTag, content);
194                 }
195
196             }
197         }
198         if (tagCount == 0) {
199             log(aLineNo, "type.missingTag", aTag);
200         }
201
202     }
203
204
205     /**
206      * Log a message.
207      *
208      * @param aLine the line number where the error was found
209      * @param aTag the javdoc tag to be logged
210      * @param aTagValue the contents of the tag
211      *
212      * @see java.text.MessageFormat
213      */
214     protected final void logTag(int aLine, String JavaDoc aTag, String JavaDoc aTagValue)
215     {
216         final String JavaDoc originalSeverity = getSeverity();
217         setSeverity(mTagSeverityLevel.getName());
218
219         log(aLine, "javadoc.writeTag", aTag, aTagValue);
220
221         setSeverity(originalSeverity);
222     }
223 }
224
Popular Tags