lemon.external.epydoc.objdoc.FuncDoc

Package lemon :: Package external :: Package epydoc :: Module objdoc :: Class FuncDoc

[show private | hide private]

Class FuncDoc

ObjDoc --+
         |
        FuncDoc

The documentation for a function. This documentation consists of standard pieces of documentation (as defined in ObjDoc), and the following function-specific pieces of documentation:

parameters: A list of the function's positional parameters.
vararg: The function's vararg parameter, or None.
kwarg: The function's keyword parameter, or None.
returns: The function's return value.
raises: A list of exceptions that may be raised by the function.
overrides: The method that this method overrides.

Method Summary
	`__init__(self, uid, verbosity)`
	`__repr__(self)`
`list` of `Var`	`keywords(self)` Return the keyword parameters for the function/method documented by this `FuncDoc`.
	`_process_field(self, tag, arg, descr, warnings)` Process a field from this object's docstring.
Accessors
`Var` or `None`	`kwarg(self)` Return the keyword parameter for the function/method documented by this `FuncDoc`, or `None` if it has no keyword parameter.
`boolean`	`matches_override(self)` Return true if the method documented by this `FuncDoc` overrides another method, and its signature matches the signature of the overridden method.
`Link` or `None`	`overrides(self)` Return the method overridden by the method documented by this `FuncDoc`; or `None` if the method documented by this `FuncDoc` does not override any method, or if this `FuncDoc` documents a function.
`list` of `Var`	`parameter_list(self)` Return a (flat) list of all parameters for the function/method documented by this `FuncDoc`.
`list` of `Var`	`parameters(self)` Return the positional parameters for the function/method documented by this `FuncDoc`.
`list` of `Raise`	`raises(self)` Return a list of exceptions that may be raised by the function/method documented by this `FuncDoc`.
`Var` or `None`	`returns(self)` Return the return value for the function/method documented by this `FuncDoc`, or `None` if it has no return value.
`Var` or `None`	`vararg(self)` Return the vararg parameter for the function/method documented by this `FuncDoc`, or `None` if it has no vararg parameter.
Inheritance
	`find_override(self, bases)` Find the method that this method overrides.
Signature Parsing
`None`	`_init_builtin_signature(self, func)` Construct the signature for a builtin function or method from its docstring.
	`_init_signature(self, func)`
	`_params_to_vars(self, params, defaults)`
`boolean`	`_signature_match(self, basespec, childspec)` Return true if the signature of `childfunc` matches the signature of `basefunc` well enough that we should inherit its documentation.
Inherited from ObjDoc
`list` of `(string, elt)`	`by_group(self, elts)` Divide a set of elements into groups.
`boolean`	`defines_groups(self)` Return true if the object documented by this `ObjDoc` defines any groups.
`markup.ParsedDocstring`	`descr(self)` Return a description of the object documented by this `ObjDoc`.
`list` of `markup.ParsedDocstring`	`field_values(self, field)` Return a list of the values that are specified for the given field in the docstring of the object documented by this `ObjDoc`.
`list` of `DocField`	`fields(self)` Return a list of the fields that are given values in the docstring of the object documented by this `ObjDoc`.
`list` of `string`	`groups(self)` Return a list of the names of the groups that are defined for the object documented by this `ObjDoc`.
`boolean`	`has_docstring(self)` Return true if the object documented by this `ObjDoc` has a docstring.
`list` of `string`	`sortorder(self)` Return a list specifying the sort order that should be used for the object's children.
`markup.ParsedDocstring`	`summary(self)` Return a summary of the description of the object documented by this `ObjDoc`.
`UID`	`uid(self)` Return the UID of the object documented by this `ObjDoc`.
`None`	`_print_errors(self, stream)` Print any errors that were encountered while constructing this `ObjDoc` to `stream`.
	`_sort(self, items)` Return a copy of the list `items`, sorted first by `sortorder`, and then by name.

Instance Variable Summary
`Var`	`_kwarg_param`: This function's keyword parameter, or `None` if it has none.
`list` of `Var`	`_params`: A list of this function's normal parameters.
`list` of `Raise`	`_raises`: The exceptions that may be raised by this function.
`Var`	`_return`: This function's return value.
`Var`	`_vararg_param`: This function's vararg parameter, or `None` if it has none.
Inherited from ObjDoc
`markup.ParsedDocstring`	`_descr`: The object's description, encoded as epytext.
	`_field_warnings`: Warnings generated when processing the object's docstring's fields.
