Update docs so we can generate better output from Sphinx. (protocolbu…

…ffers#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.

python/google/protobuf/descriptor_pool.py

@@ -38,7 +38,7 @@
 the protocol buffer compiler tool. This should only be used when the type of
 protocol buffers used in an application or library cannot be predetermined.
 
-Below is a straightforward example on how to use this class:
+Below is a straightforward example on how to use this class::
 
   pool = DescriptorPool()
   file_descriptor_protos = [ ... ]
@@ -91,10 +91,10 @@ def _NormalizeFullyQualifiedName(name):
   generated with a leading period. This function removes that prefix.
 
   Args:
-    name: A str, the fully-qualified symbol name.
+    name (str): The fully-qualified symbol name.
 
   Returns:
-    A str, the normalized fully-qualified symbol name.
+    str: The normalized fully-qualified symbol name.
   """
   return name.lstrip('.')
 
@@ -159,8 +159,8 @@ def _CheckConflictRegister(self, desc, desc_name, file_name):
 
     Args:
       desc: Descriptor of a message, enum, service, extension or enum value.
-      desc_name: the full name of desc.
-      file_name: The file name of descriptor.
+      desc_name (str): the full name of desc.
+      file_name (str): The file name of descriptor.
     """
     for register, descriptor_type in [
         (self._descriptors, descriptor.Descriptor),
@@ -196,7 +196,7 @@ def Add(self, file_desc_proto):
     """Adds the FileDescriptorProto and its types to this pool.
 
     Args:
-      file_desc_proto: The FileDescriptorProto to add.
+      file_desc_proto (FileDescriptorProto): The file descriptor to add.
     """
 
     self._internal_db.Add(file_desc_proto)
@@ -205,8 +205,8 @@ def AddSerializedFile(self, serialized_file_desc_proto):
     """Adds the FileDescriptorProto and its types to this pool.
 
     Args:
-      serialized_file_desc_proto: A bytes string, serialization of the
-        FileDescriptorProto to add.
+      serialized_file_desc_proto (bytes): A bytes string, serialization of the
+        :class:`FileDescriptorProto` to add.
     """
 
     # pylint: disable=g-import-not-at-top
@@ -392,10 +392,10 @@ def FindFileByName(self, file_name):
     """Gets a FileDescriptor by file name.
 
     Args:
-      file_name: The path to the file to get a descriptor for.
+      file_name (str): The path to the file to get a descriptor for.
 
     Returns:
-      A FileDescriptor for the named file.
+      FileDescriptor: The descriptor for the named file.
 
     Raises:
       KeyError: if the file cannot be found in the pool.
@@ -421,10 +421,11 @@ def FindFileContainingSymbol(self, symbol):
     """Gets the FileDescriptor for the file containing the specified symbol.
 
     Args:
-      symbol: The name of the symbol to search for.
+      symbol (str): The name of the symbol to search for.
 
     Returns:
-      A FileDescriptor that contains the specified symbol.
+      FileDescriptor: Descriptor for the file that contains the specified
+      symbol.
 
     Raises:
       KeyError: if the file cannot be found in the pool.
@@ -447,10 +448,11 @@ def _InternalFindFileContainingSymbol(self, symbol):
     """Gets the already built FileDescriptor containing the specified symbol.
 
     Args:
-      symbol: The name of the symbol to search for.
+      symbol (str): The name of the symbol to search for.
 
     Returns:
-      A FileDescriptor that contains the specified symbol.
+      FileDescriptor: Descriptor for the file that contains the specified
+      symbol.
 
     Raises:
       KeyError: if the file cannot be found in the pool.
@@ -495,10 +497,10 @@ def FindMessageTypeByName(self, full_name):
     """Loads the named descriptor from the pool.
 
     Args:
-      full_name: The full name of the descriptor to load.
+      full_name (str): The full name of the descriptor to load.
 
     Returns:
-      The descriptor for the named type.
+      Descriptor: The descriptor for the named type.
 
     Raises:
       KeyError: if the message cannot be found in the pool.
@@ -513,10 +515,10 @@ def FindEnumTypeByName(self, full_name):
     """Loads the named enum descriptor from the pool.
 
     Args:
-      full_name: The full name of the enum descriptor to load.
+      full_name (str): The full name of the enum descriptor to load.
 
     Returns:
-      The enum descriptor for the named type.
+      EnumDescriptor: The enum descriptor for the named type.
 
     Raises:
       KeyError: if the enum cannot be found in the pool.
@@ -531,10 +533,10 @@ def FindFieldByName(self, full_name):
     """Loads the named field descriptor from the pool.
 
     Args:
-      full_name: The full name of the field descriptor to load.
+      full_name (str): The full name of the field descriptor to load.
 
     Returns:
-      The field descriptor for the named field.
+      FieldDescriptor: The field descriptor for the named field.
 
     Raises:
       KeyError: if the field cannot be found in the pool.
@@ -548,10 +550,10 @@ def FindOneofByName(self, full_name):
     """Loads the named oneof descriptor from the pool.
 
     Args:
-      full_name: The full name of the oneof descriptor to load.
+      full_name (str): The full name of the oneof descriptor to load.
 
     Returns:
-      The oneof descriptor for the named oneof.
+      OneofDescriptor: The oneof descriptor for the named oneof.
 
     Raises:
       KeyError: if the oneof cannot be found in the pool.
@@ -565,10 +567,10 @@ def FindExtensionByName(self, full_name):
     """Loads the named extension descriptor from the pool.
 
     Args:
-      full_name: The full name of the extension descriptor to load.
+      full_name (str): The full name of the extension descriptor to load.
 
     Returns:
-      A FieldDescriptor, describing the named extension.
+      FieldDescriptor: The field descriptor for the named extension.
 
     Raises:
       KeyError: if the extension cannot be found in the pool.
@@ -594,15 +596,15 @@ def FindExtensionByName(self, full_name):
   def FindExtensionByNumber(self, message_descriptor, number):
     """Gets the extension of the specified message with the specified number.
 
-    Extensions have to be registered to this pool by calling
-    AddExtensionDescriptor.
+    Extensions have to be registered to this pool by calling :func:`Add` or
+    :func:`AddExtensionDescriptor`.
 
     Args:
-      message_descriptor: descriptor of the extended message.
-      number: integer, number of the extension field.
+      message_descriptor (Descriptor): descriptor of the extended message.
+      number (int): Number of the extension field.
 
     Returns:
-      A FieldDescriptor describing the extension.
+      FieldDescriptor: The descriptor for the extension.
 
     Raises:
       KeyError: when no extension with the given number is known for the
@@ -615,16 +617,16 @@ def FindExtensionByNumber(self, message_descriptor, number):
       return self._extensions_by_number[message_descriptor][number]
 
   def FindAllExtensions(self, message_descriptor):
-    """Gets all the known extension of a given message.
+    """Gets all the known extensions of a given message.
 
     Extensions have to be registered to this pool by calling
-    AddExtensionDescriptor.
+    :func:`Add` or :func:`AddExtensionDescriptor`.
 
     Args:
-      message_descriptor: descriptor of the extended message.
+      message_descriptor (Descriptor): Descriptor of the extended message.
 
     Returns:
-      A list of FieldDescriptor describing the extensions.
+      list[FieldDescriptor]: Field descriptors describing the extensions.
     """
     # Fallback to descriptor db if FindAllExtensionNumbers is provided.
     if self._descriptor_db and hasattr(
@@ -681,10 +683,10 @@ def FindServiceByName(self, full_name):
     """Loads the named service descriptor from the pool.
 
     Args:
-      full_name: The full name of the service descriptor to load.
+      full_name (str): The full name of the service descriptor to load.
 
     Returns:
-      The service descriptor for the named service.
+      ServiceDescriptor: The service descriptor for the named service.
 
     Raises:
       KeyError: if the service cannot be found in the pool.
@@ -698,10 +700,10 @@ def FindMethodByName(self, full_name):
     """Loads the named service method descriptor from the pool.
 
     Args:
-      full_name: The full name of the method descriptor to load.
+      full_name (str): The full name of the method descriptor to load.
 
     Returns:
-      The method descriptor for the service method.
+      MethodDescriptor: The method descriptor for the service method.
 
     Raises:
       KeyError: if the method cannot be found in the pool.
@@ -715,10 +717,10 @@ def _FindFileContainingSymbolInDb(self, symbol):
     """Finds the file in descriptor DB containing the specified symbol.
 
     Args:
-      symbol: The name of the symbol to search for.
+      symbol (str): The name of the symbol to search for.
 
     Returns:
-      A FileDescriptor that contains the specified symbol.
+      FileDescriptor: The file that contains the specified symbol.
 
     Raises:
       KeyError: if the file cannot be found in the descriptor database.

python/google/protobuf/internal/containers.py

@@ -33,9 +33,10 @@
 This file defines container classes which represent categories of protocol
 buffer field types which need extra maintenance. Currently these categories
 are:
-  - Repeated scalar fields - These are all repeated fields which aren't
+
+-   Repeated scalar fields - These are all repeated fields which aren't
     composite (e.g. they are of simple types like int32, string, etc).
-  - Repeated composite fields - Repeated fields which are composite. This
+-   Repeated composite fields - Repeated fields which are composite. This
     includes groups and nested messages.
 """
 
@@ -285,7 +286,6 @@ def extend(self, elem_seq):
 
   def MergeFrom(self, other):
     """Appends the contents of another repeated field of the same type to this
-
     one. We do not check the types of the individual fields.
     """
     self._values.extend(other._values)
@@ -416,7 +416,6 @@ def extend(self, elem_seq):
 
   def MergeFrom(self, other):
     """Appends the contents of another repeated field of the same type to this
-
     one, copying each individual message.
     """
     self.extend(other._values)