Index: src/epydoc/objdoc.py =================================================================== RCS file: /cvsroot/epydoc/epydoc/src/epydoc/objdoc.py,v retrieving revision 1.86 diff -u -4 -r1.86 objdoc.py --- src/epydoc/objdoc.py 7 Apr 2004 03:30:07 -0000 1.86 +++ src/epydoc/objdoc.py 21 Apr 2004 23:10:20 -0000 @@ -1155,8 +1155,13 @@ # If mod is a package, then it will contain a __path__ if mod.__dict__.has_key('__path__'): self._modules = [] else: self._modules = None + if mod.__dict__.has_key('__docfilter__'): + self._docfilter = mod.__docfilter__ + else: + self._docfilter = None + # Handle functions, classes, and variables. self._classes = [] self._functions = [] self._variables = [] @@ -1169,12 +1174,16 @@ # Don't do anything for these special variables: if field in ('__builtins__', '__doc__', '__all__', '__file__', '__path__', '__name__', - '__extra_epydoc_fields__', '__docformat__'): + '__extra_epydoc_fields__', '__docformat__', + '__docfilter__'): continue # Don't do anything if we can't get a UID. if vuid is None: continue + # Don't do anything if the filter rejects field + if self._docfilter is not None and not self._docfilter(field): + continue # Record imported modules. if vuid.is_module(): self._imported_modules.append(Link(field, vuid)) @@ -2195,22 +2204,12 @@ self._raises = [] self._overrides = None self._matches_override = 0 - docstring = _getdoc(func) # Initialize the signature if uid.is_method(): func = func.im_func - if type(func) is types.FunctionType: - self._init_signature(func) - elif uid.is_routine(): - # If there's a builtin signature, then just parse it; - # don't include it in the description. - if self._init_builtin_signature(func): - if '\n' in docstring: - docstring = docstring.split('\n', 1)[1] - else: - raise TypeError("Can't document %s" % func) + docstring = self._init_signature(func) # These are used to keep track of params & keyword arguments # while processing fields; we can delete them when we're done. self._tmp_param = {} @@ -2256,43 +2255,49 @@ # The end marker r'\s*(\n|\s+--\s+|$|\.\s|\.\n)') - def _init_builtin_signature(self, func): + def _init_signature(self, func): """ - Construct the signature for a builtin function or method from - its docstring. If the docstring uses the standard convention - of including a signature in the first line of the docstring - (and formats that signature according to standard - conventions), then it will be used to extract a signature. - Otherwise, the signature will be set to a single varargs - variable named C{"..."}. + Construct the signature for a function or method from its + docstring. If the docstring uses the standard convention of + including a signature in the first line of the docstring (and + formats that signature according to standard conventions), + then it will be used to extract a signature. Otherwise, + introspection will be used to get the details of the + parameters and etc. If that is not possible then the + signature will be set to a single varargs variable named C{"..."}. @rtype: C{None} """ + docstring = _getdoc(func) self._params = [] self._kwarg_param = None self._vararg_param = None self._return = Param('return') - m = FuncDoc._SIGNATURE_RE.match(_getdoc(func) or '') + # first check if there is a matching signature at the begining + # of the docstring + m = FuncDoc._SIGNATURE_RE.match(docstring or '') if m and m.group('func') == func.__name__: + params = m.group('params') rtype = m.group('return') selfparam = m.group('self') - - if selfparam and not rtype: - self._vararg_param = Param('...') - return 0 + + # i don't think this is an error??? + #if selfparam and not rtype and not self._introspect_signature(func): + # self._vararg_param = Param('...') + # return docstring # Extract the parameters from the signature. if params: # Figure out which parameters are optional. while '[' in params or ']' in params: m2 = re.match(r'(.*)\[([^\[\]]+)\](.*)', params) - if not m2: + if not m2 and not self._introspect_signature(func): self._vararg_param = Param('...') - return 0 + return docstring (start, mid, end) = m2.groups() mid = re.sub(r'((,|^)\s*[\w\-\.]+)', r'\1=...', mid) params = start+mid+end @@ -2318,27 +2323,36 @@ # Add the self parameter, if it was specified. if selfparam: self._params.insert(0, Param(selfparam)) - # We found a signature. - return 1 - - else: - # We couldn't parse the signature. + # trim the signature out of the docstring + docstring = docstring[m.end():] + + # if no match then use introspection if possible + elif not self._introspect_signature(func): + # otherwise just set a generic value self._vararg_param = Param('...') - return 0 + #raise TypeError("Can't document %s" % func) - def _init_signature(self, func): - # Get the function's signature - (args, vararg, kwarg, defaults) = inspect.getargspec(func) + return docstring - # Construct argument/return Variables. - self._params = self._params_to_vars(args, defaults) - if vararg: self._vararg_param = Param(vararg) - else: self._vararg_param = None - if kwarg: self._kwarg_param = Param(kwarg) - else: self._kwarg_param = None - self._return = Param('return') + + def _introspect_signature(self, func): + if type(func) is types.FunctionType: + # Get the function's signature + (args, vararg, kwarg, defaults) = inspect.getargspec(func) + + # Construct argument/return Variables. + self._params = self._params_to_vars(args, defaults) + if vararg: self._vararg_param = Param(vararg) + else: self._vararg_param = None + if kwarg: self._kwarg_param = Param(kwarg) + else: self._kwarg_param = None + self._return = Param('return') + return True + else: + return False + def _params_to_vars(self, params, defaults): vars = [] if defaults == None: defaults = []