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 ddf74f3296fdc7c33681c3807c5b8bb1f1641c3d..5a748257f1970dacae73e395b3e6a54a537dfc20 100644 (file)
--- 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