Add or expand docs.rst
Change-Id: I18d1529088beb41b37be00a77ba8999f6b6f810a
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index aff6fa1..ab99c5e 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -43,6 +43,8 @@
"$dir_pw_bloat:docs",
"$dir_pw_boot_armv7m:docs",
"$dir_pw_build:docs",
+ "$dir_pw_checksum:docs",
+ "$dir_pw_containers:docs",
"$dir_pw_cpu_exception:docs",
"$dir_pw_cpu_exception_armv7m:docs",
"$dir_pw_docgen:docs",
@@ -64,5 +66,6 @@
"$dir_pw_sys_io_stdio:docs",
"$dir_pw_target_runner:docs",
"$dir_pw_tokenizer:docs",
+ "$dir_pw_varint:docs",
]
}
diff --git a/pw_checksum/BUILD.gn b/pw_checksum/BUILD.gn
index 743ee58..0a7e169 100644
--- a/pw_checksum/BUILD.gn
+++ b/pw_checksum/BUILD.gn
@@ -37,3 +37,7 @@
"ccitt_crc16_test.cc",
]
}
+
+pw_doc_group("docs") {
+ sources = [ "docs.rst" ]
+}
diff --git a/pw_checksum/docs.rst b/pw_checksum/docs.rst
new file mode 100644
index 0000000..5ae1a88
--- /dev/null
+++ b/pw_checksum/docs.rst
@@ -0,0 +1,40 @@
+.. default-domain:: cpp
+
+.. highlight:: sh
+
+-----------
+pw_checksum
+-----------
+The pw_checksum module provides functions for calculating checksums.
+
+pw_checksum/ccitt_crc16.h
+=========================
+
+.. cpp:namespace:: pw::checksum
+
+.. cpp:var:: constexpr uint16_t kCcittCrc16DefaultInitialValue = 0xFFFF
+
+ The default initial value for the CRC16.
+
+.. cpp:function:: uint16_t CcittCrc16(span<const std::byte> data, uint16_t initial_value = kCcittCrc16DefaultInitialValue)
+
+ Calculates the CRC16 of the provided data using polynomial 0x1021, with a
+ default initial value of :cpp:expr:`0xFFFF`.
+
+ To incrementally calculate a CRC16, use the previous value as the initial
+ value.
+
+ .. code-block:: cpp
+
+ uint16_t crc = CcittCrc16(my_data);
+
+ crc = CcittCrc16(more_data, crc);
+
+Compatibility
+=============
+* C
+* C++17
+
+Dependencies
+============
+* pw_span
diff --git a/pw_containers/BUILD.gn b/pw_containers/BUILD.gn
index 7e2aff9..a009e8d 100644
--- a/pw_containers/BUILD.gn
+++ b/pw_containers/BUILD.gn
@@ -12,6 +12,7 @@
# License for the specific language governing permissions and limitations under
# the License.
+import("$dir_pw_docgen/docs.gni")
import("$dir_pw_unit_test/test.gni")
config("default_config") {
@@ -32,3 +33,7 @@
deps = [ ":pw_containers" ]
sources = [ "vector_test.cc" ]
}
+
+pw_doc_group("docs") {
+ sources = [ "docs.rst" ]
+}
diff --git a/pw_containers/docs.rst b/pw_containers/docs.rst
new file mode 100644
index 0000000..377ac92
--- /dev/null
+++ b/pw_containers/docs.rst
@@ -0,0 +1,30 @@
+.. default-domain:: cpp
+
+.. highlight:: sh
+
+-------------
+pw_containers
+-------------
+The pw_containers module provides embedded-friendly container classes.
+
+pw_vector
+=========
+The Vector class is similar to std::vector, except it is backed by a
+fixed-size buffer. Vectors must be declared with an explicit maximum size
+(e.g. ``Vector<int, 10>``) but vectors can be used and referred to without the
+max size template parameter (e.g. ``Vector<int>``).
+
+To allow referring to a ``pw::Vector`` without an explicit maximum size, all
+Vector classes inherit from the generic ``Vector<T>``, which stores the maximum
+size in a variable. This allows Vectors to be used without having to know
+their maximum size at compile time. It also keeps code size small since
+function implementations are shared for all maximum sizes.
+
+Compatibility
+=============
+* C
+* C++17
+
+Dependencies
+============
+* pw_span
diff --git a/pw_string/README.md b/pw_string/README.md
index 9c850c1..0659a70 100644
--- a/pw_string/README.md
+++ b/pw_string/README.md
@@ -1 +1 @@
-# pw\_string: Utilities for safely building strings
+# pw\_string: Embedded-friendly C++ string manipulation primitives
diff --git a/pw_string/docs.rst b/pw_string/docs.rst
index 67ee9a6..25cf59c 100644
--- a/pw_string/docs.rst
+++ b/pw_string/docs.rst
@@ -7,9 +7,16 @@
---------
pw_string
---------
-The string module provides efficient utilities for safely working with strings.
-The pw_string functions and classes always null-terminate strings and never
-overrun buffers. They do not allocate their own memory.
+String manipulation is a very common operation, but the standard C and C++
+string libraries have drawbacks. The C++ functions are easy-to-use and powerful,
+but require too much flash and memory for many embedded projects. The C string
+functions are lighter weight, but can be difficult to use correctly. Mishandling
+of null terminators or buffer sizes can result in serious bugs.
+
+The pw_string module provides the flexibility, ease-of-use, and safety of
+C++-style string manipulation, but with no dynamic memory allocation and a much
+smaller binary size impact. Using pw_string in place of the standard C functions
+eliminates issues related to buffer overflow or missing null terminators.
Compatibility
=============
diff --git a/pw_varint/BUILD.gn b/pw_varint/BUILD.gn
index d1aa98c..9b79a5c 100644
--- a/pw_varint/BUILD.gn
+++ b/pw_varint/BUILD.gn
@@ -12,6 +12,7 @@
# License for the specific language governing permissions and limitations under
# the License.
+import("$dir_pw_docgen/docs.gni")
import("$dir_pw_unit_test/test.gni")
config("default_config") {
@@ -39,3 +40,7 @@
"varint_test.cc",
]
}
+
+pw_doc_group("docs") {
+ sources = [ "docs.rst" ]
+}
diff --git a/pw_varint/docs.rst b/pw_varint/docs.rst
new file mode 100644
index 0000000..e4cb746
--- /dev/null
+++ b/pw_varint/docs.rst
@@ -0,0 +1,23 @@
+.. default-domain:: cpp
+
+.. highlight:: sh
+
+---------
+pw_varint
+---------
+The pw_varint module provides functions for encoding and decoding variable
+length integers, or varints. For smaller values, varints require less memory
+than a fixed-size encoding. For example, a 32-bit (4-byte) integer requires 1--5
+bytes when varint-encoded.
+
+`Protocol Buffers <https://developers.google.com/protocol-buffers/docs/encoding#varints>`_
+use a variable-length encoding for integers.
+
+Compatibility
+=============
+* C
+* C++11 (with :doc:`../pw_polyfill/docs`)
+
+Dependencies
+============
+* pw_span
