pw_sys_io: Doxygenify ReadByte()

Change-Id: I7c0154f7310531bb607c1fbe6b3fab59d2e6e654
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/152075
Reviewed-by: Wyatt Hepler <hepler@google.com>
Pigweed-Auto-Submit: Kayce Basques <kayce@google.com>
Reviewed-by: Kayce Basques <kayce@google.com>
Commit-Queue: Kayce Basques <kayce@google.com>

docs/BUILD.gn

@@ -150,20 +150,21 @@ _doxygen_input_files = [
  "$dir_pw_string/public/pw_string/string.h",
  "$dir_pw_function/public/pw_function/function.h",
  "$dir_pw_function/public/pw_function/pointer.h",
+ "$dir_pw_status/public/pw_status/status.h",
  "$dir_pw_string/public/pw_string/string_builder.h",
  "$dir_pw_string/public/pw_string/util.h",
  "$dir_pw_sync/public/pw_sync/binary_semaphore.h",
  "$dir_pw_sync/public/pw_sync/borrow.h",
  "$dir_pw_sync/public/pw_sync/counting_semaphore.h",
  "$dir_pw_sync/public/pw_sync/inline_borrowable.h",
- "$dir_pw_status/public/pw_status/status.h",
  "$dir_pw_sync/public/pw_sync/interrupt_spin_lock.h",
  "$dir_pw_sync/public/pw_sync/lock_annotations.h",
  "$dir_pw_sync/public/pw_sync/mutex.h",
  "$dir_pw_sync/public/pw_sync/thread_notification.h",
  "$dir_pw_sync/public/pw_sync/timed_mutex.h",
  "$dir_pw_sync/public/pw_sync/timed_thread_notification.h",
  "$dir_pw_sync/public/pw_sync/virtual_basic_lockable.h",
+ "$dir_pw_sys_io/public/pw_sys_io/sys_io.h",
  "$dir_pw_thread/public/pw_thread/test_thread_context.h",
  "$dir_pw_tokenizer/public/pw_tokenizer/encode_args.h",
  "$dir_pw_tokenizer/public/pw_tokenizer/tokenize.h",

pw_sys_io/docs.rst

@@ -39,6 +39,10 @@ Module usage
 See backend docs for how to interact with the underlying system I/O
 implementation.
 
+API reference
+=============
+.. doxygenfunction:: pw::sys_io::ReadByte(std::byte* dest)
+
 Dependencies
 ============
  * pw_sys_io_backend

pw_sys_io/public/pw_sys_io/sys_io.h

@@ -45,14 +45,17 @@
 
 namespace pw::sys_io {
 
-// Read a single byte from the sys io backend.
-// Implemented by: Backend
-//
-// This function will block until it either succeeds or fails to read a byte
-// from the pw_sys_io backend.
-//
-// Returns OkStatus() - A byte was successfully read.
-// Status::ResourceExhausted() - if the underlying source vanished.
+/// Reads a single byte from the `pw_sys_io` backend.
+/// This function blocks until it either succeeds or fails to read a
+/// byte.
+///
+/// @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.
+/// * @pw_status{RESOURCE_EXHAUSTED} - The underlying source vanished.
 Status ReadByte(std::byte* dest);
 
 // Read a single byte from the sys io backend, if available.