mirror of
https://github.com/protocolbuffers/protobuf
synced 2026-08-26 02:23:14 -04:00
6f129c123e
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. |
||
|---|---|---|
| .. | ||
| import_test_package | ||
| __init__.py | ||
| _parameterized.py | ||
| any_test.proto | ||
| api_implementation.cc | ||
| api_implementation.py | ||
| containers.py | ||
| decoder.py | ||
| descriptor_database_test.py | ||
| descriptor_pool_test.py | ||
| descriptor_pool_test1.proto | ||
| descriptor_pool_test2.proto | ||
| descriptor_test.py | ||
| encoder.py | ||
| enum_type_wrapper.py | ||
| extension_dict.py | ||
| factory_test1.proto | ||
| factory_test2.proto | ||
| file_options_test.proto | ||
| generator_test.py | ||
| json_format_test.py | ||
| keywords_test.py | ||
| message_factory_test.py | ||
| message_listener.py | ||
| message_set_extensions.proto | ||
| message_test.py | ||
| missing_enum_values.proto | ||
| more_extensions.proto | ||
| more_extensions_dynamic.proto | ||
| more_messages.proto | ||
| no_package.proto | ||
| packed_field_test.proto | ||
| proto_builder_test.py | ||
| python_message.py | ||
| python_protobuf.cc | ||
| reflection_test.py | ||
| service_reflection_test.py | ||
| symbol_database_test.py | ||
| test_bad_identifiers.proto | ||
| test_util.py | ||
| testing_refleaks.py | ||
| text_encoding_test.py | ||
| text_format_test.py | ||
| type_checkers.py | ||
| unknown_fields_test.py | ||
| well_known_types.py | ||
| well_known_types_test.py | ||
| wire_format.py | ||
| wire_format_test.py | ||