From: Jonathan Wakely <jwakely@redhat.com>
Date: Tue, 5 May 2026 19:19:45 +0000 (+0100)
Subject: libstdc++: Improve docs for range access functions [PR97001]
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d8cde7c0859004e07c0cfd9733a8eb0272b3300a;p=thirdparty%2Fgcc.git

libstdc++: Improve docs for range access functions [PR97001]

libstdc++-v3/ChangeLog:

	PR libstdc++/97001
	* include/bits/range_access.h: Improve Doxygen comments.
---

diff --git a/libstdc++-v3/include/bits/range_access.h b/libstdc++-v3/include/bits/range_access.h
index ddf74f3296f..5a748257f19 100644
--- a/libstdc++-v3/include/bits/range_access.h
+++ b/libstdc++-v3/include/bits/range_access.h
@@ -47,6 +47,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return an iterator pointing to the first element of
    *          the container.
    *  @param  __cont  Container.
+   *  @since  C++11
    */
   template<typename _Container>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -71,6 +72,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return an iterator pointing to one past the last element of
    *          the container.
    *  @param  __cont  Container.
+   *  @since  C++11
    */
   template<typename _Container>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -83,6 +85,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return an iterator pointing to one past the last element of
    *          the const container.
    *  @param  __cont  Container.
+   *  @since  C++11
    */
   template<typename _Container>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -94,6 +97,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /**
    *  @brief  Return an iterator pointing to the first element of the array.
    *  @param  __arr  Array.
+   *  @since  C++11
    */
   template<typename _Tp, size_t _Nm>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -105,6 +109,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return an iterator pointing to one past the last element
    *          of the array.
    *  @param  __arr  Array.
+   *  @since  C++11
    */
   template<typename _Tp, size_t _Nm>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -125,6 +130,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return an iterator pointing to the first element of
    *          the const container.
    *  @param  __cont  Container.
+   *  @since  C++14
    */
   template<typename _Container>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -137,6 +143,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return an iterator pointing to one past the last element of
    *          the const container.
    *  @param  __cont  Container.
+   *  @since  C++14
    */
   template<typename _Container>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -149,6 +156,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return a reverse iterator pointing to the last element of
    *          the container.
    *  @param  __cont  Container.
+   *  @since  C++14
    */
   template<typename _Container>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -161,6 +169,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return a reverse iterator pointing to the last element of
    *          the const container.
    *  @param  __cont  Container.
+   *  @since  C++14
    */
   template<typename _Container>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -173,6 +182,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return a reverse iterator pointing one past the first element of
    *          the container.
    *  @param  __cont  Container.
+   *  @since  C++14
    */
   template<typename _Container>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -185,6 +195,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return a reverse iterator pointing one past the first element of
    *          the const container.
    *  @param  __cont  Container.
+   *  @since  C++14
    */
   template<typename _Container>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -197,6 +208,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return a reverse iterator pointing to the last element of
    *          the array.
    *  @param  __arr  Array.
+   *  @since  C++14
    */
   template<typename _Tp, size_t _Nm>
     [[__nodiscard__]]
@@ -208,6 +220,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return a reverse iterator pointing one past the first element of
    *          the array.
    *  @param  __arr  Array.
+   *  @since  C++14
    */
   template<typename _Tp, size_t _Nm>
     [[__nodiscard__]]
@@ -219,6 +232,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return a reverse iterator pointing to the last element of
    *          the initializer_list.
    *  @param  __il  initializer_list.
+   *  @since  C++14
    */
   template<typename _Tp>
     [[__nodiscard__]]
@@ -230,6 +244,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return a reverse iterator pointing one past the first element of
    *          the initializer_list.
    *  @param  __il  initializer_list.
+   *  @since  C++14
    */
   template<typename _Tp>
     [[__nodiscard__]]
@@ -241,6 +256,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return a reverse iterator pointing to the last element of
    *          the const container.
    *  @param  __cont  Container.
+   *  @since  C++14
    */
   template<typename _Container>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -253,6 +269,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *  @brief  Return a reverse iterator pointing one past the first element of
    *          the const container.
    *  @param  __cont  Container.
+   *  @since  C++14
    */
   template<typename _Container>
     [[__nodiscard__, __gnu__::__always_inline__]]
@@ -267,6 +284,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /**
    *  @brief  Return the size of a container.
    *  @param  __cont  Container.
+   *  @since  C++17
    */
   template <typename _Container>
     [[nodiscard, __gnu__::__always_inline__]]
@@ -277,6 +295,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /**
    *  @brief  Return the size of an array.
+   *  @param  - An array.
+   *  @return The number of elements in the array.
+   *  @since  C++17
    */
   template <typename _Tp, size_t _Nm>
     [[nodiscard, __gnu__::__always_inline__]]
@@ -287,6 +308,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /**
    *  @brief  Return whether a container is empty.
    *  @param  __cont  Container.
+   *  @since  C++17
    */
   template <typename _Container>
     [[nodiscard, __gnu__::__always_inline__]]
@@ -297,6 +319,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /**
    *  @brief  Return whether an array is empty (always false).
+   *  @param  - An array.
+   *  @since  C++17
    */
   template <typename _Tp, size_t _Nm>
     [[nodiscard, __gnu__::__always_inline__]]
@@ -307,6 +331,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /**
    *  @brief  Return whether an initializer_list is empty.
    *  @param  __il  Initializer list.
+   *  @since  C++17
    */
   template <typename _Tp>
     [[nodiscard, __gnu__::__always_inline__]]
@@ -317,6 +342,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /**
    *  @brief  Return the data pointer of a container.
    *  @param  __cont  Container.
+   *  @since  C++17
    */
   template <typename _Container>
     [[nodiscard, __gnu__::__always_inline__]]
@@ -328,6 +354,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /**
    *  @brief  Return the data pointer of a const container.
    *  @param  __cont  Container.
+   *  @since  C++17
    */
   template <typename _Container>
     [[nodiscard, __gnu__::__always_inline__]]
@@ -339,6 +366,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /**
    *  @brief  Return the data pointer of an array.
    *  @param  __array  Array.
+   *  @since  C++17
    */
   template <typename _Tp, size_t _Nm>
     [[nodiscard, __gnu__::__always_inline__]]
@@ -349,6 +377,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /**
    *  @brief  Return the data pointer of an initializer list.
    *  @param  __il  Initializer list.
+   *  @since  C++17
    */
   template <typename _Tp>
     [[nodiscard, __gnu__::__always_inline__]]
@@ -358,6 +387,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif // __glibcxx_nonmember_container_access
 
 #ifdef __glibcxx_ssize // C++ >= 20
+  /**
+   *  @brief  Return the size of a container, as a signed integer.
+   *  @param  __cont  Container.
+   *  @since  C++20
+   */
   template<typename _Container>
     [[nodiscard, __gnu__::__always_inline__]]
     constexpr auto
@@ -368,6 +402,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       return static_cast<common_type_t<ptrdiff_t, type>>(__cont.size());
     }
 
+  /**
+   *  @brief  Return the length of an array, as a signed integer.
+   *  @since  C++20
+   */
   template<typename _Tp, ptrdiff_t _Num>
     [[nodiscard, __gnu__::__always_inline__]]
     constexpr ptrdiff_t