Improve doxygen comments for allocators in containers

	PR libstdc++/70716
	* include/bits/forward_list.h (forward_list): Update doxygen comments
	to reflect allocator propagation semantics. Remove ambiguous
	statements about data being lost.
	* include/bits/stl_deque.h (deque): Likewise.
	* include/bits/stl_list.h (list): Likewise.
	* include/bits/stl_map.h (map): Likewise.
	* include/bits/stl_multimap.h (multimap): Likewise.
	* include/bits/stl_multiset.h (multiset): Likewise.
	* include/bits/stl_set.h (set): Likewise.
	* include/bits/stl_vector.h (vector): Likewise.
	* include/bits/unordered_map.h (unordered_map, unordered_multimap):
	Likewise.
	* include/bits/unordered_set.h (unordered_set, unordered_multiset):
	Likewise.

From-SVN: r238332

libstdc++-v3/ChangeLog

+2016-07-14  Jonathan Wakely  <jwakely@redhat.com>
+
+	PR libstdc++/70716
+	* include/bits/forward_list.h (forward_list): Update doxygen comments
+	to reflect allocator propagation semantics. Remove ambiguous
+	statements about data being lost.
+	* include/bits/stl_deque.h (deque): Likewise.
+	* include/bits/stl_list.h (list): Likewise.
+	* include/bits/stl_map.h (map): Likewise.
+	* include/bits/stl_multimap.h (multimap): Likewise.
+	* include/bits/stl_multiset.h (multiset): Likewise.
+	* include/bits/stl_set.h (set): Likewise.
+	* include/bits/stl_vector.h (vector): Likewise.
+	* include/bits/unordered_map.h (unordered_map, unordered_multimap):
+	Likewise.
+	* include/bits/unordered_set.h (unordered_set, unordered_multiset):
+	Likewise.
+
 2016-07-14  Ville Voutilainen  <ville.voutilainen@gmail.com>
 
 	Implement P0032R3, Homogeneous interface for variant, any and optional,

libstdc++-v3/include/bits/forward_list.h

@@ -566,8 +566,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @param  __list  A %forward_list of identical element and allocator
        *                types.
        *
-       *  All the elements of @a __list are copied, but unlike the copy
-       *  constructor, the allocator object is not copied.
+       *  All the elements of @a __list are copied.
+       *
+       *  Whether the allocator is copied depends on the allocator traits.
        */
       forward_list&
       operator=(const forward_list& __list);
@@ -579,7 +580,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  The contents of @a __list are moved into this %forward_list
        *  (without copying, if the allocators permit it).
-       *  @a __list is a valid, but unspecified %forward_list
+       *
+       *  Afterwards @a __list is a valid, but unspecified %forward_list
+       *
+       *  Whether the allocator is moved depends on the allocator traits.
        */
       forward_list&
       operator=(forward_list&& __list)
@@ -617,7 +621,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %forward_list and
        *  that the number of elements of the resulting %forward_list is the
-       *  same as the number of elements assigned.  Old data is lost.
+       *  same as the number of elements assigned.
        */
       template<typename _InputIterator,
 	       typename = std::_RequireInputIter<_InputIterator>>
@@ -636,7 +640,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  This function fills a %forward_list with @a __n copies of the
        *  given value.  Note that the assignment completely changes the
        *  %forward_list, and that the resulting %forward_list has __n
-       *  elements.  Old data is lost.
+       *  elements.
        */
       void
       assign(size_type __n, const _Tp& __val)
@@ -991,6 +995,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  time.  Note that the global std::swap() function is
        *  specialized such that std::swap(l1,l2) will feed to this
        *  function.
+       *
+       *  Whether the allocators are swapped depends on the allocator traits.
        */
       void
       swap(forward_list& __list) noexcept

libstdc++-v3/include/bits/stl_deque.h

@@ -939,8 +939,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Deque copy constructor.
        *  @param  __x  A %deque of identical element and allocator types.
        *
