commit 6f129c123e02673736d8facd8dc046a38a4375b8
author David L. Jones <dlj@google.com> Tue Mar 10 12:57:30 2020 -0700
committer GitHub <noreply@github.com> Tue Mar 10 12:57:30 2020 -0700
tree a79f290d62107250643e56eb342aa97868a8f313
parent 637d7eda30cd6945da13f4b089612d2e80c6bf33

Update docs so we can generate better output from Sphinx. (#7295)

This change updates docstrings and comments so that they will produce nicer
formatting and cross-references from Sphinx. There are a few broad categories of
changes:

- Paramter and attribute docs are updated so that types will be recognized by
  Napoleon (https://sphinxcontrib-napoleon.readthedocs.io/en/latest/) This
  usually just means moving a colon in the docstring, so
  `name: (type) description` becomes `name (type): description`.

- References to other symbols can be cross-references if they have the right
  format. For example, "attr_name" might become ":attr:`attr_name`".
  https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects

- For fenced code blocks, adding a double-colon `::` signifies a literal block.
  https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks

- Some bits of docstrings move from docstring to comments. For TODOs, this
  means we won't be putting stale (or otherwise unrelated) noise into the docs.
  For `Message.DESCRIPTOR`, the change means it gets appropriate documentation.

- There are some wording tweaks for consistency, and some new docstrings
  (especially for methods in Message).

For types, I used the convention of `list[Foo]` and `dict(foo, bar)`, which seem
to be common among other Python rst docstrings. Sphinx should generally
recognize both, and cross-links them correctly (both internally and to Python
library documentation). Upgrading to Python3-style type annotations would allow
us to use `sphinx-autodoc-typehints`; the changes in this commit are very
similar to typing-based hints.