From 3985099a54661443c749a0a45e9839d2302fc49f Mon Sep 17 00:00:00 2001
From: Kayce Basques <kayce@google.com>
Date: Mon, 26 Jun 2023 21:39:40 +0000
Subject: [PATCH] pw_sys_io: Doxygenify TryReadByte()

Change-Id: Ied2e1004d22e62714d32cd308848c178fe4ff89c
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/153190
Reviewed-by: Wyatt Hepler <hepler@google.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>
Reviewed-by: Kayce Basques <kayce@google.com>
Presubmit-Verified: CQ Bot Account <pigweed-scoped@luci-project-accounts.iam.gserviceaccount.com>
Pigweed-Auto-Submit: Kayce Basques <kayce@google.com>
---
 pw_sys_io/docs.rst                  |  1 +
 pw_sys_io/public/pw_sys_io/sys_io.h | 18 +++++++++++-------
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/pw_sys_io/docs.rst b/pw_sys_io/docs.rst
index dbea7fbfa..85962cfc1 100644
--- a/pw_sys_io/docs.rst
+++ b/pw_sys_io/docs.rst
@@ -42,6 +42,7 @@ implementation.
 API reference
 =============
 .. doxygenfunction:: pw::sys_io::ReadByte(std::byte* dest)
+.. doxygenfunction:: pw::sys_io::TryReadByte(std::byte* dest)
 
 Dependencies
 ============
diff --git a/pw_sys_io/public/pw_sys_io/sys_io.h b/pw_sys_io/public/pw_sys_io/sys_io.h
index 5346138eb..bdd185fe0 100644
--- a/pw_sys_io/public/pw_sys_io/sys_io.h
+++ b/pw_sys_io/public/pw_sys_io/sys_io.h
@@ -54,16 +54,20 @@ namespace pw::sys_io {
 /// @warning Do not build production projects on top of `pw_sys_io`.
 ///
 /// @returns
-/// * @pw_status{OK} - A byte was successfully read.
+/// * @pw_status{OK} - A byte was successfully read and is in `dest`.
 /// * @pw_status{RESOURCE_EXHAUSTED} - The underlying source vanished.
 Status ReadByte(std::byte* dest);
 
-// Read a single byte from the sys io backend, if available.
-// Implemented by: Backend
-//
-// Returns OkStatus() - A byte was successfully read, and is in dest.
-//         Status::Unavailable() - No byte is available to read; try later.
-//         Status::Unimplemented() - Not supported on this target.
+/// Reads a single byte from the `pw_sys_io` backend, if available.
+///
+/// @pre This function must be implemented by the `pw_sys_io` backend.
+///
+/// @warning Do not build production projects on top of `pw_sys_io`.
+///
+/// @returns
+/// * @pw_status{OK} - A byte was successfully read and is in `dest`.
+/// * @pw_status{UNAVAILABLE} - No byte is available to read; try later.
+/// * @pw_status{UNIMPLEMENTED} - The function is not supported on this target.
 Status TryReadByte(std::byte* dest);
 
 // Write a single byte out the sys io backend.