epydoc.objdoc.ObjDoc

Package epydoc :: Module objdoc :: Class ObjDoc

[show private | hide private]

Class ObjDoc

Known Subclasses:: ClassDoc, FuncDoc, ModuleDoc, PropertyDoc

A base class for encoding the information about a Python object that is necessary to create its documentation. This base class defines the following pieces of documentation:

uid: The object's unique identifier.
descr: A full description of the object.
summary: A summary description of the object.
fields: A list of generic docstring fields, such as authors, version, and notes. The list of standard generic docstring fields is defined by the variable ObjDoc.STANDARD_FIELDS; but the user may also add new generic docstring fields (via @newfield or __extra_epydoc_fields__).
sortorder: The object's sort order, as defined by the @sort field.
groups: Groupings for contained objects (or parameters).

Method Summary
	`__init__(self, uid, verbosity, docstring)` Create the documentation for the given object.
Accessors
`UID`	`uid(self)` Return the UID of the object documented by this `ObjDoc`.
`markup.ParsedDocstring`	`descr(self)` Return a description 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 `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 `string`	`sortorder(self)` Return a list specifying the sort order that should be used for the object's children.
`list` of `string`	`groups(self)` Return a list of the names of the groups that are defined for the object documented by this `ObjDoc`.
`list` of `(string, elt)`	`by_group(self, elts)` Divide a set of elements into groups.
`boolean`	`has_docstring(self)` Return true if the object documented by this `ObjDoc` has a docstring.
`markup.ParsedDocstring`	`summary(self)` Return a summary of the description of the object documented by this `ObjDoc`.
`boolean`	`defines_groups(self)` Return true if the object documented by this `ObjDoc` defines any groups.

Class Variable Summary
Docstring Parsing
`List` of `DocField`	`STANDARD_FIELDS`: The list of standard docstring fields that epydoc accepts.

Method Details

uid(self)

Returns:: The UID of the object documented by this ObjDoc.
(type=UID)

descr(self)

Returns:: A description of the object documented by this ObjDoc.
(type=markup.ParsedDocstring)

fields(self)

Returns:: A list of the fields that are given values in the docstring of the object documented by this ObjDoc. The fields are listed in the order that they first appear in the docstring.
(type=list of DocField)

field_values(self, field)

Returns:: A list of the values that are specified for the given field in the docstring of the object documented by this ObjDoc. Values are listed in the order that they appear in the docstring.
(type=list of markup.ParsedDocstring)

sortorder(self)

Returns:: A list specifying the sort order that should be used for the object's children. Elements that are in this list should appear before elements that are not in this list; and elements that are in this list should appear in the order that they appear in this list.
(type=list of string)

groups(self)

Returns:: A list of the names of the groups that are defined for the object documented by this ObjDoc. To divide a set of children into groups, use by_group.
(type=list of string)

by_group(self, elts)

Divide a set of elements into groups. Typical usage:

>>> grouped_funcs = fdoc.by_group(fdoc.functions())
>>> for (group, members) in grouped_funcs:
...     print group, members

Parameters:: elts - The set of elements that should be divided into groups. These elements should be Links, Vars, or Params specifying child objects of the object documented by this ObjDoc.
(type=list of (Link or Var or ObjDoc))

Returns:: A list of tuples of the form (name, members), where name is the name of a group; and members is a list of the elements in elts that are in the group. Group membership is tested with the elt.name() method, so every element in elts must define that method.
(type=list of (string, elt))

has_docstring(self)

Returns:: True if the object documented by this ObjDoc has a docstring.
(type=boolean)

summary(self)

Returns:: A summary of the description of the object documented by this ObjDoc.
(type=markup.ParsedDocstring)

defines_groups(self)

Returns:: True if the object documented by this ObjDoc defines any groups.
(type=boolean)

init(self, uid, verbosity=0, docstring=None)
(Constructor)

Create the documentation for the given object.

Parameters:: uid - The UID of the object to document.
(type=UID); verbosity - The verbosity of output produced when creating documentation for the object. More positive numbers produce more verbose output; negative numbers supress warnings and errors.
(type=int)

Class Variable Details

STANDARD_FIELDS

The list of standard docstring fields that epydoc accepts. The order of fields is significant: when the fields are rendered, they will be listed in the order that they are given in this list. Note that this list does not include special fields, such as "group"; it just includes "simple" fields, which contain a single textual description or a list of textual descriptions.

Type:: List of DocField
Value:: [<Field: depreciated>, <Field: version>, <Field: date>, <Field: status>, <Field: author>, <Field: contact>, <Field: organization>, <Field: copyright>, ...

Generated by Epydoc 2.1 on Sat Mar 20 17:46:17 2004

http://epydoc.sf.net