-       *  The newly-created %deque uses a copy of the allocation object used
-       *  by @a __x.
+       *  The newly-created %deque uses a copy of the allocator object used
+       *  by @a __x (unless the allocator traits dictate a different object).
        */
       deque(const deque& __x)
       : _Base(_Alloc_traits::_S_select_on_copy(__x._M_get_Tp_allocator()),
@@ -1046,8 +1046,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Deque assignment operator.
        *  @param  __x  A %deque of identical element and allocator types.
        *
-       *  All the elements of @a x are copied, but unlike the copy constructor,
-       *  the allocator object is not copied.
+       *  All the elements of @a x are copied.
+       *
+       *  The newly-created %deque uses a copy of the allocator object used
+       *  by @a __x (unless the allocator traits dictate a different object).
        */
       deque&
       operator=(const deque& __x);
@@ -1078,7 +1080,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %deque and that the
        *  resulting %deque's size is the same as the number of elements
-       *  assigned.  Old data may be lost.
+       *  assigned.
        */
       deque&
       operator=(initializer_list<value_type> __l)
@@ -1097,7 +1099,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  This function fills a %deque with @a n copies of the given
        *  value.  Note that the assignment completely changes the
        *  %deque and that the resulting %deque's size is the same as
-       *  the number of elements assigned.  Old data may be lost.
+       *  the number of elements assigned.
        */
       void
       assign(size_type __n, const value_type& __val)
@@ -1113,7 +1115,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %deque and that the
        *  resulting %deque's size is the same as the number of elements
-       *  assigned.  Old data may be lost.
+       *  assigned.
        */
 #if __cplusplus >= 201103L
       template<typename _InputIterator,
@@ -1141,7 +1143,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %deque and that the
        *  resulting %deque's size is the same as the number of elements
-       *  assigned.  Old data may be lost.
+       *  assigned.
        */
       void
       assign(initializer_list<value_type> __l)
@@ -1803,6 +1805,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  (Four pointers, so it should be quite fast.)
        *  Note that the global std::swap() function is specialized such that
        *  std::swap(d1,d2) will feed to this function.
+       *
+       *  Whether the allocators are swapped depends on the allocator traits.
        */
       void
       swap(deque& __x) _GLIBCXX_NOEXCEPT

libstdc++-v3/include/bits/stl_list.h

@@ -643,7 +643,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
        *  @param  __x  A %list of identical element and allocator types.
        *
        *  The newly-created %list uses a copy of the allocation object used
-       *  by @a __x.
+       *  by @a __x (unless the allocator traits dictate a different object).
        */
       list(const list& __x)
       : _Base(_Node_alloc_traits::
@@ -718,6 +718,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 	}
 #endif
 
+#if __cplusplus >= 201103L
       /**
        *  No explicit dtor needed as the _Base dtor takes care of
        *  things.  The _Base dtor only erases the elements, and note
@@ -725,13 +726,16 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
        *  memory is not touched in any way.  Managing the pointer is
        *  the user's responsibility.
        */
+      ~list() = default;
+#endif
 
       /**
        *  @brief  %List assignment operator.
        *  @param  __x  A %list of identical element and allocator types.
        *
-       *  All the elements of @a __x are copied, but unlike the copy
-       *  constructor, the allocator object is not copied.
+       *  All the elements of @a __x are copied.
+       *
+       *  Whether the allocator is copied depends on the allocator traits.
        */
       list&
       operator=(const list& __x);
@@ -742,7 +746,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
        *  @param  __x  A %list of identical element and allocator types.
        *
        *  The contents of @a __x are moved into this %list (without copying).
-       *  @a __x is a valid, but unspecified %list
+       *
+       *  Afterwards @a __x is a valid, but unspecified %list
+       *
+       *  Whether the allocator is moved depends on the allocator traits.
        */
       list&
       operator=(list&& __x)
@@ -778,7 +785,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
        *  This function fills a %list with @a __n copies of the given
        *  value.  Note that the assignment completely changes the %list
        *  and that the resulting %list's size is the same as the number
-       *  of elements assigned.  Old data may be lost.
+       *  of elements assigned.
        */
       void
       assign(size_type __n, const value_type& __val)
@@ -794,7 +801,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
        *
        *  Note that the assignment completely changes the %list and
        *  that the resulting %list's size is the same as the number of
-       *  elements assigned.  Old data may be lost.
+       *  elements assigned.
        */
 #if __cplusplus >= 201103L
       template<typename _InputIterator,
@@ -1348,6 +1355,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
        *  time.  Note that the global std::swap() function is
        *  specialized such that std::swap(l1,l2) will feed to this
        *  function.
+       *
+       *  Whether the allocators are swapped depends on the allocator traits.
        */
       void
       swap(list& __x) _GLIBCXX_NOEXCEPT

libstdc++-v3/include/bits/stl_map.h

@@ -179,8 +179,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Map copy constructor.
        *  @param  __x  A %map of identical element and allocator types.
        *
-       *  The newly-created %map uses a copy of the allocation object
-       *  used by @a __x.
+       *  The newly-created %map uses a copy of the allocator object used
+       *  by @a __x (unless the allocator traits dictate a different object).
        */
       map(const map& __x)
       : _M_t(__x._M_t) { }
@@ -289,8 +289,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Map assignment operator.
        *  @param  __x  A %map of identical element and allocator types.
        *
-       *  All the elements of @a __x are copied, but unlike the copy
-       *  constructor, the allocator object is not copied.
+       *  All the elements of @a __x are copied.
+       *
+       *  Whether the allocator is copied depends on the allocator traits.
        */
       map&
       operator=(const map& __x)
@@ -313,7 +314,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %map and
        *  that the resulting %map's size is the same as the number
-       *  of elements assigned.  Old data may be lost.
+       *  of elements assigned.
        */
       map&
       operator=(initializer_list<value_type> __l)
@@ -1027,6 +1028,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  stateless and empty), so it should be quite fast.)  Note
        *  that the global std::swap() function is specialized such
        *  that std::swap(m1,m2) will feed to this function.
