libstdc++: Reduce duplication in Doxygen comments for std::list

We have a number of comments which are duplicated for C++98 and C++11
overloads, where the signatures are slightly different. Instead of
duplicating the comments that are 90% identical, just use a single
comment that can apply to both. In some cases this means saying "an
iterator" instead of "A const iterator" but that's fine, a
std::list::const_iterator is still an iterator (and a non-const iterator
is a valid argument to those functions because they'll implicitly
convert to const_iterator).

In two cases the @return description just needs to say that it returns
void for C++98 and an iterator otherwise.

libstdc++-v3/ChangeLog:

	* include/bits/stl_list.h: Reduce duplication in doxygen
	comments.

diff --git a/libstdc++-v3/include/bits/stl_list.h b/libstdc++-v3/include/bits/stl_list.h
index df7f388ede5a9b334e61314fc49e31cf8ee4f672..cf3d05fcae959d0cd4dab2962acb060548e34ff4 100644 (file)
--- a/libstdc++-v3/include/bits/stl_list.h
+++ b/libstdc++-v3/include/bits/stl_list.h
@@ -1477,10 +1477,11 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       template<typename... _Args>
        iterator
        emplace(const_iterator __position, _Args&&... __args);
+#endif
 
       /**
        *  @brief  Inserts given value into %list before specified iterator.
-       *  @param  __position  A const_iterator into the %list.
+       *  @param  __position  An iterator into the %list.
        *  @param  __x  Data to be inserted.
        *  @return  An iterator that points to the inserted data.
        *
@@ -1488,52 +1489,34 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
        *  the specified location.  Due to the nature of a %list this
        *  operation can be done in constant time, and does not
        *  invalidate iterators and references.
+       *
+       *  @{
        */
+#if __cplusplus >= 201103L
       iterator
       insert(const_iterator __position, const value_type& __x);
+
+      iterator
+      insert(const_iterator __position, value_type&& __x)
+      { return emplace(__position, std::move(__x)); }
 #else
-      /**
-       *  @brief  Inserts given value into %list before specified iterator.
-       *  @param  __position  An iterator into the %list.
-       *  @param  __x  Data to be inserted.
-       *  @return  An iterator that points to the inserted data.
-       *
-       *  This function will insert a copy of the given value before
-       *  the specified location.  Due to the nature of a %list this
-       *  operation can be done in constant time, and does not
-       *  invalidate iterators and references.
-       */
       iterator
       insert(iterator __position, const value_type& __x);
 #endif
+      /// @}
 
 #if __cplusplus >= 201103L
-      /**
-       *  @brief  Inserts given rvalue into %list before specified iterator.
-       *  @param  __position  A const_iterator into the %list.
-       *  @param  __x  Data to be inserted.
-       *  @return  An iterator that points to the inserted data.
-       *
-       *  This function will insert a copy of the given rvalue before
-       *  the specified location.  Due to the nature of a %list this
-       *  operation can be done in constant time, and does not
-       *  invalidate iterators and references.
-       */
-      iterator
-      insert(const_iterator __position, value_type&& __x)
-      { return emplace(__position, std::move(__x)); }
-
       /**
        *  @brief  Inserts the contents of an initializer_list into %list
        *          before specified const_iterator.
        *  @param  __p  A const_iterator into the %list.
        *  @param  __l  An initializer_list of value_type.
        *  @return  An iterator pointing to the first element inserted
-       *           (or __position).
+       *           (or `__p`).
        *
        *  This function will insert copies of the data in the
-       *  initializer_list @a l into the %list before the location
-       *  specified by @a p.
+       *  initializer_list `__l` into the %list before the location
+       *  specified by `__p`.
        *
        *  This operation is linear in the number of elements inserted and
        *  does not invalidate iterators and references.
@@ -1543,36 +1526,24 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       { return this->insert(__p, __l.begin(), __l.end()); }
 #endif
 
-#if __cplusplus >= 201103L
       /**
        *  @brief  Inserts a number of copies of given data into the %list.
-       *  @param  __position  A const_iterator into the %list.
+       *  @param  __position  An iterator into the %list.
        *  @param  __n  Number of elements to be inserted.
        *  @param  __x  Data to be inserted.
-       *  @return  An iterator pointing to the first element inserted
-       *           (or __position).
+       *  @return  Since C++11, an iterator pointing to the first element
+       *           inserted (or `__position`). In C++98 this returns void.
        *
        *  This function will insert a specified number of copies of the
-       *  given data before the location specified by @a position.
+       *  given data before the location specified by `__position`.
        *
        *  This operation is linear in the number of elements inserted and
        *  does not invalidate iterators and references.
        */
+#if __cplusplus >= 201103L
       iterator
       insert(const_iterator __position, size_type __n, const value_type& __x);
 #else
-      /**
-       *  @brief  Inserts a number of copies of given data into the %list.
-       *  @param  __position  An iterator into the %list.
-       *  @param  __n  Number of elements to be inserted.
-       *  @param  __x  Data to be inserted.
-       *
-       *  This function will insert a specified number of copies of the
-       *  given data before the location specified by @a position.
-       *
-       *  This operation is linear in the number of elements inserted and
-       *  does not invalidate iterators and references.
-       */
       void
       insert(iterator __position, size_type __n, const value_type& __x)
       {
@@ -1581,41 +1552,28 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       }
 #endif
 
