Home | Trees | Indices | Help |
|
---|
|
object --+ | type --+ | _AttributeDocstrings
Metaclass for declaring docstrings for class attributes.
|
|||
the object's type |
|
||
Inherited from Inherited from |
|
|||
Inherited from Inherited from |
|
Metaclass for declaring docstrings for class attributes. Base Python doesn't provide any syntax for setting docstrings on 'data attributes' (non-callables). This metaclass allows class definitions to follow the declaration of a data attribute with a docstring for that attribute; the attribute docstring will be popped from the class dict and folded into the class docstring. The naming convention for attribute docstrings is: <attrname> + "__doc". For example: class Thing(object): """A thing and its properties.""" __metaclass__ = cherrypy._AttributeDocstrings height = 50 height__doc = """The height of the Thing in inches.""" In which case, help(Thing) starts like this: >>> help(mod.Thing) Help on class Thing in module pkg.mod: class Thing(__builtin__.object) | A thing and its properties. | | height [= 50]: | The height of the Thing in inches. | The benefits of this approach over hand-edited class docstrings: 1. Places the docstring nearer to the attribute declaration. 2. Makes attribute docs more uniform ("name (default): doc"). 3. Reduces mismatches of attribute _names_ between the declaration and the documentation. 4. Reduces mismatches of attribute default _values_ between the declaration and the documentation. The benefits of a metaclass approach over other approaches: 1. Simpler ("less magic") than interface-based solutions. 2. __metaclass__ can be specified at the module global level for classic classes. For various formatting reasons, you should write multiline docs with a leading newline and not a trailing one: response__doc = """ The response object for the current thread. In the main thread, and any threads which are not HTTP requests, this is None.""" The type of the attribute is intentionally not included, because that's not How Python Works. Quack.
|
Home | Trees | Indices | Help |
|
---|
Generated by Epydoc 3.0.1 on Mon Aug 24 13:21:29 2009 | http://epydoc.sourceforge.net |