pw_assert: Update docs.rst to comply with Style Guide
Change-Id: I03dd829e16bc429a95a1d13925ce834389405731
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/68580
Commit-Queue: Erik Gilling <konkers@google.com>
Reviewed-by: Keir Mierle <keir@google.com>
diff --git a/pw_assert/docs.rst b/pw_assert/docs.rst
index 43a69ac..82a0b99 100644
--- a/pw_assert/docs.rst
+++ b/pw_assert/docs.rst
@@ -38,7 +38,7 @@
PW_CHECK_INT_LE(ItemCount(), 100, "System state: %s", GetStateStr());
Example
--------
+=======
.. code-block:: cpp
@@ -75,8 +75,8 @@
Use ``PW_ASSERT`` from ``pw_assert/assert.h`` for asserts in headers or
asserting in ``constexpr`` contexts.
-Structure of assert modules
----------------------------
+Structure of Assert Modules
+===========================
The module is split into two components:
1. The **facade** (this module) which is only a macro interface layer, and
@@ -415,7 +415,7 @@
expression, or anything other than a binary indication of failure**.
Example
--------
+=======
.. code-block:: cpp
@@ -437,8 +437,8 @@
}
};
-PW_ASSERT API reference
------------------------
+PW_ASSERT API Reference
+=======================
.. cpp:function:: PW_ASSERT(condition)
A header- and constexpr-safe version of ``PW_CHECK()``.
@@ -464,16 +464,16 @@
Use ``PW_CHECK_*()`` whenever possible.
-PW_ASSERT API backend
----------------------
+PW_ASSERT API Backend
+=====================
The ``PW_ASSERT`` API ultimately calls the C function
``pw_assert_HandleFailure()``, which must be provided by the ``pw_assert``
backend. The ``pw_assert_HandleFailure()`` function must not return.
.. _module-pw_assert-circular-deps:
-Avoiding circular dependencies with ``PW_ASSERT``
--------------------------------------------------
+Avoiding Circular Dependencies With ``PW_ASSERT``
+=================================================
Because asserts are so widely used, including in low-level libraries, it is
common for the ``pw_assert`` backend to cause circular dependencies. Because of
this, assert backends may avoid declaring explicit dependencies, instead relying
@@ -500,7 +500,6 @@
-----------
Backend API
-----------
-
The backend controls what to do in the case of an assertion failure. In the
most basic cases, the backend could display the assertion failure on something
like sys_io and halt in a while loop waiting for a debugger. In other cases,
@@ -582,8 +581,8 @@
file, expression, or other rich assert information. Backends should do
something reasonable in this case; typically, capturing the stack is useful.
-Backend build targets
----------------------
+Backend Build Targets
+=====================
In GN, the backend must provide a ``pw_assert.impl`` build target in the same
directory as the backend target. If the main backend target's dependencies would
cause dependency cycles, the actual backend implementation with its full
@@ -593,11 +592,11 @@
:ref:`module-pw_assert-circular-deps`.
--------------------------
-Frequently asked questions
+Frequently Asked Questions
--------------------------
When should DCHECK_* be used instead of CHECK_* and vice versa?
----------------------------------------------------------------
+===============================================================
There is no hard and fast rule for when to use one or the other.
In theory, ``DCHECK_*`` macros should never be used and all the asserts should
@@ -646,7 +645,7 @@
mistake; so use error codes in those cases instead.
How should objects be asserted against or compared?
----------------------------------------------------
+===================================================
Unfortunately, there is no native mechanism for this, and instead the way to
assert object states or comparisons is with the normal ``PW_CHECK_*`` macros
that operate on booleans, ints, and floats.
@@ -660,7 +659,7 @@
object assert API won't be added.
Why was the assert facade designed this way?
---------------------------------------------
+============================================
The Pigweed assert API was designed taking into account the needs of several
past projects the team members were involved with. Based on those experiences,
the following were key requirements for the API:
@@ -693,7 +692,7 @@
asserting in that case, rather than terminating at a C-style API.
Why isn't there a ``PW_CHECK_LE``? Why is the type (e.g. ``INT``) needed?
--------------------------------------------------------------------------
+=========================================================================
The problem with asserts like ``PW_CHECK_LE(a, b)`` instead of
``PW_CHECK_INT_LE(a, b)`` or ``PW_CHECK_FLOAT_EXACT_LE(a, b)`` is that to
capture the arguments with the tokenizer, we need to know the types. Using the
@@ -717,8 +716,8 @@
Below is a brief summary of what modules are ready for use:
-Available assert backends
--------------------------
+Available Assert Backends
+=========================
- ``pw_assert`` - **Stable** - The assert facade (this module). This module is
stable, and in production use. The documentation is comprehensive and covers
the functionality. There are (a) tests for the facade macro processing logic,
@@ -738,8 +737,8 @@
``pw_assert_log`` in combination with ``pw_log_null``. This will direct asserts
to logs, then the logs are removed due to the null backend.
-Missing functionality
----------------------
+Missing Functionality
+=====================
- **Stack traces** - Pigweed doesn't have a reliable stack walker, which makes
displaying a stack trace on crash harder. We plan to add this eventually.
- **Snapshot integration** - Pigweed doesn't yet have a rich system state
