Source Code for Module epydoc.checker

  1  # 
  2  # objdoc: epydoc documentation completeness checker 
  3  # Edward Loper 
  4  # 
  5  # Created [01/30/01 05:18 PM] 
  6  # $Id: checker.py 1366 2006-09-07 15:54:59Z edloper $ 
  7  # 
  8   
  9  """ 
 10  Documentation completeness checker.  This module defines a single 
 11  class, C{DocChecker}, which can be used to check the that specified 
 12  classes of objects are documented. 
 13  """ 
 14  __docformat__ = 'epytext en' 
 15   
 16  ################################################## 
 17  ## Imports 
 18  ################################################## 
 19   
 20  import re, sys, os.path, string 
 21  from xml.dom.minidom import Text as _Text 
 22  from epydoc.apidoc import * 
 23   
 24  # The following methods may be undocumented: 
 25  _NO_DOCS = ['__hash__', '__repr__', '__str__', '__cmp__'] 
 26   
 27  # The following methods never need descriptions, authors, or 
 28  # versions: 
 29  _NO_BASIC = ['__hash__', '__repr__', '__str__', '__cmp__'] 
 30   
 31  # The following methods never need return value descriptions. 
 32  _NO_RETURN = ['__init__', '__hash__', '__repr__', '__str__', '__cmp__'] 
 33   
 34  # The following methods don't need parameters documented: 
 35  _NO_PARAM = ['__cmp__'] 
 36   
 37 -class DocChecker: 
 38      """ 
 39      Documentation completeness checker.  C{DocChecker} can be used to 
 40      check that specified classes of objects are documented.  To check 
 41      the documentation for a group of objects, you should create a 
 42      C{DocChecker} from a L{DocIndex<apidoc.DocIndex>} that documents 
 43      those objects; and then use the L{check} method to run specified 
 44      checks on the objects' documentation. 
 45   
 46      What checks are run, and what objects they are run on, are 
 47      specified by the constants defined by C{DocChecker}.  These 
 48      constants are divided into three groups.   
 49   
 50        - Type specifiers indicate what type of objects should be 
 51          checked: L{MODULE}; L{CLASS}; L{FUNC}; L{VAR}; L{IVAR}; 
 52          L{CVAR}; L{PARAM}; and L{RETURN}. 
 53        - Public/private specifiers indicate whether public or private 
 54          objects should be checked: L{PRIVATE}. 
 55        - Check specifiers indicate what checks should be run on the 
 56          objects: L{TYPE}; L{DESCR}; L{AUTHOR}; 
 57          and L{VERSION}. 
 58   
 59      The L{check} method is used to perform a check on the 
 60      documentation.  Its parameter is formed by or-ing together at 
 61      least one value from each specifier group: 
 62   
 63          >>> checker.check(DocChecker.MODULE | DocChecker.DESCR) 
 64           
 65      To specify multiple values from a single group, simply or their 
 66      values together: 
 67       
 68          >>> checker.check(DocChecker.MODULE | DocChecker.CLASS | 
 69          ...               DocChecker.FUNC ) 
 70   
 71      @group Types: MODULE, CLASS, FUNC, VAR, IVAR, CVAR, PARAM, 
 72          RETURN, ALL_T 
 73      @type MODULE: C{int} 
 74      @cvar MODULE: Type specifier that indicates that the documentation 
 75          of modules should be checked. 
 76      @type CLASS: C{int} 
 77      @cvar CLASS: Type specifier that indicates that the documentation 
 78          of classes should be checked. 
 79      @type FUNC: C{int} 
 80      @cvar FUNC: Type specifier that indicates that the documentation 
 81          of functions should be checked. 
 82      @type VAR: C{int} 
 83      @cvar VAR: Type specifier that indicates that the documentation 
 84          of module variables should be checked. 
 85      @type IVAR: C{int} 
 86      @cvar IVAR: Type specifier that indicates that the documentation 
 87          of instance variables should be checked. 
 88      @type CVAR: C{int} 
 89      @cvar CVAR: Type specifier that indicates that the documentation 
 90          of class variables should be checked. 
 91      @type PARAM: C{int} 
 92      @cvar PARAM: Type specifier that indicates that the documentation 
 93          of function and method parameters should be checked. 
 94      @type RETURN: C{int} 
 95      @cvar RETURN: Type specifier that indicates that the documentation 
 96          of return values should be checked. 
 97      @type ALL_T: C{int} 
 98      @cvar ALL_T: Type specifier that indicates that the documentation 
 99          of all objects should be checked. 
100   
101      @group Checks: TYPE, AUTHOR, VERSION, DESCR, ALL_C 
102      @type TYPE: C{int} 
103      @cvar TYPE: Check specifier that indicates that every variable and 
104          parameter should have a C{@type} field. 
105      @type AUTHOR: C{int} 
106      @cvar AUTHOR: Check specifier that indicates that every object 
107          should have an C{author} field. 
108      @type VERSION: C{int} 
109      @cvar VERSION: Check specifier that indicates that every object 
110          should have a C{version} field. 
111      @type DESCR: C{int} 
112      @cvar DESCR: Check specifier that indicates that every object 
113          should have a description.   
114      @type ALL_C: C{int} 
115      @cvar ALL_C: Check specifier that indicates that  all checks 
116          should be run. 
117   
118      @group Publicity: PRIVATE 
119      @type PRIVATE: C{int} 
120      @cvar PRIVATE: Specifier that indicates that private objects should 
121          be checked. 
122      """ 
123      # Types 
124      MODULE = 1 
125      CLASS  = 2 
126      FUNC   = 4 
127      VAR    = 8 
128      #IVAR   = 16 
129      #CVAR   = 32 
130      PARAM  = 64 
131      RETURN = 128 
132      PROPERTY = 256 
133      ALL_T  = 1+2+4+8+16+32+64+128+256 
134   
135      # Checks 
136      TYPE = 256 
137      AUTHOR = 1024 
138      VERSION = 2048 
139      DESCR = 4096 
140      ALL_C = 256+512+1024+2048+4096 
141   
142      # Private/public 
143      PRIVATE = 16384 
144   
145      ALL = ALL_T + ALL_C + PRIVATE 
146   
147 -    def __init__(self, docindex): 
148          """ 
149          Create a new C{DocChecker} that can be used to run checks on 
150          the documentation of the objects documented by C{docindex} 
151   
152          @param docindex: A documentation map containing the 
153              documentation for the objects to be checked. 
154          @type docindex: L{Docindex<apidoc.DocIndex>} 
155          """ 
156          self._docindex = docindex 
157   
158          # Initialize instance variables 
159          self._checks = 0 
160          self._last_warn = None 
161          self._out = sys.stdout 
162          self._num_warnings = 0 
163   
164 -    def check(self, *check_sets): 
165          """ 
166          Run the specified checks on the documentation of the objects 
167          contained by this C{DocChecker}'s C{DocIndex}.  Any errors found 
168          are printed to standard out. 
169   
170          @param check_sets: The checks that should be run on the 
171              documentation.  This value is constructed by or-ing 
172              together the specifiers that indicate which objects should 
173              be checked, and which checks should be run.  See the 
174              L{module description<checker>} for more information. 
175              If no checks are specified, then a default set of checks 
176              will be run. 
177          @type check_sets: C{int} 
178          @return: True if no problems were found. 
179          @rtype: C{boolean} 
180          """ 
181          if not check_sets: 
182              check_sets = (DocChecker.MODULE | DocChecker.CLASS | 
183                            DocChecker.FUNC | DocChecker.VAR |  
184                            DocChecker.DESCR,) 
185               
186          self._warnings = {} 
187          log.start_progress('Checking docs') 
188          for j, checks in enumerate(check_sets): 
189              self._check(checks) 
190          log.end_progress() 
191   
192          for (warning, docs) in self._warnings.items(): 
193              docs = sorted(docs) 
194              docnames = '\n'.join(['  - %s' % self._name(d) for d in docs]) 
195              log.warning('%s:\n%s' % (warning, docnames)) 
196   
197 -    def _check(self, checks): 
198          self._checks = checks 
199           
200          # Get the list of objects to check. 
201          valdocs = sorted(self._docindex.reachable_valdocs( 
202              imports=False, packages=False, bases=False, submodules=False,  
203              subclasses=False, private = (checks & DocChecker.PRIVATE))) 
204          docs = set() 
205          for d in valdocs: 
206              if not isinstance(d, GenericValueDoc): docs.add(d) 
207          for doc in valdocs: 
208              if isinstance(doc, NamespaceDoc): 
209                  for d in doc.variables.values(): 
210                      if isinstance(d.value, GenericValueDoc): docs.add(d) 
211   
212          for i, doc in enumerate(sorted(docs)): 
213              if isinstance(doc, ModuleDoc): 
214                  self._check_module(doc) 
215              elif isinstance(doc, ClassDoc): 
216                  self._check_class(doc) 
217              elif isinstance(doc, RoutineDoc): 
218                  self._check_func(doc) 
219              elif isinstance(doc, PropertyDoc): 
220                  self._check_property(doc) 
221              elif isinstance(doc, VariableDoc): 
222                  self._check_var(doc) 
223              else: 
224                  log.error("Don't know how to check %r" % doc) 
225   
226 -    def _name(self, doc): 
227          name = str(doc.canonical_name) 
228          if isinstance(doc, RoutineDoc): name += '()' 
229          return name 
230   
231 -    def _check_basic(self, doc): 
232          """ 
233          Check the description, author, version, and see-also fields of 
234          C{doc}.  This is used as a helper function by L{_check_module}, 
235          L{_check_class}, and L{_check_func}. 
236   
237          @param doc: The documentation that should be checked. 
238          @type doc: L{APIDoc} 
239          @rtype: C{None} 
240          """ 
241          if ((self._checks & DocChecker.DESCR) and 
242              (doc.descr in (None, UNKNOWN))): 
243              if doc.docstring in (None, UNKNOWN): 
244                  self.warning('Undocumented', doc) 
245              else: 
246                  self.warning('No description', doc) 
247          if self._checks & DocChecker.AUTHOR: 
248              for tag, arg, descr in doc.metadata: 
249                  if 'author' == tag: break 
250              else: 
251                  self.warning('No authors', doc) 
252          if self._checks & DocChecker.VERSION: 
253              for tag, arg, descr in doc.metadata: 
254                  if 'version' == tag: break 
255              else: 
256                  self.warning('No version', doc) 
257               
258 -    def _check_module(self, doc): 
259          """ 
260          Run checks on the module whose APIDoc is C{doc}. 
261           
262          @param doc: The APIDoc of the module to check. 
263          @type doc: L{APIDoc} 
264          @rtype: C{None} 
265          """ 
266          if self._checks & DocChecker.MODULE: 
267              self._check_basic(doc) 
268           
269 -    def _check_class(self, doc): 
270          """ 
271          Run checks on the class whose APIDoc is C{doc}. 
272           
273          @param doc: The APIDoc of the class to check. 
274          @type doc: L{APIDoc} 
275          @rtype: C{None} 
276          """ 
277          if self._checks & DocChecker.CLASS: 
278              self._check_basic(doc) 
279   
280 -    def _check_property(self, doc): 
281          if self._checks & DocChecker.PROPERTY: 
282              self._check_basic(doc) 
283   
284 -    def _check_var(self, doc): 
285          """ 
286          Run checks on the variable whose documentation is C{var} and 
287          whose name is C{name}. 
288           
289          @param doc: The documentation for the variable to check. 
290          @type doc: L{APIDoc} 
291          @rtype: C{None} 
292          """ 
293          if self._checks & DocChecker.VAR: 
294              if (self._checks & (DocChecker.DESCR|DocChecker.TYPE) and 
295                  doc.descr in (None, UNKNOWN) and 
296                  doc.type_descr in (None, UNKNOWN) and 
297                  doc.docstring in (None, UNKNOWN)): 
298                  self.warning('Undocumented', doc) 
299              else: 
300                  if (self._checks & DocChecker.DESCR and 
301                      doc.descr in (None, UNKNOWN)): 
302                      self.warning('No description', doc) 
303                  if (self._checks & DocChecker.TYPE and 
304                      doc.type_descr in (None, UNKNOWN)): 
305                      self.warning('No type information', doc) 
306               
307 -    def _check_func(self, doc): 
308          """ 
309          Run checks on the function whose APIDoc is C{doc}. 
310           
311          @param doc: The APIDoc of the function to check. 
312          @type doc: L{APIDoc} 
313          @rtype: C{None} 
314          """ 
315          name = doc.canonical_name 
316          if (self._checks & DocChecker.FUNC and 
317              doc.docstring in (None, UNKNOWN) and 
318              doc.canonical_name[-1] not in _NO_DOCS): 
319              self.warning('Undocumented', doc) 
320              return 
321          if (self._checks & DocChecker.FUNC and 
322              doc.canonical_name[-1] not in _NO_BASIC): 
323                  self._check_basic(doc) 
324          if (self._checks & DocChecker.RETURN and 
325              doc.canonical_name[-1] not in _NO_RETURN): 
326              if (doc.return_type in (None, UNKNOWN) and 
327                  doc.return_descr in (None, UNKNOWN)): 
328                  self.warning('No return descr', doc) 
329          if (self._checks & DocChecker.PARAM and 
330              doc.canonical_name[-1] not in _NO_PARAM): 
331              if doc.arg_descrs in (None, UNKNOWN): 
332                  self.warning('No argument info', doc) 
333              else: 
334                  args_with_descr = [] 
335                  for arg, descr in doc.arg_descrs: 
336                      if isinstance(arg, basestring): 
337                          args_with_descr.append(arg) 
338                      else: 
339                          args_with_descr += arg 
340                  for posarg in doc.posargs: 
341                      if (self._checks & DocChecker.DESCR and 
342                          posarg not in args_with_descr): 
343                          self.warning('Argument(s) not described', doc) 
344                      if (self._checks & DocChecker.TYPE and 
345                          posarg not in doc.arg_types): 
346                          self.warning('Argument type(s) not described', doc) 
347   
348 -    def warning(self, msg, doc): 
349          self._warnings.setdefault(msg,set()).add(doc) 
350