From fb0e327ca1d4f124725cabc8e5093bc15591469c Mon Sep 17 00:00:00 2001 From: Kayce Basques Date: Fri, 7 Jul 2023 16:46:45 +0000 Subject: [PATCH] pw_sys_io: Doxygenify ReadBytes() Change-Id: I1c5b7eb70a84e3a98ac45b2ab2884915ec0a2e84 Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/154192 Reviewed-by: Kayce Basques Presubmit-Verified: CQ Bot Account Reviewed-by: Wyatt Hepler Commit-Queue: Auto-Submit Pigweed-Auto-Submit: Kayce Basques --- pw_sys_io/docs.rst | 1 + pw_sys_io/public/pw_sys_io/sys_io.h | 26 ++++++++++++++------------ 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/pw_sys_io/docs.rst b/pw_sys_io/docs.rst index f891d0e209..e4df70ea5d 100644 --- a/pw_sys_io/docs.rst +++ b/pw_sys_io/docs.rst @@ -45,6 +45,7 @@ API reference .. doxygenfunction:: pw::sys_io::TryReadByte(std::byte* dest) .. doxygenfunction:: pw::sys_io::WriteByte(std::byte b) .. doxygenfunction:: pw::sys_io::WriteLine(const std::string_view& s) +.. doxygenfunction:: pw::sys_io::ReadBytes(ByteSpan 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 1b25331e49..40e715788c 100644 --- a/pw_sys_io/public/pw_sys_io/sys_io.h +++ b/pw_sys_io/public/pw_sys_io/sys_io.h @@ -97,18 +97,20 @@ Status WriteByte(std::byte b); /// returned as part of the `StatusWithSize`. StatusWithSize WriteLine(const std::string_view& s); -// Fill a byte span from the sys io backend using ReadByte(). -// Implemented by: Facade -// -// This function is implemented by this facade and simply uses ReadByte() to -// read enough bytes to fill the destination span. If there's an error reading a -// byte, the read is aborted and the contents of the destination span are -// undefined. This function blocks until either an error occurs, or all bytes -// are successfully read from the backend's ReadByte() implementation. -// -// Return status is OkStatus() if the destination span was successfully -// filled. In all cases, the number of bytes successuflly read to the -// destination span are returned as part of the StatusWithSize. +/// Fills a byte span from the `pw_sys_io` backend using `ReadByte()`. +/// +/// @pre This function must be implemented by the `pw_sys_io` facade. +/// +/// This function is implemented by the facade and simply uses `ReadByte()` to +/// read enough bytes to fill the destination span. If there's an error reading +/// a byte, the read is aborted and the contents of the destination span are +/// undefined. This function blocks until either an error occurs or all bytes +/// are successfully read from the backend's `ReadByte()` implementation. +/// +/// @returns +/// * @pw_status{OK} if the destination span was successfully filled. In all +/// cases, the number of bytes successuflly read to the destination span are +/// returned as part of the `StatusWithSize`. StatusWithSize ReadBytes(ByteSpan dest); // Write span of bytes out the sys io backend using WriteByte().