ParameterDocAnalyzer


1   package org.incava.doctorj;
2   
3   import java.io.*;
4   import java.util.*;
5   import net.sourceforge.pmd.ast.*;
6   import org.incava.analysis.*;
7   import org.incava.java.ParameterUtil;
8   import org.incava.java.SimpleNodeUtil;
9   import org.incava.javadoc.*;
10  import org.incava.text.Location;
11  import org.incava.text.SpellChecker;
12  
13  
14  /**
15   * Checks the validity of Javadoc for a list of parameters.
16   */
17  public class ParameterDocAnalyzer extends DocAnalyzer
18  {
19      /**
20       * The message for documented parameters for a function without any in the
21       * code.
22       */
23      public final static String   MSG_PARAMETERS_DOCUMENTED_BUT_NO_CODE_PARAMETERS = "Parameters documented but no code parameters";
24      
25      /**
26       * The message for a parameter field without a name.
27       */
28      public final static String   MSG_PARAMETER_WITHOUT_NAME = "Parameter tag without name";
29  
30      /**
31       * The message for a parameter field without a description.
32       */
33      public final static String   MSG_PARAMETER_WITHOUT_DESCRIPTION = "Parameter without description";
34  
35      /**
36       * The message for parameters being misordered with regard to the code.
37       */
38      public final static String   MSG_PARAMETER_NOT_IN_CODE_ORDER = "Parameter not in code order";
39  
40      /**
41       * The message for a parameter being apparently misspelled from that in the
42       * code.
43       */
44      public final static String   MSG_PARAMETER_MISSPELLED = "Parameter misspelled";
45  
46      /**
47       * The message for a parameter referring to argument type, not name.
48       */
49      public final static String   MSG_PARAMETER_TYPE_USED = "Parameter refers to type, not name";
50  
51      /**
52       * The message for an undocumented code parameter.
53       */
54      public final static String   MSG_PARAMETER_NOT_DOCUMENTED = "Parameter not documented";
55  
56      /**
57       * The message for a documented parameter not found in the code.
58       */
59      public final static String   MSG_PARAMETER_NOT_IN_CODE = "Parameter not in code";
60  
61      /**
62       * The message for a repeated documented parameter.
63       */
64      public final static String   MSG_PARAMETER_REPEATED = "Parameter repeated";
65  
66      /**
67       * The warning level for checking for the existence of Javadoc for
68       * parameters.
69       */
70      protected final static int CHKLVL_PARAM_DOC_EXISTS = 2;
71  
72      /**
73       * The Javadoc block applicable to this parameter list.
74       */
75      private JavadocNode _javadoc;
76  
77      /**
78       * The function containing the list of parameters.
79       */
80      private SimpleNode _function;
81  
82      /**
83       * The list of parameters in the code.
84       */
85      private ASTFormalParameters _parameterList;
86  
87      /**
88       * The list of parameters from the code, that were documented.
89       */
90      private List _documentedParameters = new ArrayList();
91  
92      private int _nodeLevel;
93  
94      /**
95       * Creates and runs the parameter documentation analyzer.
96       *
97       * @param report   The report to which to send violations.
98       * @param javadoc  The javadoc for the function. Should not be null.
99       * @param function The constructor or method.
100      */
101     public ParameterDocAnalyzer(Report report, JavadocNode javadoc, SimpleNode function, ASTFormalParameters parameterList, int nodeLevel)
102     {
103         super(report);
104 
105         _javadoc = javadoc;
106         _function = function;
107         _parameterList = parameterList;
108         _nodeLevel = nodeLevel;
109     }
110 
111     /**
112      * Analyzes the Javadoc for the parameter list.
113      */
114     public void run()
115     {
116         tr.Ace.log("function", _function);
117 
118         // foreach @throws / @parameter tag:
119         //  - check for target
120         //  - check for description
121         //  - in order as in code
122 
123         boolean misorderedReported = false;
124         int     parameterIndex     = 0;
125             
126         JavadocTaggedNode[] taggedComments = _javadoc.getTaggedComments();
127         for (int ti = 0; ti < taggedComments.length; ++ti) {
128             JavadocTaggedNode jtn = taggedComments[ti];
129             tr.Ace.bold("jtn", jtn);
130             JavadocTag tag = jtn.getTag();
131             
132             tr.Ace.yellow("tag", tag);
133             if (tag.text.equals(JavadocTags.PARAM)) {
134                 tr.Ace.magenta("parameter");
135                 
136                 JavadocElement tgt = jtn.getTarget();
137                 tr.Ace.magenta("tgt", tgt);
138 
139                 tr.Ace.yellow("parameter index: " + parameterIndex);
140 
141                 if (!SimpleNodeUtil.hasChildren(_parameterList)) {
142                     addViolation(MSG_PARAMETERS_DOCUMENTED_BUT_NO_CODE_PARAMETERS, tag.start, tag.end);
143                     break;
144                 }
145                 else if (tgt == null) {
146                     if (Options.warningLevel >= CHKLVL_TAG_CONTENT + _nodeLevel) {
147                         addViolation(MSG_PARAMETER_WITHOUT_NAME, tag.start, tag.end);
148                     }
149                     else {
150                         tr.Ace.log("function", _function);
151                     }
152                 }
153                 else {
154                     JavadocElement desc = jtn.getDescriptionNonTarget();
155                     if (jtn.getDescriptionNonTarget() == null) {
156                         if (Options.warningLevel >= CHKLVL_TAG_CONTENT + _nodeLevel) {
157                             addViolation(MSG_PARAMETER_WITHOUT_DESCRIPTION, tgt.start, tgt.end);
158                         }
159                         else {
160                             tr.Ace.log("function", _function);
161                         }
162                     }
163 
164                     String   tgtStr = tgt.text;
165                     int    index  = getMatchingParameter(tgtStr);
166                     
167                     tr.Ace.log("matching parameter: " + index);
168 
169                     if (index == -1) {
170                         index = getClosestMatchingParameter(tgtStr);
171                         tr.Ace.log("closest matching parameter: " + index);
172                         tr.Ace.log("parameter index: " + parameterIndex);
173 
174                         SimpleNodeUtil.dump(_parameterList, "pppp");
175 
176                         if (index == -1) {
177                             String   paramType = ParameterUtil.getParameterType(_parameterList, parameterIndex);
178                             tr.Ace.log("paramType: " + paramType + "; tgtStr: " + tgtStr);
179 
180                             if (tgtStr.equals(paramType)) {
181                                 addViolation(MSG_PARAMETER_TYPE_USED, tgt.start, tgt.end);
182                                 addDocumentedParameter(parameterIndex, tgt.start, tgt.end);
183                             }
184                             else {
185                                 addViolation(MSG_PARAMETER_NOT_IN_CODE, tgt.start, tgt.end);
186                             }
187                         }
188                         else {
189                             addViolation(MSG_PARAMETER_MISSPELLED, tgt.start, tgt.end);
190                             addDocumentedParameter(index, tgt.start, tgt.end);
191                         }
192                     }
193                     else {
194                         addDocumentedParameter(index, tgt.start, tgt.end);
195                     }   
196                 }
197                 ++parameterIndex;
198             }
199         }
200 
201         tr.Ace.log("documentedParameters", _documentedParameters);
202 
203         if (_parameterList == null) {
204             tr.Ace.log("no parameters");
205         }
206         else if (isCheckable(_function, CHKLVL_PARAM_DOC_EXISTS)) {
207             reportUndocumentedParameters();
208         }
209         else {
210             tr.Ace.log("function", _function);
211         }
212     }
213 
214     protected void addDocumentedParameter(int index, Location start, Location end)
215     {
216         if (_documentedParameters.size() > 0 && ((Integer  )_documentedParameters.get(_documentedParameters.size() - 1)).intValue() > index) {
217             addViolation(MSG_PARAMETER_NOT_IN_CODE_ORDER, start, end);
218         }
219         
220         Integer   i = new Integer  (index);
221         if (_documentedParameters.contains(i)) {
222             addViolation(MSG_PARAMETER_REPEATED, start, end);
223         }
224         else {
225             _documentedParameters.add(i);
226         }
227     }
228     
229     protected void reportUndocumentedParameters()
230     {
231         ASTFormalParameter[] params = ParameterUtil.getParameters(_parameterList);
232         
233         for (int ni = 0; ni < params.length; ++ni) {
234             tr.Ace.log("parameter", params[ni]);
235             ASTFormalParameter param = params[ni];
236             if (!_documentedParameters.contains(new Integer  (ni))) {
237                 Token nameTk = ParameterUtil.getParameterName(param);
238                 addViolation(MSG_PARAMETER_NOT_DOCUMENTED, nameTk);
239             }
240         }
241     }
242 
243     /**
244      * Returns the first param in the list whose name matches the given string.
245      */
246     protected int getMatchingParameter(String   str)
247     {
248         ASTFormalParameter[] params = ParameterUtil.getParameters(_parameterList);
249         
250         for (int ni = 0; ni < params.length; ++ni) {
251             tr.Ace.log("parameter", params[ni]);
252             ASTFormalParameter param = params[ni];
253             Token nameTk = ParameterUtil.getParameterName(param);
254             if (nameTk.image.equals(str)) {
255                 return ni;
256             }
257         }
258 
259         return -1;
260     }
261 
262     /**
263      * Returns the first param in the list whose name most closely matches the
264      * given string.
265      */
266     protected int getClosestMatchingParameter(String   str)
267     {
268         if (_parameterList == null) {
269             return -1;
270         }
271         else {
272             SpellChecker         spellChecker = new SpellChecker();
273             int                  bestDistance = -1;
274             int                  bestIndex    = -1;
275             ASTFormalParameter[] params       = ParameterUtil.getParameters(_parameterList);
276         
277             for (int ni = 0; ni < params.length; ++ni) {
278                 tr.Ace.log("parameter", params[ni]);
279                 ASTFormalParameter param  = params[ni];
280                 Token              nameTk = ParameterUtil.getParameterName(param);
281                 int                dist   = spellChecker.editDistance(nameTk.image, str);
282 
283                 // tr.Ace.log("edit distance(param: '" + paramTkn.image + "', str: '" + str + "'): " + dist);
284             
285                 if (dist >= 0 && dist <= SpellChecker.DEFAULT_MAX_DISTANCE && (bestDistance == -1 || dist < bestDistance)) {
286                     bestDistance = dist;
287                     bestIndex    = ni;
288                 }
289             }
290 
291             return bestIndex;
292         }
293     }
294 
295 }
296
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Free Books Free Magazines
Popular Tags