docs(timeout): consolidate return-value docs and fix rendering (#292)

[mvandeberg]

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<awaitable_result_t<A>> (which rendered as task<awaitable_result_t[>] because was stripped as an HTML tag) with prose describing the value using io_result<Ts...>, spelling out the success / inner-error / timeout outcomes.
• Capitalize the @throws description ("Any exception ...").
• Fold the lone @Par Precision sentence into the opening paragraph.

[cppalliance-bot]

An automated preview of the documentation is available at https://306.capy.prtest3.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-06-09 17:11:07 UTC

[cppalliance-bot]

GCOVR code coverage report https://306.capy.prtest3.cppalliance.org/gcovr/index.html
LCOV code coverage report https://306.capy.prtest3.cppalliance.org/genhtml/index.html
Coverage Diff Report https://306.capy.prtest3.cppalliance.org/diff-report/index.html

Build time: 2026-06-09 17:23:09 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.44%. Comparing base (ce1c7d7) to head (c82dd56).
⚠️ Report is 2 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #306      +/-   ##
===========================================
- Coverage    96.46%   96.44%   -0.03%     
===========================================
  Files          164      164              
  Lines         8951     8951              
===========================================
- Hits          8635     8633       -2     
- Misses         316      318       +2     

Flag	Coverage Δ
linux	96.58% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
include/boost/capy/timeout.hpp	89.13% <ø> (ø)

... and 2 files with indirect coverage changes

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ce1c7d7...c82dd56. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.