+       *
+       *  Whether the allocators are swapped depends on the allocator traits.
        */
       void
       swap(map& __x)

libstdc++-v3/include/bits/stl_multimap.h

@@ -177,8 +177,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Multimap copy constructor.
        *  @param  __x  A %multimap of identical element and allocator types.
        *
-       *  The newly-created %multimap uses a copy of the allocation object
-       *  used by @a __x.
+       *  The newly-created %multimap uses a copy of the allocator object used
+       *  by @a __x (unless the allocator traits dictate a different object).
        */
       multimap(const multimap& __x)
       : _M_t(__x._M_t) { }
@@ -284,8 +284,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Multimap assignment operator.
        *  @param  __x  A %multimap of identical element and allocator types.
        *
-       *  All the elements of @a __x are copied, but unlike the copy
-       *  constructor, the allocator object is not copied.
+       *  All the elements of @a __x are copied.
+       *
+       *  Whether the allocator is copied depends on the allocator traits.
        */
       multimap&
       operator=(const multimap& __x)
@@ -308,7 +309,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %multimap and
        *  that the resulting %multimap's size is the same as the number
-       *  of elements assigned.  Old data may be lost.
+       *  of elements assigned.
        */
       multimap&
       operator=(initializer_list<value_type> __l)
@@ -701,6 +702,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  should be quite fast.)
        *  Note that the global std::swap() function is specialized such that
        *  std::swap(m1,m2) will feed to this function.
+       *
+       *  Whether the allocators are swapped depends on the allocator traits.
        */
       void
       swap(multimap& __x)

libstdc++-v3/include/bits/stl_multiset.h

@@ -189,8 +189,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Multiset copy constructor.
        *  @param  __x  A %multiset of identical element and allocator types.
        *
-       *  The newly-created %multiset uses a copy of the allocation object used
-       *  by @a __x.
+       *  The newly-created %multiset uses a copy of the allocator object used
+       *  by @a __x (unless the allocator traits dictate a different object).
        */
       multiset(const multiset& __x)
       : _M_t(__x._M_t) { }
@@ -255,8 +255,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Multiset assignment operator.
        *  @param  __x  A %multiset of identical element and allocator types.
        *
