Fix up docstring markup for Pydoctor

* Double newlines for new paragraphs
* Use “:param:” syntax
Turn existing C comments into docstrings
Add and extend docstrings