Add lifetime, ownership, and semantic documentation

- circular_dynamic_buffer: note that copies alias external storage
- slice_of: add @tparam, example, thread safety, lifetime note
- string_dynamic_buffer: add example and invalidation/lifetime note
- strand: document moved-from state on move ctor/assign
- thread_pool::executor_type: document unassociated default state
- io_result<T1,T2> and <T1,T2,T3>: add @tparam and payload semantics
- match_delim::delim: document string_view lifetime requirement

Author: sgerbino

include/boost/capy/buffers/circular_dynamic_buffer.hpp

@@ -70,7 +70,14 @@ class circular_dynamic_buffer
     /// Construct an empty circular buffer with zero capacity.
     circular_dynamic_buffer() = default;
 
-    /// Construct a copy.
+    /** Construct a copy.
+
+        Copies the adapter state (position and length) but does
+        not deep-copy the backing storage. Both objects alias the
+        same external buffer.
+
+        @note The underlying storage must outlive all copies.
+    */
     circular_dynamic_buffer(
         circular_dynamic_buffer const&) = default;
 
@@ -110,7 +117,14 @@ class circular_dynamic_buffer
             detail::throw_invalid_argument();
     }
 
-    /// Assign by copying.
+    /** Assign by copying.
+
+        Copies the adapter state but does not deep-copy the
+        backing storage. Both objects alias the same external
+        buffer afterward.
+
+        @note The underlying storage must outlive all copies.
+    */
     circular_dynamic_buffer& operator=(
         circular_dynamic_buffer const&) = default;
 

include/boost/capy/buffers/slice.hpp

@@ -52,6 +52,24 @@ using slice_type = std::conditional_t<
     kept using the free functions @ref keep_prefix,
     @ref remove_prefix, etc.
 
+    The wrapped sequence is stored by value. The underlying
+    buffer memory must remain valid for the lifetime of the
+    slice.
+
+    @par Thread Safety
+    Distinct objects: Safe.
+    Shared objects: Unsafe.
+
+    @par Example
+    @code
+    mutable_buffer buf(data, 100);
+    auto s = prefix(buf, 50);   // first 50 bytes
+    remove_prefix(s, 10);       // now bytes 10..49
+    @endcode
+
+    @tparam BufferSequence The buffer sequence type, stored
+        by value. Must satisfy @ref ConstBufferSequence.
+
     @see keep_prefix, remove_prefix, prefix, sans_prefix
 */
 template<ConstBufferSequence BufferSequence>

include/boost/capy/buffers/string_dynamic_buffer.hpp

@@ -26,10 +26,25 @@ namespace capy {
     bytes are appended by `prepare` and made readable by
     `commit`.
 
+    @note The wrapped string must outlive this adapter.
+        Calls to `prepare`, `commit`, and `consume`
+        invalidate previously returned buffer views.
+
     @par Thread Safety
     Distinct objects: Safe.
     Shared objects: Unsafe.
 
+    @par Example
+    @code
+    std::string s;
+    auto buf = dynamic_buffer( s, 4096 );
+    auto mb = buf.prepare( 100 );
+    // fill mb with data...
+    buf.commit( 100 );
+    // buf.data() now has 100 readable bytes
+    buf.consume( 50 );
+    @endcode
+
     @tparam CharT The character type.
     @tparam Traits The character traits type.
     @tparam Allocator The allocator type.

include/boost/capy/ex/strand.hpp

@@ -113,6 +113,9 @@ class strand
     strand(strand const&) = default;
 
     /** Construct by moving.
+
+        @note A moved-from strand is only safe to destroy
+            or reassign.
     */
     strand(strand&&) = default;
 
@@ -121,6 +124,9 @@ class strand
     strand& operator=(strand const&) = default;
 
     /** Assign by moving.
+
+        @note A moved-from strand is only safe to destroy
+            or reassign.
     */
     strand& operator=(strand&&) = default;
 

include/boost/capy/ex/thread_pool.hpp

@@ -117,7 +117,12 @@ class thread_pool::executor_type
     }
 
 public:
-    /// Construct a default null executor.
+    /** Construct a default null executor.
+
+        The resulting executor is not associated with any pool.
+        `context()`, `dispatch()`, and `post()` require the
+        executor to be associated with a pool before use.
+    */
     executor_type() = default;
 
     /// Return the underlying thread pool.

