pw_tokenizer: Migrate the custom macro example (SEED-0102)
Change-Id: I5e820d93bad103709eac48a19b8c18a318011384
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/157032
Presubmit-Verified: CQ Bot Account <pigweed-scoped@luci-project-accounts.iam.gserviceaccount.com>
Pigweed-Auto-Submit: Kayce Basques <kayce@google.com>
Reviewed-by: Carlos Chinchilla <cachinchilla@google.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed-service-accounts.iam.gserviceaccount.com>
Reviewed-by: Kayce Basques <kayce@google.com>
diff --git a/pw_tokenizer/docs.rst b/pw_tokenizer/docs.rst
index be3898b..b802e95 100644
--- a/pw_tokenizer/docs.rst
+++ b/pw_tokenizer/docs.rst
@@ -54,72 +54,6 @@
See :ref:`module-pw_tokenizer-api-tokenization` in the API reference
for detailed information about the tokenization API.
-Example: tokenize a message with arguments in a custom macro
-============================================================
-The following example implements a custom tokenization macro similar to
-:ref:`module-pw_log_tokenized`.
-
-.. code-block:: cpp
-
- #include "pw_tokenizer/tokenize.h"
-
- #ifndef __cplusplus
- extern "C" {
- #endif
-
- void EncodeTokenizedMessage(uint32_t metadata,
- pw_tokenizer_Token token,
- pw_tokenizer_ArgTypes types,
- ...);
-
- #ifndef __cplusplus
- } // extern "C"
- #endif
-
- #define PW_LOG_TOKENIZED_ENCODE_MESSAGE(metadata, format, ...) \
- do { \
- PW_TOKENIZE_FORMAT_STRING( \
- PW_TOKENIZER_DEFAULT_DOMAIN, UINT32_MAX, format, __VA_ARGS__); \
- EncodeTokenizedMessage(payload, \
- _pw_tokenizer_token, \
- PW_TOKENIZER_ARG_TYPES(__VA_ARGS__) \
- PW_COMMA_ARGS(__VA_ARGS__)); \
- } while (0)
-
-In this example, the ``EncodeTokenizedMessage`` function would handle encoding
-and processing the message. Encoding is done by the
-:cpp:class:`pw::tokenizer::EncodedMessage` class or
-:cpp:func:`pw::tokenizer::EncodeArgs` function from
-``pw_tokenizer/encode_args.h``. The encoded message can then be transmitted or
-stored as needed.
-
-.. code-block:: cpp
-
- #include "pw_log_tokenized/log_tokenized.h"
- #include "pw_tokenizer/encode_args.h"
-
- void HandleTokenizedMessage(pw::log_tokenized::Metadata metadata,
- pw::span<std::byte> message);
-
- extern "C" void EncodeTokenizedMessage(const uint32_t metadata,
- const pw_tokenizer_Token token,
- const pw_tokenizer_ArgTypes types,
- ...) {
- va_list args;
- va_start(args, types);
- pw::tokenizer::EncodedMessage<> encoded_message(token, types, args);
- va_end(args);
-
- HandleTokenizedMessage(metadata, encoded_message);
- }
-
-.. admonition:: Why use a custom macro
-
- - Optimal code size. Invoking a free function with the tokenized data results
- in the smallest possible call site.
- - Pass additional arguments, such as metadata, with the tokenized message.
- - Integrate ``pw_tokenizer`` with other systems.
-
Binary logging with pw_tokenizer
================================
String tokenization can be used to convert plain text logs to a compact,
diff --git a/pw_tokenizer/guides.rst b/pw_tokenizer/guides.rst
index 0c461c0..1db5d06 100644
--- a/pw_tokenizer/guides.rst
+++ b/pw_tokenizer/guides.rst
@@ -60,6 +60,63 @@
``pw_tokenizer_zephyr.ld`` which is added to the end of the linker file
via a call to ``zephyr_linker_sources(SECTIONS ...)``.
+.. _module-pw_tokenizer-tokenization-guides:
+
+-------------------
+Tokenization guides
+-------------------
+
+Tokenize a message with arguments in a custom macro
+===================================================
+The following example implements a custom tokenization macro similar to
+:ref:`module-pw_log_tokenized`.
+
+.. code-block:: cpp
+
+ #include "pw_tokenizer/tokenize.h"
+
+ #ifndef __cplusplus
+ extern "C" {
+ #endif
+
+ void EncodeTokenizedMessage(uint32_t metadata,
+ pw_tokenizer_Token token,
+ pw_tokenizer_ArgTypes types,
+ ...);
+
+ #ifndef __cplusplus
+ } // extern "C"
+ #endif
+
+ #define PW_LOG_TOKENIZED_ENCODE_MESSAGE(metadata, format, ...) \
+ do { \
+ PW_TOKENIZE_FORMAT_STRING( \
+ PW_TOKENIZER_DEFAULT_DOMAIN, UINT32_MAX, format, __VA_ARGS__); \
+ EncodeTokenizedMessage(payload, \
+ _pw_tokenizer_token, \
+ PW_TOKENIZER_ARG_TYPES(__VA_ARGS__) \
+ PW_COMMA_ARGS(__VA_ARGS__)); \
+ } while (0)
+
+In this example, the ``EncodeTokenizedMessage`` function would handle encoding
+and processing the message. Encoding is done by the
+:cpp:class:`pw::tokenizer::EncodedMessage` class or
+:cpp:func:`pw::tokenizer::EncodeArgs` function from
+``pw_tokenizer/encode_args.h``. The encoded message can then be transmitted or
+stored as needed.
+
+.. code-block:: cpp
+
+ #include "pw_log_tokenized/log_tokenized.h"
+ #include "pw_tokenizer/encode_args.h"
+
+ void HandleTokenizedMessage(pw::log_tokenized::Metadata metadata,
+ pw::span<std::byte> message);
+
+ extern "C" void EncodeTokenizedMessage(const uint32_t metadata,
+ const pw_tokenizer_Token token,
+ const pw_tokenizer_ArgTypes types,
+
.. _module-pw_tokenizer-base64-guides:
-------------
