I know documentation is another huge project in itself but it seems there are several different formatting schemes in docstrings all over the code base. I don't understand some of the more common docs using formatting such as:
Update a Power Reg persistent object
:param id: Primary key for the object to update.
:type id: int
:param value_map: A map attributes to update and their new values.
For a "many" end of a relationship, you may
provide a list of foreign keys to be added, or
you may provide a struct with two lists of keys
indexed as 'add' and 'remove'.
:type value_map: dict
I have never seen types documented like this in python and it should not be necessary since python is duck typed. The docstrings are also not well formatted for use in the python interpreter. (ie. help()). I find the formatting very hard to read as opposed to:
Update a Power Reg persistent object
Args:
id: the object's primary key
value_map: dictionary of attributes to update and their new values.
For a "many" end of a relationship, you may
provide a sequence of foreign keys to be added, or
you may provide a dictionary with two lists of keys
indexed as 'add' and 'remove'.
I'm not sure how the documentation is currently being generated or why the awkward formatting is required.
For a python project I think restructured text formatting is the way to go. Full documentation can be generated with Sphinx and the formatting is readable as regular pydoc, or with help().
This is an important issue regardless of whether or not we change existing docstrings to at least make sure that new ones are written properly. (or for me to understand why they are as is).
I know documentation is another huge project in itself but it seems there are several different formatting schemes in docstrings all over the code base. I don't understand some of the more common docs using formatting such as:
I have never seen types documented like this in python and it should not be necessary since python is duck typed. The docstrings are also not well formatted for use in the python interpreter. (ie.
help()). I find the formatting very hard to read as opposed to:I'm not sure how the documentation is currently being generated or why the awkward formatting is required.
For a python project I think restructured text formatting is the way to go. Full documentation can be generated with Sphinx and the formatting is readable as regular pydoc, or with
help().This is an important issue regardless of whether or not we change existing docstrings to at least make sure that new ones are written properly. (or for me to understand why they are as is).