include/boost/capy/io_result.hpp

@@ -32,7 +32,12 @@ namespace capy {
     if (ec) { ... }
     @endcode
 
-    @tparam Args Additional value types beyond the error code.
+    @note Only 0, 1, 2, and 3 payload specializations are
+        provided. Payload members are only meaningful when
+        `ec` does not indicate an error.
+
+    @tparam Args Ordered payload types following the leading
+        `std::error_code`.
 */
 template<class... Args>
 struct io_result
@@ -100,7 +105,7 @@ struct [[nodiscard]] io_result<T1>
     /// The error code from the operation.
     std::error_code ec;
 
-    /// The first result value.
+    /// The first payload value. Unspecified when `ec` is set.
     T1 t1{};
 
 #ifdef _MSC_VER
@@ -132,6 +137,19 @@ struct [[nodiscard]] io_result<T1>
 
 /** Result type for operations returning two values.
 
+    Stores a leading `std::error_code` followed by two
+    operation-specific payload values. Inspect `t1` and `t2`
+    only when `ec` does not indicate an error.
+
+    @par Example
+    @code
+    auto [ec, t1, t2] = co_await some_op();
+    if (ec) { ... }
+    @endcode
+
+    @tparam T1 First payload type following the error code.
+    @tparam T2 Second payload type following T1.
+
     @see io_result
 */
 template<typename T1, typename T2>
@@ -140,10 +158,10 @@ struct [[nodiscard]] io_result<T1, T2>
     /// The error code from the operation.
     std::error_code ec;
 
-    /// The first result value.
+    /// The first payload value. Unspecified when `ec` is set.
     T1 t1{};
 
-    /// The second result value.
+    /// The second payload value. Unspecified when `ec` is set.
     T2 t2{};
 
 #ifdef _MSC_VER
@@ -178,6 +196,20 @@ struct [[nodiscard]] io_result<T1, T2>
 
 /** Result type for operations returning three values.
 
+    Stores a leading `std::error_code` followed by three
+    operation-specific payload values. Inspect `t1`, `t2`,
+    and `t3` only when `ec` does not indicate an error.
+
+    @par Example
+    @code
+    auto [ec, t1, t2, t3] = co_await some_op();
+    if (ec) { ... }
+    @endcode
+
+    @tparam T1 First payload type following the error code.
+    @tparam T2 Second payload type following T1.
+    @tparam T3 Third payload type following T2.
+
     @see io_result
 */
 template<typename T1, typename T2, typename T3>
@@ -186,13 +218,13 @@ struct [[nodiscard]] io_result<T1, T2, T3>
     /// The error code from the operation.
     std::error_code ec;
 
-    /// The first result value.
+    /// The first payload value. Unspecified when `ec` is set.
     T1 t1{};
 
-    /// The second result value.
+    /// The second payload value. Unspecified when `ec` is set.
     T2 t2{};
 
-    /// The third result value.
+    /// The third payload value. Unspecified when `ec` is set.
     T3 t3{};
 
 #ifdef _MSC_VER
@@ -230,8 +262,8 @@ struct [[nodiscard]] io_result<T1, T2, T3>
 
 #ifdef _MSC_VER
 
-/// @name Free-standing get() overloads for ADL (MSVC aggregate workaround).
-/// @{
+// Free-standing get() overloads for ADL (MSVC aggregate workaround).
+/// @cond
 
 template<std::size_t I>
 auto& get(io_result<>& r) noexcept
@@ -305,7 +337,7 @@ auto&& get(io_result<T1, T2, T3>&& r) noexcept
     return std::move(r).template get<I>();
 }
 
-/// @}
+/// @endcond
 
 #endif // _MSC_VER
 

include/boost/capy/read_until.hpp

@@ -205,15 +205,21 @@ struct read_until_awaitable
 */
 struct match_delim
 {
-    /// The delimiter string to search for.
+    /** The delimiter string to search for.
+
+        @note The referenced characters must remain valid
+            for the lifetime of this object and any pending
+            read operation.
+    */
     std::string_view delim;
 
     /** Search for the delimiter in `data`.
 
         @param data The data to search.
         @param hint If non-null, receives the overlap hint
             on miss.
-        @return Position past the delimiter, or `npos`.
+        @return `0` if `delim` is empty; otherwise the position
+            just past the delimiter, or `npos` if not found.
     */
     std::size_t
     operator()(