epydoc.objdoc.FuncDoc

Package epydoc :: Module objdoc :: Class FuncDoc |
[show private | hide private]
[frames | no frames]

## 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`.
Inherited from `ObjDoc`: `_sort`
Accessors
`list` of `Var` | ``parameters`(self)` Return the positional parameters for the function/method documented by this `FuncDoc`.
`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.
`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.
`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.
`list` of `Raise` | ``raises`(self)` Return a list of exceptions that may be raised by the function/method documented by this `FuncDoc`.
`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.
`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.
`list` of `Var` | ``parameter_list`(self)` Return a (flat) list of all parameters for the function/method documented by this `FuncDoc`.
Inherited from `ObjDoc`: `by_group`, `defines_groups`, `descr`, `field_values`, `fields`, `groups`, `has_docstring`, `sortorder`, `summary`, `uid`
Inheritance
| ``find_override`(self, bases)` Find the method that this method overrides.
Signature Parsing
| `_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.
`None` | ``_init_builtin_signature`(self, func)` Construct the signature for a builtin function or method from its docstring.
Error Handling
Inherited from `ObjDoc`: `_print_errors`
Docstring Parsing
| ``_process_field`(self, tag, arg, descr, warnings)` Process a field from this object's docstring.

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`: `_uid`
Error Handling
Inherited from `ObjDoc`: `_field_warnings`, `_misc_warnings`, `_parse_errors`, `_parse_warnings`
Docstring Parsing
Inherited from `ObjDoc`: `_descr`, `_fields`

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.
Docstring Parsing
Inherited from `ObjDoc`: `STANDARD_FIELDS`

Method Details

    ### 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 `Var`s 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`)

### 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`)

### 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`)

### 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`)

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

### 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`)

### 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`)

### 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`

### find_override(self, bases) Find the method that this method overrides.

### _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`)

### _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`

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

### _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: `epydoc.objdoc.ObjDoc._process_field` (inherited documentation)

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.1 on Sat Mar 20 17:46:16 2004 | http://epydoc.sf.net