pw_protobuf: Document the codegen-private namespace
Also, rename the private codegen namespace from pwpb_codegen_detail to
pwpb_codegen_private.
I recently got some CLs that actually were trying to use this private
namespace, which shows me that it's not sufficiently clear that users
are not meant to use them. I added some documentation, but for those who
don't read it, hopefully "private" is more recognizable than "detail".
Change-Id: Ifc4ce1cab8e03364ae5aeee2372989b4c06d6527
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/120811
Reviewed-by: Alexei Frolov <frolv@google.com>
Commit-Queue: Anqi Dong <anqid@google.com>
diff --git a/pw_protobuf/docs.rst b/pw_protobuf/docs.rst
index ca71c12..7b2cc69 100644
--- a/pw_protobuf/docs.rst
+++ b/pw_protobuf/docs.rst
@@ -495,6 +495,29 @@
return status.IsOutOfRange() ? OkStatus() : status;
}
+
+Handling of packages
+====================
+
+Package declarations in ``.proto`` files are converted to namespace
+declarations. Unlike ``protoc``'s native C++ codegen, pw_protobuf appends an
+additional ``::pwpb`` namespace after the user-specified package name: for
+example, ``package my.cool.project`` becomes ``namespace
+my::cool::project::pwpb``. We emit a different package name than stated, in
+order to avoid clashes for projects that link against multiple C++ proto
+libraries in the same library.
+
+..
+ TODO(b/258832150) Remove this section, if possible
+
+In some cases, pw_protobuf codegen may encounter external message references
+during parsing, where it is unable to resolve the package name of the message.
+In these situations, the codegen is instead forced to emit the package name as
+``pw::pwpb_xxx::my::cool::project``, where "pwpb_xxx" is the name of some
+unspecified private namespace. Users are expected to manually identify the
+intended namespace name of that symbol, as described above, and must not rely
+on any such private namespaces, even if they appear in codegen output.
+
-------
Codegen
-------
diff --git a/pw_protobuf/py/pw_protobuf/proto_tree.py b/pw_protobuf/py/pw_protobuf/proto_tree.py
index 2f807f5..d83c607 100644
--- a/pw_protobuf/py/pw_protobuf/proto_tree.py
+++ b/pw_protobuf/py/pw_protobuf/proto_tree.py
@@ -42,11 +42,11 @@
# codegen. This namespace provides us with an alternative, more verbose
# namespace that the codegen can use as a fallback in these cases. For example,
# for the symbol name `my.external.package.ProtoMsg.SubMsg`, we would use
-# `::pw::pwpb_codegen_detail::my::external::package:ProtoMsg::SubMsg` to refer
+# `::pw::pwpb_codegen_private::my::external::package:ProtoMsg::SubMsg` to refer
# to the pw_protobuf generated code, when package name info is not available.
#
# TODO(b/258832150) Explore removing this if possible
-EXTERNAL_SYMBOL_WORKAROUND_NAMESPACE = 'pw::pwpb_codegen_detail'
+EXTERNAL_SYMBOL_WORKAROUND_NAMESPACE = 'pw::pwpb_codegen_private'
class ProtoNode(abc.ABC):