-       *  All the elements of @a __x are copied, but unlike the copy
-       *  constructor, the allocator object is not copied.
+       *  All the elements of @a __x are copied.
+       *
+       *  Whether the allocator is copied depends on the allocator traits.
        */
       multiset&
       operator=(const multiset& __x)
@@ -279,7 +280,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %multiset and
        *  that the resulting %multiset's size is the same as the number
-       *  of elements assigned.  Old data may be lost.
+       *  of elements assigned.
        */
       multiset&
       operator=(initializer_list<value_type> __l)
@@ -403,6 +404,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  be quite fast.)
        *  Note that the global std::swap() function is specialized such that
        *  std::swap(s1,s2) will feed to this function.
+       *
+       *  Whether the allocators are swapped depends on the allocator traits.
        */
       void
       swap(multiset& __x)

libstdc++-v3/include/bits/stl_set.h

@@ -193,8 +193,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Set copy constructor.
        *  @param  __x  A %set of identical element and allocator types.
        *
-       *  The newly-created %set uses a copy of the allocation object used
-       *  by @a __x.
+       *  The newly-created %set uses a copy of the allocator object used
+       *  by @a __x (unless the allocator traits dictate a different object).
        */
       set(const set& __x)
       : _M_t(__x._M_t) { }
@@ -259,8 +259,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Set assignment operator.
        *  @param  __x  A %set of identical element and allocator types.
        *
-       *  All the elements of @a __x are copied, but unlike the copy
-       *  constructor, the allocator object is not copied.
+       *  All the elements of @a __x are copied.
+       *
+       *  Whether the allocator is copied depends on the allocator traits.
        */
       set&
       operator=(const set& __x)
@@ -283,7 +284,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %set and
        *  that the resulting %set's size is the same as the number
-       *  of elements assigned.  Old data may be lost.
+       *  of elements assigned.
        */
       set&
       operator=(initializer_list<value_type> __l)
@@ -407,6 +408,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  stateless and empty), so it should be quite fast.)  Note
        *  that the global std::swap() function is specialized such
        *  that std::swap(s1,s2) will feed to this function.
+       *
+       *  Whether the allocators are swapped depends on the allocator traits.
        */
       void
       swap(set& __x)

libstdc++-v3/include/bits/stl_vector.h

@@ -314,10 +314,12 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Vector copy constructor.
        *  @param  __x  A %vector of identical element and allocator types.
        *
-       *  The newly-created %vector uses a copy of the allocation
-       *  object used by @a __x.  All the elements of @a __x are copied,
-       *  but any extra memory in
-       *  @a __x (for fast expansion) will not be copied.
+       *  All the elements of @a __x are copied, but any unused capacity in
+       *  @a __x  will not be copied
+       *  (i.e. capacity() == size() in the new %vector).
+       *
+       *  The newly-created %vector uses a copy of the allocator object used
+       *  by @a __x (unless the allocator traits dictate a different object).
        */
       vector(const vector& __x)
       : _Base(__x.size(),
@@ -434,9 +436,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Vector assignment operator.
        *  @param  __x  A %vector of identical element and allocator types.
        *
-       *  All the elements of @a __x are copied, but any extra memory in
-       *  @a __x (for fast expansion) will not be copied.  Unlike the
-       *  copy constructor, the allocator object is not copied.
+       *  All the elements of @a __x are copied, but any unused capacity in
+       *  @a __x will not be copied.
+       *
+       *  Whether the allocator is copied depends on the allocator traits.
        */
       vector&
       operator=(const vector& __x);
@@ -448,7 +451,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  The contents of @a __x are moved into this %vector (without copying,
        *  if the allocators permit it).
-       *  @a __x is a valid, but unspecified %vector.
+       *  Afterwards @a __x is a valid, but unspecified %vector.
+       *
+       *  Whether the allocator is moved depends on the allocator traits.
        */
       vector&
       operator=(vector&& __x) noexcept(_Alloc_traits::_S_nothrow_move())
@@ -469,7 +474,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %vector and
        *  that the resulting %vector's size is the same as the number
-       *  of elements assigned.  Old data may be lost.
+       *  of elements assigned.
        */
       vector&
       operator=(initializer_list<value_type> __l)
@@ -488,7 +493,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  This function fills a %vector with @a __n copies of the given
        *  value.  Note that the assignment completely changes the
        *  %vector and that the resulting %vector's size is the same as
-       *  the number of elements assigned.  Old data may be lost.
+       *  the number of elements assigned.
        */
       void
       assign(size_type __n, const value_type& __val)
@@ -504,7 +509,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %vector and
        *  that the resulting %vector's size is the same as the number
-       *  of elements assigned.  Old data may be lost.
+       *  of elements assigned.
        */
 #if __cplusplus >= 201103L
       template<typename _InputIterator,
@@ -533,7 +538,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %vector and
        *  that the resulting %vector's size is the same as the number
-       *  of elements assigned.  Old data may be lost.
+       *  of elements assigned.
        */
       void
       assign(initializer_list<value_type> __l)
@@ -1219,6 +1224,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  (Three pointers, so it should be quite fast.)
        *  Note that the global std::swap() function is specialized such that
        *  std::swap(v1,v2) will feed to this function.
+       *
+       *  Whether the allocators are swapped depends on the allocator traits.
        */
       void
       swap(vector& __x) _GLIBCXX_NOEXCEPT

libstdc++-v3/include/bits/unordered_map.h

@@ -274,7 +274,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %unordered_map and
        *  that the resulting %unordered_map's size is the same as the number
-       *  of elements assigned.  Old data may be lost.
+       *  of elements assigned.
        */
       unordered_map&
       operator=(initializer_list<value_type> __l)
@@ -283,8 +283,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
 	return *this;
       }
 
