pw_protobuf: expand docs
This change updates the protobuf docs to explain the module's design
decisions.
Change-Id: Idccacf28651cf091218dabb1d1ad09365d445776
diff --git a/pw_protobuf/BUILD.gn b/pw_protobuf/BUILD.gn
index 6550ea4..2b152cc 100644
--- a/pw_protobuf/BUILD.gn
+++ b/pw_protobuf/BUILD.gn
@@ -43,7 +43,7 @@
pw_doc_group("docs") {
sources = [
- "decoder.rst",
+ "decoding.rst",
"docs.rst",
]
report_deps = [
diff --git a/pw_protobuf/decoder.rst b/pw_protobuf/decoding.rst
similarity index 95%
rename from pw_protobuf/decoder.rst
rename to pw_protobuf/decoding.rst
index 2178b72..7c75a2e 100644
--- a/pw_protobuf/decoder.rst
+++ b/pw_protobuf/decoding.rst
@@ -4,9 +4,9 @@
.. _chapter-protobuf-decoder:
--------
-Decoder
--------
+--------
+Decoding
+--------
Size report
===========
diff --git a/pw_protobuf/docs.rst b/pw_protobuf/docs.rst
index fcb5981..11dd4e7 100644
--- a/pw_protobuf/docs.rst
+++ b/pw_protobuf/docs.rst
@@ -10,7 +10,66 @@
The protobuf module provides a lightweight interface for encoding and decoding
the Protocol Buffer wire format.
+Design
+======
+Unlike other protobuf libraries, which typically provide in-memory data
+structures to represent protobuf messages, pw_protobuf operates directly on the
+wire format and leaves data storage to the user. This has a few benefits. The
+primary one is that it allows the library to be incredibly small, with the
+encoder and decoder each having a code size of around 1.5K and negligible RAM
+usage. Users can choose the tradeoffs most suitable for their product on top of
+this core implementation.
+
+pw_protobuf also provides zero-overhead C++ code generation which wraps its
+low-level wire format operations with a user-friendly API for processing
+specific protobuf messages. The code generation integrates with Pigweed's GN
+build system.
+
+Usage
+=====
+pw_protobuf splits wire format encoding and decoding operations. Links to the
+design and APIs of each are listed in below.
+
+See also :ref:`chapter-pw-protobuf-compiler` for details on pw_protobuf's build
+system integration.
+
+**pw_protobuf functionality**
+
.. toctree::
:maxdepth: 1
- decoder
+ decoding
+
+Comparison with other protobuf libraries
+========================================
+
+protobuf-lite
+^^^^^^^^^^^^^
+protobuf-lite is the official reduced-size C++ implementation of protobuf. It
+uses a restricted subset of the protobuf library's features to minimize code
+size. However, is is still around 150K in size and requires dynamic memory
+allocation, making it unsuitable for many embedded systems.
+
+nanopb
+^^^^^^
+`nanopb <https://github.com/nanopb/nanopb>`_ is a commonly used embedded
+protobuf library with very small code size and full code generation. It provides
+both encoding/decoding functionality and in-memory C structs representing
+protobuf messages.
+
+nanopb works well for many embedded products; however, using its generated code
+can run into RAM usage issues when processing nontrivial protobuf messages due
+to the necessity of defining a struct capable of storing all configurations of
+the message, which can grow incredibly large. In one project, Pigweed developers
+encountered an 11K struct statically allocated for a single message---over twice
+the size of the final encoded output! (This was what prompted the development of
+pw_protobuf.)
+
+To avoid this issue, it is possible to use nanopb's low-level encode/decode
+functions to process individual message fields directly, but this loses all of
+the useful semantics of code generation. pw_protobuf is designed to optimize for
+this use case; it allows for efficient operations on the wire format with an
+intuitive user interface.
+
+Depending on the requirements of a project, either of these libraries could be
+suitable.
diff --git a/pw_protobuf_compiler/docs.rst b/pw_protobuf_compiler/docs.rst
index 232e356..e1bd439 100644
--- a/pw_protobuf_compiler/docs.rst
+++ b/pw_protobuf_compiler/docs.rst
@@ -1,9 +1,8 @@
-.. _chapter-pw-protobuf-compiler:
-
.. default-domain:: py
-
.. highlight:: py
+.. _chapter-pw-protobuf-compiler:
+
--------------------
pw_protobuf_compiler
--------------------