pw_docs: Fixup minor typos, add clarifications * pw_preprocessor: Fix a typo in the example code * Correct a few spelling/grammar mistakes * Clarify intent in a couple spots Signed-off-by: Shiva Rajagopal <shivarajagopal@google.com> Change-Id: I3aebc82d219848e884408658eb8e48f3f8fe651d Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/44681 Reviewed-by: Armando Montanez <amontanez@google.com>
diff --git a/pw_assert/docs.rst b/pw_assert/docs.rst index 9a03d64..aa43ca5 100644 --- a/pw_assert/docs.rst +++ b/pw_assert/docs.rst
@@ -12,7 +12,7 @@ defensive programming that can lead to more reliable and less buggy code. The assert API facilitates flexible crash handling through Pigweed's facade -mechanism. The API is desigend to enable features like: +mechanism. The API is designed to enable features like: - Optional ancillary printf-style messages along assertions - Capturing actual values of binary operator assertions like ``a < b`` @@ -649,12 +649,12 @@ How should objects be asserted against or compared? --------------------------------------------------- -Unfortunatly, there is no native mechanism for this, and instead the way to +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. This is due to the requirement of supporting C and also tokenization. It may be -possible support rich object comparions by defining a convention for +possible support rich object comparisons by defining a convention for stringifying objects; however, this hasn't been added yet. Additionally, such a mechanism would not work well with tokenization. In particular, it would require runtime stringifying arguments and rendering them with ``%s``, which
diff --git a/pw_boot_armv7m/docs.rst b/pw_boot_armv7m/docs.rst index d00bec4..48bd3e4 100644 --- a/pw_boot_armv7m/docs.rst +++ b/pw_boot_armv7m/docs.rst
@@ -51,7 +51,7 @@ - ``int main()``: This is where applications reside. - ``void pw_boot_PreStaticMemoryInit()``: This function executes just before - static memory has been zerod and static data is intialized. This function + static memory has been zeroed and static data is intialized. This function should set up any early initialization that should be done before static memory is initialized, such as:
diff --git a/pw_fuzzer/docs.rst b/pw_fuzzer/docs.rst index fb406e1..a221e2b 100644 --- a/pw_fuzzer/docs.rst +++ b/pw_fuzzer/docs.rst
@@ -48,7 +48,7 @@ When writing you fuzz target function, you may want to consider: -- It is acceptable to return early if the input doesn't mean some constraints, +- It is acceptable to return early if the input doesn't meet some constraints, e.g. it is too short. - If your fuzzer accepts data with a well-defined format, you can bootstrap coverage by crafting examples and adding them to a `corpus`_.
diff --git a/pw_kvs/docs.rst b/pw_kvs/docs.rst index 7504566..29b3848 100644 --- a/pw_kvs/docs.rst +++ b/pw_kvs/docs.rst
@@ -49,7 +49,7 @@ entries for that key are not modified or removed from flash storage, until garbage collection reclaims the “stale” entries. -`Garbage collection`_ is done by coping any currently valid KV entries in the +`Garbage collection`_ is done by copying any currently valid KV entries in the sector to be garbage collected to a different sector and then erasing the sector.
diff --git a/pw_metric/docs.rst b/pw_metric/docs.rst index 6bdcd5a..2b9d20e 100644 --- a/pw_metric/docs.rst +++ b/pw_metric/docs.rst
@@ -150,7 +150,7 @@ UART). In those cases, metrics provide a low-overhead approach to understand what is happening. During early boot, metrics can be incremented, then after boot dumping the metrics provides insights into what happened. While basic - counter variables can work in these contexts to, one still has to deal with + counter variables can work in these contexts too, one still has to deal with the offloading problem; which the library handles. --------------------- @@ -308,7 +308,7 @@ } You can also put a metric into a group with the macro. Metrics can belong to - strictly one group, otherwise a assertion will fail. Example: + strictly one group, otherwise an assertion will fail. Example: .. code:: @@ -653,7 +653,7 @@ "/i2c1/gyro/resets": 24, "/i2c1/gyro/hangs": 1, "/spi1/thermocouple/reads": 242, - "/spi1/thermocouple/temp_celcius": 34.52, + "/spi1/thermocouple/temp_celsius": 34.52, } Note that there is no nesting of the groups; the nesting is implied from the @@ -717,8 +717,8 @@ Calls to is ``MetricService::Get`` are blocking and will send all metrics immediately, even though it is a server-streaming RPC. This will work fine if - the device doesn't have too many metics, or doesn't have concurrent RPCs like - logging, but could be a problem in some cases. + the device doesn't have too many metrics, or doesn't have concurrent RPCs + like logging, but could be a problem in some cases. We plan to offer an async version where the application is responsible for pumping the metrics into the streaming response. This gives flow control to @@ -818,7 +818,7 @@ metrics are enabled or disabled at compile time. This may rely on of C++20's support for zero-sized members to fully remove the cost. -- **Async RCPC** - The current RPC service exports the metrics by streaming +- **Async RPC** - The current RPC service exports the metrics by streaming them to the client in batches. However, the current solution streams all the metrics to completion; this may block the RPC thread. In the future we will have an async solution where the user is in control of flow priority.
diff --git a/pw_package/docs.rst b/pw_package/docs.rst index b3055db..24037e5 100644 --- a/pw_package/docs.rst +++ b/pw_package/docs.rst
@@ -32,7 +32,7 @@ ``--force`` to remove the package before installing. ``pw package status <package-name>`` - Indicates whether ``<packagxe-name>`` is installed. + Indicates whether ``<package-name>`` is installed. ``pw package remove <package-name>`` Removes ``<package-name>``.
diff --git a/pw_persistent_ram/docs.rst b/pw_persistent_ram/docs.rst index 71b9935..ef99710 100644 --- a/pw_persistent_ram/docs.rst +++ b/pw_persistent_ram/docs.rst
@@ -75,8 +75,8 @@ are initialized in RAM. The preferred way to clear Persistent RAM is to simply zero entire persistent -RAM sections and/or memory regions. Pigweed's persistents containers have picked -integrity checks which work with zerod memory, meaning they do not hold a value +RAM sections and/or memory regions. Pigweed's persistent containers have picked +integrity checks which work with zeroed memory, meaning they do not hold a value after zeroing. Alternatively containers can be individually cleared. The boot sequence itself is tightly coupled to the number of persistent sections
diff --git a/pw_preprocessor/docs.rst b/pw_preprocessor/docs.rst index 3f5b13c..03d22bb 100644 --- a/pw_preprocessor/docs.rst +++ b/pw_preprocessor/docs.rst
@@ -30,12 +30,12 @@ .. code-block:: cpp #define ARG_PRINT(...) PW_DELEGATE_BY_ARG_COUNT(_ARG_PRINT, __VA_ARGS__) - #define _ARG_PRINT_0(a) LOG_INFO("nothing!") - #define _ARG_PRINT_1(a) LOG_INFO("1 arg: %s", a) - #define _ARG_PRINT_2(a, b) LOG_INFO("2 args: %s, %s", a, b) - #define _ARG_PRINT_3(a, b, c) LOG_INFO("3 args: %s, %s, %s", a, b, c) + #define _ARG_PRINT0(a) LOG_INFO("nothing!") + #define _ARG_PRINT1(a) LOG_INFO("1 arg: %s", a) + #define _ARG_PRINT2(a, b) LOG_INFO("2 args: %s, %s", a, b) + #define _ARG_PRINT3(a, b, c) LOG_INFO("3 args: %s, %s, %s", a, b, c) - When used, ``ARG_PRINT`` expands to the ``_ARG_PRINT_#`` macro corresponding + When used, ``ARG_PRINT`` expands to the ``_ARG_PRINT#`` macro corresponding to the number of arguments. .. code-block:: cpp
diff --git a/pw_sys_io/docs.rst b/pw_sys_io/docs.rst index 3a1a6c4..eaf60ba 100644 --- a/pw_sys_io/docs.rst +++ b/pw_sys_io/docs.rst
@@ -30,7 +30,7 @@ ===== This module requires relatively minimal setup: - 1. Chose a ``pw_sys_io`` backend, or write one yourself. + 1. Choose a ``pw_sys_io`` backend, or write one yourself. 2. If using GN build, Specify the ``pw_sys_io_BACKEND`` GN build arg to point the library that provides a ``pw_sys_io`` backend.
diff --git a/pw_trace/docs.rst b/pw_trace/docs.rst index 60aa359..30cf831 100644 --- a/pw_trace/docs.rst +++ b/pw_trace/docs.rst
@@ -280,7 +280,7 @@ ---------------------- Python Trace Generator ---------------------- -The Python tool is still in early developments, but currently it supports +The Python tool is still in early development, but currently it supports generating a list of json lines from a list of trace events. To view the trace, these lines can be saved to a file and loaded into
diff --git a/pw_trace_tokenized/docs.rst b/pw_trace_tokenized/docs.rst index c1c27ac..82034dc 100644 --- a/pw_trace_tokenized/docs.rst +++ b/pw_trace_tokenized/docs.rst
@@ -16,7 +16,7 @@ This module is currently in development, and is therefore still undergoing significant changes. -Future work will add: +Future work will: 1. Add a more complete API for how to retrieve data from ring_buffer. 2. Add a Python library to decode the trace data. @@ -60,7 +60,7 @@ --------- Macro API --------- -All code should use the trace API facade directly, this backend fully +All code should use the trace API facade directly. This backend fully implements all features of the tracing facade. @@ -139,7 +139,7 @@ ----------- Time source ----------- -Tracing rquires the platform to provide the time source for tracing, this can +Tracing requires the platform to provide the time source for tracing, this can be done in one of a few ways. 1. Create a file with the default time functions, and provide as build variable @@ -159,7 +159,7 @@ ------ The optional trace buffer adds a ring buffer which contains the encoded trace data. This is still a work in progress, in particular better methods for -retireving the data still needs to be added. Currently there is an accessor for +retrieving the data still need to be added. Currently there is an accessor for the underlying ring buffer object, but this is a short term solution. .. cpp:function:: void ClearBuffer()