Complete Javadoc coverage and rule compliance for public headers

Add missing Javadoc to undocumented public declarations across
buffers, io_result, read_until, cond, error, and concept headers.
Fix rule compliance: correct section order (@Par before @tparam),
rename @Par Usage to @Par Example, and standardize brief verbs
(constructors start with "Construct", assignments with "Assign").

Author: sgerbino

include/boost/capy/buffers.hpp

@@ -74,11 +74,11 @@ class mutable_buffer
     /// Construct an empty buffer.
     mutable_buffer() = default;
 
-    /// Copy constructor.
+    /// Construct a copy.
     mutable_buffer(
         mutable_buffer const&) = default;
 
-    /// Copy assignment.
+    /// Assign by copying.
     mutable_buffer& operator=(
         mutable_buffer const&) = default;
 
@@ -166,10 +166,10 @@ class const_buffer
     /// Construct an empty buffer.
     const_buffer() = default;
 
-    /// Copy constructor.
+    /// Construct a copy.
     const_buffer(const_buffer const&) = default;
 
-    /// Copy assignment.
+    /// Assign by copying.
     const_buffer& operator=(
         const_buffer const& other) = default;
 

include/boost/capy/buffers/buffer_array.hpp

@@ -65,18 +65,17 @@ buffer_array_keep_prefix(
     It provides efficient storage for small buffer sequences
     without dynamic allocation.
 
-    @tparam N Maximum number of buffers the array can hold.
-    @tparam IsConst If true, holds const_buffer; otherwise mutable_buffer.
-
-    @par Usage
-
+    @par Example
     @code
     void process(ConstBufferSequence auto const& buffers)
     {
         const_buffer_array<4> bufs(buffers);
         // use bufs.begin(), bufs.end(), bufs.to_span()
     }
     @endcode
+
+    @tparam N Maximum number of buffers the array can hold.
+    @tparam IsConst If true, holds const_buffer; otherwise mutable_buffer.
 */
 template<std::size_t N, bool IsConst>
 class buffer_array
@@ -95,7 +94,7 @@ class buffer_array
     };
 
 public:
-    /** Default constructor.
+    /** Construct a default instance.
 
         Constructs an empty buffer array.
     */
@@ -104,7 +103,7 @@ class buffer_array
     {
     }
 
-    /** Copy constructor.
+    /** Construct a copy.
     */
     buffer_array(buffer_array const& other) noexcept
         : n_(other.n_)
@@ -252,7 +251,7 @@ class buffer_array
             arr_[n_].~value_type();
     }
 
-    /** Copy assignment.
+    /** Assign by copying.
     */
     buffer_array&
     operator=(buffer_array const& other) noexcept

include/boost/capy/buffers/buffer_pair.hpp

