From 39884c8c26fdc711cf3b870aaca1bfbef4aa1d77 Mon Sep 17 00:00:00 2001 From: Wyatt Hepler Date: Thu, 15 Aug 2024 23:04:09 +0000 Subject: [PATCH] pw_status: Convert StatusWithSize to Doxygen MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: I888dcbd7764ead4cd567fe8c183fc8f27d8a55f4 Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/229980 Lint: Lint 🤖 Pigweed-Auto-Submit: Wyatt Hepler Reviewed-by: Alexei Frolov Commit-Queue: Auto-Submit --- docs/BUILD.gn | 1 + pw_status/public/pw_status/status_with_size.h | 93 ++++++++++--------- pw_status/reference.rst | 4 + 3 files changed, 53 insertions(+), 45 deletions(-) diff --git a/docs/BUILD.gn b/docs/BUILD.gn index 509229d413..adef32f86a 100644 --- a/docs/BUILD.gn +++ b/docs/BUILD.gn @@ -284,6 +284,7 @@ _doxygen_input_files = [ # keep-sorted: start "$dir_pw_spi/public/pw_spi/chip_selector.h", "$dir_pw_spi/public/pw_spi/chip_selector_digital_out.h", "$dir_pw_status/public/pw_status/status.h", + "$dir_pw_status/public/pw_status/status_with_size.h", "$dir_pw_status/public/pw_status/try.h", "$dir_pw_stream/public/pw_stream/stream.h", "$dir_pw_stream_uart_linux/public/pw_stream_uart_linux/stream.h", diff --git a/pw_status/public/pw_status/status_with_size.h b/pw_status/public/pw_status/status_with_size.h index f022f6aa40..0e38500a0b 100644 --- a/pw_status/public/pw_status/status_with_size.h +++ b/pw_status/public/pw_status/status_with_size.h @@ -1,4 +1,4 @@ -// Copyright 2020 The Pigweed Authors +// Copyright 2024 The Pigweed Authors // // Licensed under the Apache License, Version 2.0 (the "License"); you may not // use this file except in compliance with the License. You may obtain a copy of @@ -20,31 +20,32 @@ namespace pw { -// StatusWithSize stores a status and an unsigned integer. The integer must not -// exceed StatusWithSize::max_size(), which is 134,217,727 (2**27 - 1) on 32-bit -// systems. -// -// StatusWithSize is useful for reporting the number of bytes read or written in -// an operation along with the status. For example, a function that writes a -// formatted string may want to report both the number of characters written and -// whether it ran out of space. -// -// StatusWithSize is more efficient than its alternatives. It packs a status and -// size into a single word, which can be returned from a function in a register. -// Because they are packed together, the size is limited to max_size(). -// -// StatusWithSize's alternatives result in larger code size. For example: -// -// 1. Return status, pass size output as a pointer argument. -// -// Requires an additional argument and forces the output argument to the -// stack in order to pass an address, increasing code size. -// -// 2. Return an object with Status and size members. -// -// At least for ARMv7-M, the returned struct is created on the stack, which -// increases code size. -// +/// `StatusWithSize` stores a status and an unsigned integer. The integer must +/// not exceed `StatusWithSize::max_size()`, which is 134,217,727 (2**27 - 1) on +/// 32-bit systems. +/// +/// `StatusWithSize` is useful for reporting the number of bytes read or written +/// in an operation along with the status. For example, a function that writes a +/// formatted string may want to report both the number of characters written +/// and whether it ran out of space. +/// +/// `StatusWithSize` is more efficient than its alternatives. It packs a status +/// and size into a single word, which can be returned from a function in a +/// register. Because they are packed together, the size is limited to +/// max_size(). +/// +/// `StatusWithSize`'s alternatives result in larger code size. For example: +/// +/// 1. Return status, pass size output as a pointer argument. +/// +/// Requires an additional argument and forces the output argument to the +/// stack in order to pass an address, increasing code size. +/// +/// 2. Return an object with Status and size members. +/// +/// At least for ARMv7-M, the returned struct is created on the stack, +/// which increases code size. +/// class _PW_STATUS_NO_DISCARD StatusWithSize { public: static constexpr StatusWithSize Cancelled(size_t size = 0) { @@ -96,17 +97,18 @@ class _PW_STATUS_NO_DISCARD StatusWithSize { return StatusWithSize(Status::DataLoss(), size); } - // Creates a StatusWithSize with OkStatus() and a size of 0. + /// Creates a `StatusWithSize` with status `OK` and a size of 0. explicit constexpr StatusWithSize() : size_(0) {} - // Creates a StatusWithSize with status OK and the provided size. - // std::enable_if is used to prevent enum types (e.g. Status) from being used. - // TODO(hepler): Add debug-only assert that size <= max_size(). + /// Creates a `StatusWithSize` with status `OK` and the provided size. + /// `std::enable_if` is used to prevent enum types (e.g. `Status::Code`) from + /// being used. template ::value>> - explicit constexpr StatusWithSize(T size) - : size_(static_cast(size)) {} + explicit constexpr StatusWithSize(T size) : size_(static_cast(size)) { + // TODO(hepler): Add debug-only assert that size <= max_size(). + } - // Creates a StatusWithSize with the provided status and size. + /// Creates a StatusWithSize with the provided status and size. explicit constexpr StatusWithSize(Status status, size_t size) : StatusWithSize((static_cast(status.code()) << kStatusShift) | size) {} @@ -114,13 +116,13 @@ class _PW_STATUS_NO_DISCARD StatusWithSize { constexpr StatusWithSize(const StatusWithSize&) = default; constexpr StatusWithSize& operator=(const StatusWithSize&) = default; - /// ``Update`` s this status and adds to ``size``. + /// `Update` s this status and adds to `size`. /// - /// The resulting ``StatusWithSize`` will have a size of - /// ``this->size() + new_status_with_size.size()`` + /// The resulting `StatusWithSize` will have a size of `this->size() + + /// new_status_with_size.size()` /// - /// The resulting status will be Ok if both statuses are ``Ok``, - /// otherwise it will take on the earliest non-``Ok`` status. + /// The resulting status will be `OK` if both statuses are `OK`, otherwise it + /// will take on the earliest non-`OK` status. constexpr void UpdateAndAdd(StatusWithSize new_status_with_size) { Status new_status; if (ok()) { @@ -132,27 +134,28 @@ class _PW_STATUS_NO_DISCARD StatusWithSize { *this = StatusWithSize(new_status, new_size); } - /// Zeros this size if the status is not ``Ok``. + /// Zeroes the size if the status is not `OK`. constexpr void ZeroIfNotOk() { if (!ok()) { *this = StatusWithSize(status(), 0); } } - // Returns the size. The size is always present, even if status() is an error. + /// Returns the size. The size is always present, even if `status()` is an + /// error. [[nodiscard]] constexpr size_t size() const { return size_ & kSizeMask; } - // The maximum valid value for size. + /// The maximum valid value for size. [[nodiscard]] static constexpr size_t max_size() { return kSizeMask; } - // True if status() == OkStatus(). + /// True if status() == OkStatus(). [[nodiscard]] constexpr bool ok() const { return (size_ & kStatusMask) == 0u; } - // Ignores any errors. This method does nothing except potentially suppress - // complaints from any tools that are checking that errors are not dropped on - // the floor. + /// Ignores any errors. This method does nothing except potentially suppress + /// complaints from any tools that are checking that errors are not dropped on + /// the floor. constexpr void IgnoreError() const {} [[nodiscard]] constexpr Status status() const { diff --git a/pw_status/reference.rst b/pw_status/reference.rst index 5d7bbab7ac..ff83dfd535 100644 --- a/pw_status/reference.rst +++ b/pw_status/reference.rst @@ -373,6 +373,10 @@ C++ API ``PW_STATUS_``. For example, ``PW_STATUS_DATA_LOSS`` corresponds with :c:enumerator:`DATA_LOSS`. +.. doxygenclass:: pw::StatusWithSize + :members: + :undoc-members: + .. doxygendefine:: PW_TRY .. doxygendefine:: PW_TRY_ASSIGN .. doxygendefine:: PW_TRY_WITH_SIZE