-      ///  Returns the allocator object with which the %unordered_map was
-      ///  constructed.
+      ///  Returns the allocator object used by the %unordered_map.
       allocator_type
       get_allocator() const noexcept
       { return _M_h.get_allocator(); }
@@ -1258,12 +1257,12 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  @brief  %Unordered_multimap list assignment operator.
        *  @param  __l  An initializer_list.
        *
-       *  This function fills an %unordered_multimap with copies of the elements
-       *  in the initializer list @a __l.
+       *  This function fills an %unordered_multimap with copies of the
+       *  elements in the initializer list @a __l.
        *
        *  Note that the assignment completely changes the %unordered_multimap
        *  and that the resulting %unordered_multimap's size is the same as the
-       *  number of elements assigned.  Old data may be lost.
+       *  number of elements assigned.
        */
       unordered_multimap&
       operator=(initializer_list<value_type> __l)
@@ -1272,8 +1271,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
 	return *this;
       }
 
-      ///  Returns the allocator object with which the %unordered_multimap was
-      ///  constructed.
+      ///  Returns the allocator object used by the %unordered_multimap.
       allocator_type
       get_allocator() const noexcept
       { return _M_h.get_allocator(); }

libstdc++-v3/include/bits/unordered_set.h

@@ -268,7 +268,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %unordered_set and
        *  that the resulting %unordered_set's size is the same as the number
-       *  of elements assigned.  Old data may be lost.
+       *  of elements assigned.
        */
       unordered_set&
       operator=(initializer_list<value_type> __l)
@@ -277,8 +277,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
 	return *this;
       }
 
-      ///  Returns the allocator object with which the %unordered_set was
-      ///  constructed.
+      ///  Returns the allocator object used by the %unordered_set.
       allocator_type
       get_allocator() const noexcept
       { return _M_h.get_allocator(); }
@@ -942,7 +941,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *
        *  Note that the assignment completely changes the %unordered_multiset
        *  and that the resulting %unordered_multiset's size is the same as the
-       *  number of elements assigned. Old data may be lost.
+       *  number of elements assigned.
        */
       unordered_multiset&
       operator=(initializer_list<value_type> __l)
@@ -951,8 +950,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
 	return *this;
       }
 
-      ///  Returns the allocator object with which the %unordered_multiset was
-      ///  constructed.
+      ///  Returns the allocator object used by the %unordered_multiset.
       allocator_type
       get_allocator() const noexcept
       { return _M_h.get_allocator(); }