From c82dd5603efe1bcf0e85feae154c4955c60e2cfb Mon Sep 17 00:00:00 2001 From: Michael Vandeberg Date: Tue, 9 Jun 2026 10:21:13 -0600 Subject: [PATCH] docs(timeout): consolidate return-value docs and fix rendering (#292) Rewrite the boost::capy::timeout docstring to address reviewer feedback: - Remove the custom @par Return Type block, leaving a single @return ("Return Value") section consistent with delay(). - Replace `@return task>` (which rendered as `task]` because was stripped as an HTML tag) with prose describing the value using io_result, spelling out the success / inner-error / timeout outcomes. - Capitalize the @throws description ("Any exception ..."). - Fold the lone @par Precision sentence into the opening paragraph. --- include/boost/capy/timeout.hpp | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/include/boost/capy/timeout.hpp b/include/boost/capy/timeout.hpp index d6132bf07..a6233b618 100644 --- a/include/boost/capy/timeout.hpp +++ b/include/boost/capy/timeout.hpp @@ -158,21 +158,12 @@ class timeout_launcher complete wins and cancels the other. If the awaitable finishes first, its result is returned as-is (success, error, or exception). If the timer fires first, an `io_result` with - `ec == error::timeout` is produced. + `ec == error::timeout` is produced. The timeout fires at or + after the specified duration. Unlike @ref when_any, exceptions from the inner awaitable are always propagated — they are never swallowed by the timer. - @par Return Type - - Always returns `io_result` matching the inner - awaitable's result type. On timeout, `ec` is set to - `error::timeout` and payload values are default-initialized. - - @par Precision - - The timeout fires at or after the specified duration. - @par Cancellation If the parent's stop token is activated, both children are @@ -192,9 +183,14 @@ class timeout_launcher @param a The awaitable to race against the deadline. @param dur The maximum duration to wait. - @return `task>`. + @return An `io_result` matching the inner awaitable's + result type. On normal completion the inner awaitable's + result is returned unchanged, whether it indicates success + or sets `ec` to an error. On timeout, `ec` is set to + `error::timeout` and the payload values are + default-initialized. - @throws Rethrows any exception from the inner awaitable, + @throws Rethrows Any exception from the inner awaitable, regardless of whether the timer has fired. @see delay, cond::timeout