From 644d342cedb10e62e4024e5a23bbc53a4411a00b Mon Sep 17 00:00:00 2001 From: Michael Vandeberg Date: Mon, 8 Jun 2026 15:46:40 -0600 Subject: [PATCH] docs: fix free-function reference docs and hide get (#293) Move the buffer niebloid call-operator structs into namespace detail and attach docstrings to the public variables, so begin/end/front/buffer_copy/ buffer_size/buffer_empty render descriptions instead of the generic ADL note. Add @param/@return where missing. Hide the free boost::capy::get overloads with #if !defined(BOOST_CAPY_MRDOCS) and the member io_result::get via exclude-symbols in mrdocs.yml; drop the dead @cond markers. --- doc/mrdocs.yml | 5 ++ include/boost/capy/buffers.hpp | 82 +++++++++++++++------- include/boost/capy/buffers/buffer_copy.hpp | 44 ++++++------ include/boost/capy/buffers/front.hpp | 20 ++++-- include/boost/capy/io_result.hpp | 6 +- 5 files changed, 103 insertions(+), 54 deletions(-) diff --git a/doc/mrdocs.yml b/doc/mrdocs.yml index 2560be736..51cd46380 100644 --- a/doc/mrdocs.yml +++ b/doc/mrdocs.yml @@ -13,6 +13,11 @@ include-symbols: implementation-defined: - 'boost::capy::detail' - 'boost::capy::*::detail' +exclude-symbols: + # Tuple-protocol accessor for structured bindings. Cannot be hidden with an + # in-source BOOST_CAPY_MRDOCS guard because detail::decomposes_to instantiates + # structured bindings on io_result during the docs parse and needs this member. + - 'boost::capy::io_result::get' inaccessible-members: never inaccessible-bases: never diff --git a/include/boost/capy/buffers.hpp b/include/boost/capy/buffers.hpp index 9fe509754..6c76b8031 100644 --- a/include/boost/capy/buffers.hpp +++ b/include/boost/capy/buffers.hpp @@ -198,12 +198,8 @@ concept MutableBufferSequence = std::ranges::bidirectional_range && std::is_convertible_v, mutable_buffer>); -/** Return an iterator to the first buffer in a sequence. - - Handles single buffers and ranges uniformly. For a single buffer, - returns a pointer to it (forming a one-element range). -*/ -constexpr struct begin_mrdocs_workaround_t +namespace detail { +struct begin_fn { template ConvertibleToBuffer> auto operator()(ConvertibleToBuffer const& b) const noexcept -> ConvertibleToBuffer const* @@ -224,14 +220,22 @@ constexpr struct begin_mrdocs_workaround_t { return std::ranges::begin(bs); } -} begin {}; +}; +} // detail -/** Return an iterator past the last buffer in a sequence. +/** Return an iterator to the first buffer in a sequence. Handles single buffers and ranges uniformly. For a single buffer, - returns a pointer one past it. + returns a pointer to it (forming a one-element range). + + @param bs The buffer sequence. + + @return An iterator to the first buffer in the sequence. */ -constexpr struct end_mrdocs_workaround_t +constexpr detail::begin_fn begin {}; + +namespace detail { +struct end_fn { template ConvertibleToBuffer> auto operator()(ConvertibleToBuffer const& b) const noexcept -> ConvertibleToBuffer const* @@ -252,20 +256,22 @@ constexpr struct end_mrdocs_workaround_t { return std::ranges::end(bs); } -} end {}; +}; +} // detail -/** Return the total byte count across all buffers in a sequence. +/** Return an iterator past the last buffer in a sequence. - Sums the `size()` of each buffer in the sequence. This differs - from `buffer_length` which counts the number of buffer elements. + Handles single buffers and ranges uniformly. For a single buffer, + returns a pointer one past it. - @par Example - @code - std::array bufs = { ... }; - std::size_t total = buffer_size( bufs ); // sum of both sizes - @endcode + @param bs The buffer sequence. + + @return An iterator one past the last buffer in the sequence. */ -constexpr struct buffer_size_mrdocs_workaround_t +constexpr detail::end_fn end {}; + +namespace detail { +struct buffer_size_fn { // GCC 13 falsely flags reads of arr_[i].n_ in detail::buffer_array // when iterating here. The class uses union storage with placement @@ -290,14 +296,28 @@ constexpr struct buffer_size_mrdocs_workaround_t #if defined(__GNUC__) && !defined(__clang__) #pragma GCC diagnostic pop #endif -} buffer_size {}; +}; +} // detail -/** Check if a buffer sequence contains no data. +/** Return the total byte count across all buffers in a sequence. - @return `true` if all buffers have size zero or the sequence - is empty. + Sums the `size()` of each buffer in the sequence. This differs + from `buffer_length` which counts the number of buffer elements. + + @param bs The buffer sequence. + + @return The total number of bytes across all buffers in the sequence. + + @par Example + @code + std::array bufs = { ... }; + std::size_t total = buffer_size( bufs ); // sum of both sizes + @endcode */ -constexpr struct buffer_empty_mrdocs_workaround_t +constexpr detail::buffer_size_fn buffer_size {}; + +namespace detail { +struct buffer_empty_fn { // See note on buffer_size above — same union-storage false positive. #if defined(__GNUC__) && !defined(__clang__) @@ -321,7 +341,17 @@ constexpr struct buffer_empty_mrdocs_workaround_t #if defined(__GNUC__) && !defined(__clang__) #pragma GCC diagnostic pop #endif -} buffer_empty {}; +}; +} // detail + +/** Check if a buffer sequence contains no data. + + @param bs The buffer sequence. + + @return `true` if all buffers have size zero or the sequence + is empty. +*/ +constexpr detail::buffer_empty_fn buffer_empty {}; namespace detail { diff --git a/include/boost/capy/buffers/buffer_copy.hpp b/include/boost/capy/buffers/buffer_copy.hpp index a374acb8c..3d769963b 100644 --- a/include/boost/capy/buffers/buffer_copy.hpp +++ b/include/boost/capy/buffers/buffer_copy.hpp @@ -18,25 +18,8 @@ namespace boost { namespace capy { -/** Copy the contents of a buffer sequence into another buffer sequence. - - This function copies bytes from the constant buffer sequence `src` into - the mutable buffer sequence `dest`, stopping when any limit is reached. - - @par Constraints - @code - MutableBufferSequence && - ConstBufferSequence - @endcode - - @return The number of bytes copied, equal to - `std::min(size(dest), size(src), at_most)`. - - @param dest The destination buffer sequence. - @param src The source buffer sequence. - @param at_most The maximum bytes to copy. Default copies all available. -*/ -constexpr struct buffer_copy_mrdocs_workaround_t +namespace detail { +struct buffer_copy_fn { template< MutableBufferSequence MB, @@ -100,7 +83,28 @@ constexpr struct buffer_copy_mrdocs_workaround_t } return total; } -} buffer_copy {}; +}; +} // detail + +/** Copy the contents of a buffer sequence into another buffer sequence. + + This function copies bytes from the constant buffer sequence `src` into + the mutable buffer sequence `dest`, stopping when any limit is reached. + + @par Constraints + @code + MutableBufferSequence && + ConstBufferSequence + @endcode + + @return The number of bytes copied, equal to + `std::min(size(dest), size(src), at_most)`. + + @param dest The destination buffer sequence. + @param src The source buffer sequence. + @param at_most The maximum bytes to copy. Default copies all available. +*/ +constexpr detail::buffer_copy_fn buffer_copy {}; } // capy } // boost diff --git a/include/boost/capy/buffers/front.hpp b/include/boost/capy/buffers/front.hpp index 13626d3bd..1c52d01f6 100644 --- a/include/boost/capy/buffers/front.hpp +++ b/include/boost/capy/buffers/front.hpp @@ -16,9 +16,8 @@ namespace boost { namespace capy { -/** Return the first buffer in a sequence. -*/ -constexpr struct front_mrdocs_workaround_t +namespace detail { +struct front_fn { /// Return the first mutable buffer, or an empty buffer. template @@ -44,7 +43,20 @@ constexpr struct front_mrdocs_workaround_t return *it; return {}; } -} const front{}; +}; +} // detail + +/** Return the first buffer in a sequence. + + For a `MutableBufferSequence` the result is a `mutable_buffer`; + otherwise it is a `const_buffer`. + + @param bs The buffer sequence. + + @return The first buffer in the sequence, or an empty buffer if the + sequence is empty. +*/ +constexpr detail::front_fn const front{}; } // capy } // boost diff --git a/include/boost/capy/io_result.hpp b/include/boost/capy/io_result.hpp index ac2f13434..aaf4a2861 100644 --- a/include/boost/capy/io_result.hpp +++ b/include/boost/capy/io_result.hpp @@ -58,7 +58,6 @@ struct [[nodiscard]] io_result { } - /// @cond template decltype(auto) get() & noexcept { @@ -82,10 +81,9 @@ struct [[nodiscard]] io_result if constexpr (I == 0) return std::move(ec); else return std::get(std::move(values)); } - /// @endcond }; -/// @cond +#if !defined(BOOST_CAPY_MRDOCS) template decltype(auto) get(io_result& r) noexcept { @@ -103,7 +101,7 @@ decltype(auto) get(io_result&& r) noexcept { return std::move(r).template get(); } -/// @endcond +#endif } // namespace capy } // namespace boost