commit 8f284fc0adccda32d5270e358708d097de75754a
author Matthias Guenther <mrguenther@google.com> Thu Jun 09 15:06:58 2022 -0700
committer CQ Bot Account <pigweed-scoped@luci-project-accounts.iam.gserviceaccount.com> Fri Jun 10 00:50:53 2022 +0000
tree dedfbe0cea023eb743a1cc950612a9627b94aa02
parent e29b5fd0be53cb0b01859ca5970874704a830675

pw_protobuf: Fix documentation mistake

Change 96900 included documentation that had become outdated by the time
the change was submitted; this change fixes the documentation.

Bugs: b/234855743
Change-Id: Idc614aefadf3d96770bd78fdbb7ed99cf15e229b
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/97669
Reviewed-by: Ted Pudlik <tpudlik@google.com>
Commit-Queue: Matthias Guenther <mrguenther@google.com>

pw_protobuf/docs.rst

diff --git a/pw_protobuf/docs.rst b/pw_protobuf/docs.rst
index 98487a1..f7da518 100644
--- a/pw_protobuf/docs.rst
+++ b/pw_protobuf/docs.rst
@@ -666,11 +666,17 @@
       std::optional<int32_t> points;
     };
 
-* Fields and messages whose names conflict with reserved C++ keywords are
-  suffixed with underscores to avoid compilation failures. This also applies to
-  names that conflict with symbols defined by the code-generation
-  implementation. These cases are illustrated below by the ``operator`` field
-  and the ``Message`` message, respectively.
+* Generated symbols whose names conflict with reserved C++ keywords or
+  standard-library macros are suffixed with underscores to avoid compilation
+  failures. This can be seen below in ``Channel.operator``, which is mapped to
+  ``Channel::Message::operator_`` to avoid conflicting with the ``operator``
+  keyword. Similarly, some POSIX signals are provided as macros by the
+  ``<csignal>`` header, so those names need to be suffixed with underscores in
+  the generated code. Note, however, that some signal names are left unchanged.
+  These signals aren't defined in the standard library, so they won't cause any
+  problems unless the user defines custom macros for them; any naming conflicts
+  caused by user-defined macros are the user's responsibility.
+  (https://google.github.io/styleguide/cppguide.html#Preprocessor_Macros)
 
   .. code::
 
@@ -680,10 +686,20 @@
       Company operator = 3;
     }
 
-    message Message {
-      User sender = 2;
-      User recipient = 3;
-      Channel channel = 4;
+    enum PosixSignal {
+      NONE = 0;
+      SIGHUP = 1;
+      SIGINT = 2;
+      SIGQUIT = 3;
+      SIGILL = 4;
+      SIGTRAP = 5;
+      SIGABRT = 6;
+      SIGFPE = 8;
+      SIGKILL = 9;
+      SIGSEGV = 11;
+      SIGPIPE = 13;
+      SIGALRM = 14;
+      SIGTERM = 15;
     }
 
   .. code:: c++
@@ -694,10 +710,34 @@
       Company::Message operator_;
     };
 
-    struct Message_::Message {
-      User::Message sender;
-      User::Message recipient;
-      Channel::Message channel;
+    enum class PosixSignal {
+      NONE = 0;
+      SIGHUP = 1;
+      SIGINT_ = 2;
+      SIGQUIT = 3;
+      SIGILL_ = 4;
+      SIGTRAP = 5;
+      SIGABRT_ = 6;
+      SIGFPE_ = 8;
+      SIGKILL = 9;
+      SIGSEGV_ = 11;
+      SIGPIPE = 13;
+      SIGALRM = 14;
+      SIGTERM_ = 15;
+
+      kNone = NONE;
+      kSighup = SIGHUP;
+      kSigint = SIGINT_;
+      kSigquit = SIGQUIT;
+      kSigill = SIGILL_;
+      kSigtrap = SIGTRAP;
+      kSigabrt = SIGABRT_;
+      kSigfpe = SIGFPE_;
+      kSigkill = SIGKILL;
+      kSigsegv = SIGSEGV_;
+      kSigpipe = SIGPIPE;
+      kSigalrm = SIGALRM;
+      kSigterm = SIGTERM_;
     };
 
 * Repeated scalar fields are represented by ``pw::Vector`` when the