documenting class properties
- by intuited
I'm writing a lightweight class whose properties are intended to be publicly accessible, and only sometimes overridden in specific instantiations. There's no provision in the Python language for creating docstrings for class properties, or any sort of properties, for that matter. What is the accepted way, should there be one, to document these properties? Currently I'm doing this sort of thing:
class Albatross(object):
"""A bird with a flight speed exceeding that of an unladen swallow.
Properties:
"""
flight_speed = 691
__doc__ += """
flight_speed (691)
The maximum speed that such a bird can attain
"""
nesting_grounds = "Throatwarbler Man Grove"
__doc__ += """
nesting_grounds ("Throatwarbler Man Grove")
The locale where these birds congregate to reproduce.
"""
def __init__(**keyargs):
"""Initialize the Albatross from the keyword arguments."""
self.__dict__.update(keyargs)
Although this style doesn't seem to be expressly forbidden in the docstring style guidelines, it's also not mentioned as an option. The advantage here is that it provides a way to document properties alongside their definitions, while still creating a presentable class docstring, and avoiding having to write comments that reiterate the information from the docstring. I'm still kind of annoyed that I have to actually write the properties twice; I'm considering using the string representations of the values in the docstring to at least avoid duplication of the default values.
Is this a heinous breach of the ad hoc community conventions? Is it okay? Is there a better way? For example, it's possible to create a dictionary containing values and docstrings for the properties and then add the contents to the class __dict__ and docstring towards the end of the class declaration; this would alleviate the need to type the property names and values twice.
I'm pretty new to python and still working out the details of coding style, so unrelated critiques are also welcome.
