From 7700088eb07f9275e2f688beeed7755f65e414c5 Mon Sep 17 00:00:00 2001
From: Kayce Basques <kayce@google.com>
Date: Fri, 5 May 2023 15:21:18 +0000
Subject: [PATCH] docs: Doxygenify pw::hdlc::Decoder

Change-Id: Ia08ea167dcb31a837fefa4eb30bd286373264cae
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/145210
Reviewed-by: Chad Norvell <chadnorvell@google.com>
Reviewed-by: Alexei Frolov <frolv@google.com>
Pigweed-Auto-Submit: Kayce Basques <kayce@google.com>
Presubmit-Verified: CQ Bot Account <pigweed-scoped@luci-project-accounts.iam.gserviceaccount.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>
Reviewed-by: Kayce Basques <kayce@google.com>
---
 docs/BUILD.gn                    |  1 +
 pw_hdlc/api.rst                  | 22 +++-------------------
 pw_hdlc/public/pw_hdlc/decoder.h | 26 +++++++++++++-------------
 3 files changed, 17 insertions(+), 32 deletions(-)

diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index 6f98883021..403b7bb909 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -128,6 +128,7 @@ _doxygen_input_files = [
   "$dir_pw_chrono/public/pw_chrono/system_clock.h",
   "$dir_pw_chrono/public/pw_chrono/system_timer.h",
   "$dir_pw_function/public/pw_function/scope_guard.h",
+  "$dir_pw_hdlc/public/pw_hdlc/decoder.h",
   "$dir_pw_log_tokenized/public/pw_log_tokenized/handler.h",
   "$dir_pw_log_tokenized/public/pw_log_tokenized/metadata.h",
   "$dir_pw_rpc/public/pw_rpc/internal/config.h",
diff --git a/pw_hdlc/api.rst b/pw_hdlc/api.rst
index af3dbf4e61..6f6ad8d83a 100644
--- a/pw_hdlc/api.rst
+++ b/pw_hdlc/api.rst
@@ -87,29 +87,13 @@ unnumbered information frame.
 Decoder
 =======
 
+
 .. tabs::
 
    .. group-tab:: C++
 
-      .. cpp:class:: pw::hdlc::Decoder
-
-        .. cpp:function:: pw::Result<Frame> Process(std::byte b)
-
-           Parses a single byte of an HDLC stream. Returns a Result with the complete
-           frame if the byte completes a frame. The status is the following:
-
-           - OK - A frame was successfully decoded. The Result contains the Frame,
-             which is invalidated by the next Process call.
-           - UNAVAILABLE - No frame is available.
-           - RESOURCE_EXHAUSTED - A frame completed, but it was too large to fit in
-             the decoder's buffer.
-           - DATA_LOSS - A frame completed, but it was invalid. The frame was
-             incomplete or the frame check sequence verification failed.
-
-        .. cpp:function:: void Process(pw::ConstByteSpan data, F&& callback, Args&&... args)
-
-           Processes a span of data and calls the provided callback with each frame or
-           error.
+      .. doxygenclass:: pw::hdlc::Decoder
+         :members:
 
       Example:
 
diff --git a/pw_hdlc/public/pw_hdlc/decoder.h b/pw_hdlc/public/pw_hdlc/decoder.h
index 0290a2ad87..30956c828e 100644
--- a/pw_hdlc/public/pw_hdlc/decoder.h
+++ b/pw_hdlc/public/pw_hdlc/decoder.h
@@ -75,17 +75,17 @@ class Decoder {
   Decoder(const Decoder&) = delete;
   Decoder& operator=(const Decoder&) = delete;
 
-  // Parses a single byte of an HDLC stream. Returns a Result with the complete
-  // frame if the byte completes a frame. The status is the following:
-  //
-  //     OK - A frame was successfully decoded. The Result contains the Frame,
-  //         which is invalidated by the next Process call.
-  //     UNAVAILABLE - No frame is available.
-  //     RESOURCE_EXHAUSTED - A frame completed, but it was too large to fit in
-  //         the decoder's buffer.
-  //     DATA_LOSS - A frame completed, but it was invalid. The frame was
-  //         incomplete or the frame check sequence verification failed.
-  //
+  /// @brief Parses a single byte of an HDLC stream.
+  ///
+  /// @returns A `pw::Result` with the complete frame if the byte completes a
+  /// frame. The status can be one of the following:
+  /// * `OK` - A frame was successfully decoded. The `Result` contains the
+  /// `Frame`, which is invalidated by the next `Process()` call.
+  /// * `UNAVAILABLE` - No frame is available.
+  /// * `RESOURCE_EXHAUSTED` - A frame completed, but it was too large to fit in
+  ///   the decoder's buffer.
+  /// * `DATA_LOSS` - A frame completed, but it was invalid. The frame was
+  ///   incomplete or the frame check sequence verification failed.
   Result<Frame> Process(std::byte new_byte);
 
   // Returns the buffer space required for a `Decoder` to successfully decode a
@@ -99,8 +99,8 @@ class Decoder {
                : max_frame_size - 2;
   }
 
-  // Processes a span of data and calls the provided callback with each frame or
-  // error.
+  /// @brief Processes a span of data and calls the provided callback with each
+  /// frame or error.
   template <typename F, typename... Args>
   void Process(ConstByteSpan data, F&& callback, Args&&... args) {
     for (std::byte b : data) {