#
# objdoc: epydoc documentation completeness checker
# Edward Loper
#
# Created [01/30/01 05:18 PM]
# $Id: checker.py 1366 2006-09-07 15:54:59Z edloper $
#
"""
Documentation completeness checker. This module defines a single
class, C{DocChecker}, which can be used to check the that specified
classes of objects are documented.
"""
__docformat__ = 'epytext en'
##################################################
## Imports
##################################################
import re, sys, os.path, string
from xml.dom.minidom import Text
from epydoc.apidoc import *
# The following methods may be undocumented:
_NO_DOCS = ['__hash__', '__repr__', '__str__', '__cmp__']
# The following methods never need descriptions, authors, or
# versions:
_NO_BASIC = ['__hash__', '__repr__', '__str__', '__cmp__']
# The following methods never need return value descriptions.
_NO_RETURN = ['__init__', '__hash__', '__repr__', '__str__', '__cmp__']
# The following methods don't need parameters documented:
_NO_PARAM = ['__cmp__']
class DocChecker:
"""
Documentation completeness checker. C{DocChecker} can be used to
check that specified classes of objects are documented. To check
the documentation for a group of objects, you should create a
C{DocChecker} from a L{DocIndex<apidoc.DocIndex>} that documents
those objects; and then use the L{check} method to run specified
checks on the objects' documentation.
What checks are run, and what objects they are run on, are
specified by the constants defined by C{DocChecker}. These
constants are divided into three groups.
- Type specifiers indicate what type of objects should be
checked: L{MODULE}; L{CLASS}; L{FUNC}; L{VAR}; L{IVAR};
L{CVAR}; L{PARAM}; and L{RETURN}.
- Public/private specifiers indicate whether public or private
objects should be checked: L{PRIVATE}.
- Check specifiers indicate what checks should be run on the
objects: L{TYPE}; L{DESCR}; L{AUTHOR};
and L{VERSION}.
The L{check} method is used to perform a check on the
documentation. Its parameter is formed by or-ing together at
least one value from each specifier group:
>>> checker.check(DocChecker.MODULE | DocChecker.DESCR)
To specify multiple values from a single group, simply or their
values together:
>>> checker.check(DocChecker.MODULE | DocChecker.CLASS |
... DocChecker.FUNC )
@group Types: MODULE, CLASS, FUNC, VAR, IVAR, CVAR, PARAM,
RETURN, ALL_T
@type MODULE: C{int}
@cvar MODULE: Type specifier that indicates that the documentation
of modules should be checked.
@type CLASS: C{int}
@cvar CLASS: Type specifier that indicates that the documentation
of classes should be checked.
@type FUNC: C{int}
@cvar FUNC: Type specifier that indicates that the documentation
of functions should be checked.
@type VAR: C{int}
@cvar VAR: Type specifier that indicates that the documentation
of module variables should be checked.
@type IVAR: C{int}
@cvar IVAR: Type specifier that indicates that the documentation
of instance variables should be checked.
@type CVAR: C{int}
@cvar CVAR: Type specifier that indicates that the documentation
of class variables should be checked.
@type PARAM: C{int}
@cvar PARAM: Type specifier that indicates that the documentation
of function and method parameters should be checked.
@type RETURN: C{int}
@cvar RETURN: Type specifier that indicates that the documentation
of return values should be checked.
@type ALL_T: C{int}
@cvar ALL_T: Type specifier that indicates that the documentation
of all objects should be checked.
@group Checks: TYPE, AUTHOR, VERSION, DESCR, ALL_C
@type TYPE: C{int}
@cvar TYPE: Check specifier that indicates that every variable and
parameter should have a C{@type} field.
@type AUTHOR: C{int}
@cvar AUTHOR: Check specifier that indicates that every object
should have an C{author} field.
@type VERSION: C{int}
@cvar VERSION: Check specifier that indicates that every object
should have a C{version} field.
@type DESCR: C{int}
@cvar DESCR: Check specifier that indicates that every object
should have a description.
@type ALL_C: C{int}
@cvar ALL_C: Check specifier that indicates that all checks
should be run.
@group Publicity: PRIVATE
@type PRIVATE: C{int}
@cvar PRIVATE: Specifier that indicates that private objects should
be checked.
"""
# Types
MODULE = 1
CLASS = 2
FUNC = 4
VAR = 8
#IVAR = 16
#CVAR = 32
PARAM = 64
RETURN = 128
PROPERTY = 256
ALL_T = 1+2+4+8+16+32+64+128+256
# Checks
TYPE = 256
AUTHOR = 1024
VERSION = 2048
DESCR = 4096
ALL_C = 256+512+1024+2048+4096
# Private/public
PRIVATE = 16384
ALL = ALL_T + ALL_C + PRIVATE
def __init__(self, docindex):
"""
Create a new C{DocChecker} that can be used to run checks on
the documentation of the objects documented by C{docindex}
@param docindex: A documentation map containing the
documentation for the objects to be checked.
@type docindex: L{Docindex<apidoc.DocIndex>}
"""
self._docindex = docindex
# Initialize instance variables
self._checks = 0
self._last_warn = None
self._out = sys.stdout
self._num_warnings = 0
def check(self, *check_sets):
"""
Run the specified checks on the documentation of the objects
contained by this C{DocChecker}'s C{DocIndex}. Any errors found
are printed to standard out.
@param check_sets: The checks that should be run on the
documentation. This value is constructed by or-ing
together the specifiers that indicate which objects should
be checked, and which checks should be run. See the
L{module description<checker>} for more information.
If no checks are specified, then a default set of checks
will be run.
@type check_sets: C{int}
@return: True if no problems were found.
@rtype: C{boolean}
"""
if not check_sets:
check_sets = (DocChecker.MODULE | DocChecker.CLASS |
DocChecker.FUNC | DocChecker.VAR |
DocChecker.DESCR,)
self._warnings = {}
log.start_progress('Checking docs')
for j, checks in enumerate(check_sets):
self._check(checks)
log.end_progress()
for (warning, docs) in self._warnings.items():
docs = sorted(docs)
docnames = '\n'.join([' - %s' % self._name(d) for d in docs])
log.warning('%s:\n%s' % (warning, docnames))
def _check(self, checks):
self._checks = checks
# Get the list of objects to check.
valdocs = sorted(self._docindex.reachable_valdocs(
imports=False, packages=False, bases=False, submodules=False,
subclasses=False, private = (checks & DocChecker.PRIVATE)))
docs = set()
for d in valdocs:
if not isinstance(d, GenericValueDoc): docs.add(d)
for doc in valdocs:
if isinstance(doc, NamespaceDoc):
for d in doc.variables.values():
if isinstance(d.value, GenericValueDoc): docs.add(d)
for i, doc in enumerate(sorted(docs)):
if isinstance(doc, ModuleDoc):
self._check_module(doc)
elif isinstance(doc, ClassDoc):
self._check_class(doc)
elif isinstance(doc, RoutineDoc):
self._check_func(doc)
elif isinstance(doc, PropertyDoc):
self._check_property(doc)
elif isinstance(doc, VariableDoc):
self._check_var(doc)
else:
log.error("Don't know how to check %r" % doc)
def _name(self, doc):
name = str(doc.canonical_name)
if isinstance(doc, RoutineDoc): name += '()'
return name
def _check_basic(self, doc):
"""
Check the description, author, version, and see-also fields of
C{doc}. This is used as a helper function by L{_check_module},
L{_check_class}, and L{_check_func}.
@param doc: The documentation that should be checked.
@type doc: L{APIDoc}
@rtype: C{None}
"""
if ((self._checks & DocChecker.DESCR) and
(doc.descr in (None, UNKNOWN))):
if doc.docstring in (None, UNKNOWN):
self.warning('Undocumented', doc)
else:
self.warning('No description', doc)
if self._checks & DocChecker.AUTHOR:
for tag, arg, descr in doc.metadata:
if 'author' == tag: break
else:
self.warning('No authors', doc)
if self._checks & DocChecker.VERSION:
for tag, arg, descr in doc.metadata:
if 'version' == tag: break
else:
self.warning('No version', doc)
def _check_module(self, doc):
"""
Run checks on the module whose APIDoc is C{doc}.
@param doc: The APIDoc of the module to check.
@type doc: L{APIDoc}
@rtype: C{None}
"""
if self._checks & DocChecker.MODULE:
self._check_basic(doc)
def _check_class(self, doc):
"""
Run checks on the class whose APIDoc is C{doc}.
@param doc: The APIDoc of the class to check.
@type doc: L{APIDoc}
@rtype: C{None}
"""
if self._checks & DocChecker.CLASS:
self._check_basic(doc)
def _check_property(self, doc):
if self._checks & DocChecker.PROPERTY:
self._check_basic(doc)
def _check_var(self, doc):
"""
Run checks on the variable whose documentation is C{var} and
whose name is C{name}.
@param doc: The documentation for the variable to check.
@type doc: L{APIDoc}
@rtype: C{None}
"""
if self._checks & DocChecker.VAR:
if (self._checks & (DocChecker.DESCR|DocChecker.TYPE) and
doc.descr in (None, UNKNOWN) and
doc.type_descr in (None, UNKNOWN) and
doc.docstring in (None, UNKNOWN)):
self.warning('Undocumented', doc)
else:
if (self._checks & DocChecker.DESCR and
doc.descr in (None, UNKNOWN)):
self.warning('No description', doc)
if (self._checks & DocChecker.TYPE and
doc.type_descr in (None, UNKNOWN)):
self.warning('No type information', doc)
def _check_func(self, doc):
"""
Run checks on the function whose APIDoc is C{doc}.
@param doc: The APIDoc of the function to check.
@type doc: L{APIDoc}
@rtype: C{None}
"""
name = doc.canonical_name
if (self._checks & DocChecker.FUNC and
doc.docstring in (None, UNKNOWN) and
doc.canonical_name[-1] not in _NO_DOCS):
self.warning('Undocumented', doc)
return
if (self._checks & DocChecker.FUNC and
doc.canonical_name[-1] not in _NO_BASIC):
self._check_basic(doc)
if (self._checks & DocChecker.RETURN and
doc.canonical_name[-1] not in _NO_RETURN):
if (doc.return_type in (None, UNKNOWN) and
doc.return_descr in (None, UNKNOWN)):
self.warning('No return descr', doc)
if (self._checks & DocChecker.PARAM and
doc.canonical_name[-1] not in _NO_PARAM):
if doc.arg_descrs in (None, UNKNOWN):
self.warning('No argument info', doc)
else:
args_with_descr = []
for arg, descr in doc.arg_descrs:
if isinstance(arg, basestring):
args_with_descr.append(arg)
else:
args_with_descr += arg
for posarg in doc.posargs:
if (self._checks & DocChecker.DESCR and
posarg not in args_with_descr):
self.warning('Argument(s) not described', doc)
if (self._checks & DocChecker.TYPE and
posarg not in doc.arg_types):
self.warning('Argument type(s) not described', doc)
def warning(self, msg, doc):
self._warnings.setdefault(msg,set()).add(doc)
|