Inconsistent docstring formatting

[jc0n]

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).