@@ -21,6 +21,7 @@ namespace capy {
 */
 using const_buffer_pair = std::array<const_buffer,2>;
 
+/// Slice customization point for const_buffer_pair.
 BOOST_CAPY_DECL
 void
 tag_invoke(
@@ -33,6 +34,7 @@ tag_invoke(
 */
 using mutable_buffer_pair = std::array<mutable_buffer,2>;
 
+/// Slice customization point for mutable_buffer_pair.
 BOOST_CAPY_DECL
 void
 tag_invoke(

include/boost/capy/buffers/buffer_param.hpp

@@ -67,7 +67,7 @@ namespace capy {
     @ref max_size buffer descriptors, automatically refilling
     from the underlying sequence as buffers are consumed.
 
-    @par Usage
+    @par Example
 
     Create a `buffer_param` from any buffer sequence and use
     `data()` to get the current window of buffers. After

include/boost/capy/buffers/circular_dynamic_buffer.hpp

@@ -70,7 +70,7 @@ class circular_dynamic_buffer
     /// Construct an empty circular buffer with zero capacity.
     circular_dynamic_buffer() = default;
 
-    /// Copy constructor.
+    /// Construct a copy.
     circular_dynamic_buffer(
         circular_dynamic_buffer const&) = default;
 
@@ -110,7 +110,7 @@ class circular_dynamic_buffer
             detail::throw_invalid_argument();
     }
 
-    /// Copy assignment.
+    /// Assign by copying.
     circular_dynamic_buffer& operator=(
         circular_dynamic_buffer const&) = default;
 

include/boost/capy/buffers/consuming_buffers.hpp

@@ -129,6 +129,7 @@ class consuming_buffers
         // Default constructor required for forward_iterator
         const_iterator() noexcept = default;
 
+        /// Construct from position and consumed byte count.
         const_iterator(
             iterator_type it,
             end_iterator_type end,
@@ -139,17 +140,19 @@ class consuming_buffers
         {
         }
 
+        /// Test for equality.
         bool operator==(const_iterator const& other) const noexcept
         {
             return it_ == other.it_ && consumed_ == other.consumed_;
         }
 
-        // != operator required for equality_comparable
+        /// Test for inequality.
         bool operator!=(const_iterator const& other) const noexcept
         {
             return !(*this == other);
         }
 
+        /// Return the current buffer, adjusted for consumed bytes.
         value_type operator*() const noexcept
         {
             auto const& buf = *it_;
@@ -167,20 +170,23 @@ class consuming_buffers
             }
         }
 
+        /// Advance to the next element.
         const_iterator& operator++() noexcept
         {
             consumed_ = 0;
             ++it_;
             return *this;
         }
 
+        /// Advance to the next element (postfix).
         const_iterator operator++(int) noexcept
         {
             const_iterator tmp = *this;
             ++*this;
             return tmp;
         }
 
+        /// Move to the previous element.
         const_iterator& operator--() noexcept
         {
             if (consumed_ == 0)
@@ -201,6 +207,7 @@ class consuming_buffers
             return *this;
         }
 
+        /// Move to the previous element (postfix).
         const_iterator operator--(int) noexcept
         {
             const_iterator tmp = *this;

include/boost/capy/buffers/flat_dynamic_buffer.hpp

@@ -89,11 +89,11 @@ class flat_dynamic_buffer
             detail::throw_invalid_argument();
     }
 
-    /// Copy constructor.
+    /// Construct a copy.
     flat_dynamic_buffer(
         flat_dynamic_buffer const&) = default;
 
-    /// Copy assignment.
+    /// Assign by copying.
     flat_dynamic_buffer& operator=(
         flat_dynamic_buffer const&) = default;
 

include/boost/capy/buffers/front.hpp

@@ -20,6 +20,7 @@ namespace capy {
 */
 constexpr struct front_mrdocs_workaround_t
 {
+    /// Return the first mutable buffer, or an empty buffer.
     template<MutableBufferSequence MutableBufferSequence>
     mutable_buffer
     operator()(
@@ -31,6 +32,7 @@ constexpr struct front_mrdocs_workaround_t
         return {};
     }
 
+    /// Return the first const buffer, or an empty buffer.
     template<ConstBufferSequence ConstBufferSequence>
         requires (!MutableBufferSequence<ConstBufferSequence>)
     const_buffer

include/boost/capy/buffers/slice.hpp

@@ -46,7 +46,15 @@ using slice_type = std::conditional_t<
 
 //------------------------------------------------
 
-/** A wrapper enabling a buffer sequence to be consumed
+/** A view of a sub-range of a buffer sequence.
+
+    This class wraps a buffer sequence and presents a
+    contiguous byte sub-range by adjusting the first and
+    last buffers. The prefix and suffix can be removed or
+    kept using the free functions @ref keep_prefix,
+    @ref remove_prefix, etc.
+
+    @see keep_prefix, remove_prefix, prefix, sans_prefix
 */
 template<ConstBufferSequence BufferSequence>
 class slice_of<BufferSequence>
@@ -118,6 +126,7 @@ class slice_of<BufferSequence>
 
         const_iterator() = default;
 
+        /// Test for equality.
         bool
         operator==(
             const_iterator const& other) const noexcept
@@ -130,13 +139,15 @@ class slice_of<BufferSequence>
                 n_      == other.n_;
         }
 
+        /// Test for inequality.
         bool
         operator!=(
             const_iterator const& other) const noexcept
         {
             return !(*this == other);
         }
 
+        /// Return the current buffer, adjusted for prefix/suffix.
         reference
         operator*() const noexcept
         {
@@ -156,6 +167,7 @@ class slice_of<BufferSequence>
             return value_type(p, n);
         }
 
+        /// Advance to the next element.
         const_iterator&
         operator++() noexcept
         {
@@ -165,6 +177,7 @@ class slice_of<BufferSequence>
             return *this;
         }
 
+        /// Advance to the next element (postfix).
         const_iterator
         operator++(int) noexcept
         {
@@ -173,6 +186,7 @@ class slice_of<BufferSequence>
             return temp;
         }
 
+        /// Move to the previous element.
         const_iterator&
         operator--() noexcept
         {
@@ -182,6 +196,7 @@ class slice_of<BufferSequence>
             return *this;
         }
 
+        /// Move to the previous element (postfix).
         const_iterator
         operator--(int) noexcept
         {
@@ -232,6 +247,7 @@ class slice_of<BufferSequence>
             end_iter_impl(), prefix_, suffix_, len_, len_);
     }
 
+    /// Slice customization point for this type.
     friend
     void
     tag_invoke(