`dictionary` from `DocField` to `list` of `markup.ParsedDocstring`	`_fields`: Documentation fields that were extracted from the object's docstring.
	`_misc_warnings`: Warnings that are not related to the object's docstring.
	`_parse_errors`: Errors generated when parsing the object's docstring.
	`_parse_warnings`: Warnings generated when parsing the object's docstring.
`UID`	`_uid`: The object's unique identifier

Class Variable Summary
`SRE_Pattern`	`_SIGNATURE_RE`: A regular expression that is used to check whether a builtin function or method has a signature in its docstring.
Error Reporting
`list`	`_param_mismatches`: A dictionary whose keys are pairs (uid, base_uid), where uid is a method whose parameters do not match the parameters of its base class base_uid.
Inherited from ObjDoc
`List` of `DocField`	`STANDARD_FIELDS`: The list of standard docstring fields that epydoc accepts.

Method Details

find_override(self, bases)

Find the method that this method overrides.

keywords(self)

Returns:: The keyword parameters for the function/method documented by this FuncDoc.
(type=list of Var)

kwarg(self)

Returns:: The keyword parameter for the function/method documented by this FuncDoc, or None if it has no keyword parameter.
(type=Var or None)

matches_override(self)

Returns:: True if the method documented by this FuncDoc overrides another method, and its signature matches the signature of the overridden method.
(type=boolean)

overrides(self)

Returns:: The method overridden by the method documented by this FuncDoc; or None if the method documented by this FuncDoc does not override any method, or if this FuncDoc documents a function.
(type=Link or None)

parameter_list(self)

Returns:: A (flat) list of all parameters for the function/method documented by this FuncDoc. If you are interested in the signature of the function/method, you should use parameters instead. This list includes vararg & keyword params, but does not include the return value.
(type=list of Var)

See Also: parameters

parameters(self)

Returns:

The positional parameters for the function/method documented by this FuncDoc. This is typically a list of parameters, but it can contain sublists if the function/method's signature contains sublists. For example, for the function:

>>> def f(a, (b, c), d): pass

For this function, parameters will return a three-element list, whose second element is a sublist containing Vars for b and c.

If you just want a list of all parameters used by the function/method, use parameter_list instead.
(type=list of Var)

raises(self)

Returns:: A list of exceptions that may be raised by the function/method documented by this FuncDoc.
(type=list of Raise)

returns(self)

Returns:: The return value for the function/method documented by this FuncDoc, or None if it has no return value.
(type=Var or None)

vararg(self)

Returns:: The vararg parameter for the function/method documented by this FuncDoc, or None if it has no vararg parameter.
(type=Var or None)

_init_builtin_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 "...".

Returns:: None

_process_field(self, tag, arg, descr, warnings)

Process a field from this object's docstring. ObjDoc._process_field be overridden by child classes of ObjDoc, and called as the default case.

Parameters:: tag - The field's tag name
(type=string); arg - The field's optional argument (or None if no argument was specified).
(type=string); descr - The field's body.
(type=markup.ParsedDocstring); warnings - A list of warnings that have been encountered. If any new warnings are encountered, then they should be appended to this list.

Overrides:: lemon.external.epydoc.objdoc.ObjDoc._process_field (inherited documentation)

_signature_match(self, basespec, childspec)

Returns:: True if the signature of childfunc matches the signature of basefunc well enough that we should inherit its documentation.
(type=boolean)

Instance Variable Details

_kwarg_param

This function's keyword parameter, or None if it has none.

Type:: Var

_params

A list of this function's normal parameters.

Type:: list of Var

_raises

The exceptions that may be raised by this function.

Type:: list of Raise

_return

This function's return value.

Type:: Var

_vararg_param

This function's vararg parameter, or None if it has none.

Type:: Var

Class Variable Details

_param_mismatches

A dictionary whose keys are pairs (uid, base_uid), where uid is a method whose parameters do not match the parameters of its base class base_uid.

Type:: list
Value:: []

_SIGNATURE_RE

A regular expression that is used to check whether a builtin function or method has a signature in its docstring.

Type:: SRE_Pattern
Value:: ^\s*((\w+)\.)?(\w+)$((\s*\[?\s*[\w-\.]+(=.+?)?(\s*\[?\s*,\s*\]?\s*[\w\ -\.]+(=.+?)?)*\]*)?)\s*$(\s*(->|<=+>)\s*(\S.*?))?\s*(\n|\s+--\s+|$|\.\ \s|\.\n)

Generated by Epydoc 2.0 on Mon Nov 10 15:08:08 2003

http://epydoc.sf.net