Doc string parameter documentation

[Kapil Thangavelu]

Hi Folks,

We've seem to grown a few different incompatible ways of documenting parameters 
in code. Originally we were using twisted's pydoctor syntax, but we since
migrated to using sphinx for documentation.

We should use one style consistently. Given our usage of sphinx, I think all 
parameter documentation references should be cleaned up to use its style as we 
go.

Sphinx parameters
http://sphinx.pocoo.org/domains.html#info-field-lists

Using the autodoc extension to extract docs from source code.
http://sphinx.pocoo.org/ext/autodoc.html


cheers,

Kapil