pw_protobuf: Expand message structure limitations docs section

Adds points about protobuf version and the use of std::optional. Change-Id: I4b886ecba93b33b0bb9fdae77913e378450b410a Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/249072 Pigweed-Auto-Submit: Alexei Frolov <[email protected]> Presubmit-Verified: CQ Bot Account <[email protected]> Reviewed-by: Kayce Basques <[email protected]> Commit-Queue: Auto-Submit <[email protected]> Lint: Lint 🤖 <[email protected]>
google · Nov 21, 2024 · f776679 · f776679
1 parent f4e18d1
commit f776679
Showing 1 changed file with 18 additions and 0 deletions.
diff --git a/pw_protobuf/docs.rst b/pw_protobuf/docs.rst
@@ -285,11 +285,29 @@ Message structures are eventually intended to be replaced with an alternative
 object model. See `SEED-0103 <http://pwrev.dev/133971>`_ for additional
 information about how message structures came to be and our future plans.
 
+Protobuf versioning
+^^^^^^^^^^^^^^^^^^^
+Message structures are generated in accordance to ``proto3`` semantics only.
+Unset fields default to their zero values. Explicit field presence is supported
+through the use of the ``optional`` specifier. Proto2-only keywords such as
+``required`` have no effect.
+
+There is limited preliminary support for Protobuf editions, primarily to allow
+editions-based proto files to compile. At this time, the only editions feature
+supported by the code generator is ``field_presence``.
+
 ``oneof`` fields
 ^^^^^^^^^^^^^^^^
 ``oneof`` protobuf fields cannot be inlined within a message structure: they
 must be encoded and decoded using callbacks.
 
+``optional`` fields
+^^^^^^^^^^^^^^^^^^^
+Only scalar fields generate a ``std::optional`` wrapper in the resulting message
+structure. Optional submessages or variable-length fields
+(``string`` / ``bytes``) must be processed through callbacks, requiring manual
+tracking of presence depending on whether or not the callback is invoked.
+
 .. _pw_protobuf-per-field-apis:
 
 Per-Field Writers and Readers