Home | Trees | Indices | Help |
|
---|
|
API documentation information for a single element of a Python
program. APIDoc
itself is an abstract base class;
subclasses are used to specify what information should be recorded about
each type of program element. In particular, APIDoc
has two
direct subclasses, VariableDoc
for documenting variables and
ValueDoc
for documenting values; and the
ValueDoc
class is subclassed further for different value
types.
Each APIDoc
subclass specifies the set of attributes that
should be used to record information about the corresponding program
element type. The default value for each attribute is stored in the
class; these default values can then be overridden with instance
variables. Most attributes use the special value UNKNOWN as
their default value, to indicate that the correct value for that
attribute has not yet been determined. This makes it easier to merge two
APIDoc
objects that are documenting the same element (in
particular, to merge information about an element that was derived from
parsing with information that was derived from introspection).
For all attributes with boolean values, use only the constants
True
and False
to designate true and false. In
particular, do not use other values that evaluate as true or
false, such as 2
or ()
. This restriction makes
it easier to handle UNKNOWN
values. For example, to test if
a boolean attribute is True
or UNKNOWN
, use
'attrib in (True, UNKNOWN)
' or 'attrib is not
False
'.
APIDoc
objects describing the same object can be merged, using the method
merge_and_overwrite(other). After two
APIDoc
s are merged, any changes to one will be reflected in
the other. This is accomplished by setting the two APIDoc
objects to use a shared instance dictionary. See the documentation for
merge_and_overwrite for more information, and some
important caveats about hashing.
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
bool
|
|
||
|
|||
|
|||
Inherited from |
|
|||
__has_been_hashed = True True iff self.__hash__() has ever been called. |
|||
__mergeset = True The set of all APIDoc objects that have been merged
with this APIDoc (using merge_and_overwrite()).
|
|
|||
Docstrings | |||
---|---|---|---|
string or None
|
docstring = _Sentinel('UNKNOWN') The documented item's docstring. |
||
int
|
docstring_lineno = _Sentinel('UNKNOWN') The line number on which the documented item's docstring begins. |
||
Information Extracted from Docstrings | |||
ParsedDocstring |
descr = _Sentinel('UNKNOWN') A description of the documented item, extracted from its docstring. |
||
ParsedDocstring |
summary = _Sentinel('UNKNOWN') A summary description of the documented item, extracted from its docstring. |
||
bool
|
other_docs = _Sentinel('UNKNOWN') A flag indicating if the entire docstring body (except tags if any) is entirely included in the summary. |
||
(str, str, ParsedDocstring)
|
metadata = _Sentinel('UNKNOWN') Metadata about the documented item, extracted from fields in its docstring. |
||
DocstringField |
extra_docstring_fields = _Sentinel('UNKNOWN') A list of new docstring fields tags that are defined by the documented item's docstring. |
||
Source Information | |||
str
|
docs_extracted_by = _Sentinel('UNKNOWN') Information about where the information contained by this APIDoc came from.
|
|
|||
Inherited from |
|
APIDoc object. Keyword arguments may be
used to initialize the new APIDoc 's attributes.
|
APIDoc 's attribute. This is used when epydoc.DEBUG is true, to
make sure we don't accidentally set any inappropriate attributes on
APIDoc objects.
|
APIDoc 's attribute. This is used when epydoc.DEBUG is true, to
make sure we don't accidentally set any inappropriate attributes on
APIDoc objects.
|
repr(x)
|
APIDoc .
|
self 's class to cls .
cls must be a subclass of self 's current class.
For example, if a generic ValueDoc was created for a value,
and it is determined that the value is a routine, you can update its
class with:
>>> valdoc.specialize_to(RoutineDoc)
|
hash(x)
|
|
Combine other . To help avoid the problems that this can cause,
merge_and_overwrite will raise an exception if
other has ever been hashed, unless
ignore_hash_conflict is True. Note that adding
other to a dictionary, set, or similar data structure will
implicitly cause it to be hashed. If you do set
ignore_hash_conflict to True, then any existing data
structures that rely on other 's hash staying constant may
become corrupted.
|
Return a list of all filters can be used to selectively
exclude certain categories of attribute value. For example, using
includes=False will exclude variables that were imported
from other modules; and subclasses=False will exclude
subclasses. The filter categories currently supported by epydoc are:
|
|
__mergesetThe set of allAPIDoc objects that have been merged with
this APIDoc (using merge_and_overwrite()). Each APIDoc in
this set shares a common instance dictionary (__dict__ ).
|
|
metadataMetadata about the documented item, extracted from fields in its docstring. Currently this is encoded as a list of tuples(field, arg, descr) . But that may change.
|
extra_docstring_fieldsA list of new docstring fields tags that are defined by the documented item's docstring. These new field tags can be used by this item or by any item it contains.
|
docs_extracted_byInformation about where the information contained by thisAPIDoc came from. Can be one of 'parser' ,
'introspector' , or 'both' .
|
Home | Trees | Indices | Help |
|
---|
Generated by Epydoc 3.0beta1 on Thu Mar 1 04:23:35 2007 | http://epydoc.sourceforge.net |