-#if __cplusplus >= 201103L
       /**
        *  @brief  Inserts a range into the %list.
-       *  @param  __position  A const_iterator into the %list.
+       *  @param  __position  An iterator into the %list.
        *  @param  __first  An input iterator.
        *  @param  __last   An input iterator.
-       *  @return  An iterator pointing to the first element inserted
-       *           (or __position).
+       *  @return  Since C++11, an iterator pointing to the first element
+       *           inserted (or `__position`). In C++98 this returns void.
        *
-       *  This function will insert copies of the data in the range [@a
-       *  first,@a last) into the %list before the location specified by
-       *  @a position.
+       *  This function will insert copies of the data in the range
+       *  `[__first,__last)` into the %list before the location specified by
+       *  `__position`.
        *
        *  This operation is linear in the number of elements inserted and
        *  does not invalidate iterators and references.
        */
+#if __cplusplus >= 201103L
       template<typename _InputIterator,
               typename = std::_RequireInputIter<_InputIterator>>
        iterator
        insert(const_iterator __position, _InputIterator __first,
               _InputIterator __last);
 #else
-      /**
-       *  @brief  Inserts a range into the %list.
-       *  @param  __position  An iterator into the %list.
-       *  @param  __first  An input iterator.
-       *  @param  __last   An input iterator.
-       *
-       *  This function will insert copies of the data in the range [@a
-       *  first,@a last) into the %list before the location specified by
-       *  @a position.
-       *
-       *  This operation is linear in the number of elements inserted and
-       *  does not invalidate iterators and references.
-       */
       template<typename _InputIterator>
        void
        insert(iterator __position, _InputIterator __first,
@@ -1784,29 +1742,21 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       { splice(__position, std::move(__x)); }
 #endif
 
-#if __cplusplus >= 201103L
       /**
        *  @brief  Insert element from another %list.
-       *  @param  __position  Const_iterator referencing the element to
-       *                      insert before.
+       *  @param  __position  Iterator referencing the element to insert before.
        *  @param  __x  Source list.
-       *  @param  __i  Const_iterator referencing the element to move.
+       *  @param  __i  Iterator referencing the element to move.
        *
        *  Removes the element in list @a __x referenced by @a __i and
        *  inserts it into the current list before @a __position.
+       *
+       *  @{
        */
+#if __cplusplus >= 201103L
       void
       splice(const_iterator __position, list&& __x, const_iterator __i) noexcept
 #else
-      /**
-       *  @brief  Insert element from another %list.
-       *  @param  __position  Iterator referencing the element to insert before.
-       *  @param  __x  Source list.
-       *  @param  __i  Iterator referencing the element to move.
-       *
-       *  Removes the element in list @a __x referenced by @a __i and
-       *  inserts it into the current list before @a __position.
-       */
       void
       splice(iterator __position, list& __x, iterator __i)
 #endif
@@ -1827,51 +1777,29 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       }
 
 #if __cplusplus >= 201103L
-      /**
-       *  @brief  Insert element from another %list.
-       *  @param  __position  Const_iterator referencing the element to
-       *                      insert before.
-       *  @param  __x  Source list.
-       *  @param  __i  Const_iterator referencing the element to move.
-       *
-       *  Removes the element in list @a __x referenced by @a __i and
-       *  inserts it into the current list before @a __position.
-       */
       void
       splice(const_iterator __position, list& __x, const_iterator __i) noexcept
       { splice(__position, std::move(__x), __i); }
 #endif
+      /// @}
 
-#if __cplusplus >= 201103L
       /**
        *  @brief  Insert range from another %list.
-       *  @param  __position  Const_iterator referencing the element to
-       *                      insert before.
+       *  @param  __position  Iterator referencing the element to insert before.
        *  @param  __x  Source list.
-       *  @param  __first  Const_iterator referencing the start of range in x.
-       *  @param  __last  Const_iterator referencing the end of range in x.
+       *  @param  __first  Iterator referencing the start of range in x.
+       *  @param  __last  Iterator referencing the end of range in x.
        *
        *  Removes elements in the range [__first,__last) and inserts them
        *  before @a __position in constant time.
        *
        *  Undefined if @a __position is in [__first,__last).
        */
+#if __cplusplus >= 201103L
       void
       splice(const_iterator __position, list&& __x, const_iterator __first,
             const_iterator __last) noexcept
 #else
-      /**
-       *  @brief  Insert range from another %list.
-       *  @param  __position  Iterator referencing the element to insert before.
-       *  @param  __x  Source list.
-       *  @param  __first  Iterator referencing the start of range in x.
-       *  @param  __last  Iterator referencing the end of range in x.
-       *
-       *  Removes elements in the range [__first,__last) and inserts them
-       *  before @a __position in constant time.
-       *
-       *  Undefined if @a __position is in [__first,__last).
-       */
       void
       splice(iterator __position, list& __x, iterator __first,
             iterator __last)