Improve API docs for std::pair

	* include/bits/stl_pair.h: Improve docs.
	* include/std/tuple: Likewise.

From-SVN: r270989

libstdc++-v3/ChangeLog

 2019-05-07  Jonathan Wakely  <jwakely@redhat.com>
 
+	* include/bits/stl_pair.h: Improve docs.
+	* include/std/tuple: Likewise.
+
 	* doc/doxygen/doxygroups.cc (std::literals): Add documentation for
 	inline namespace.
 	* include/std/chrono: Improve docs.

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

@@ -72,13 +72,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    */
 
 #if __cplusplus >= 201103L
-  /// piecewise_construct_t
+  /// Tag type for piecewise construction of std::pair objects.
   struct piecewise_construct_t { explicit piecewise_construct_t() = default; };
 
-  /// piecewise_construct
+  /// Tag for piecewise construction of std::pair objects.
   _GLIBCXX17_INLINE constexpr piecewise_construct_t piecewise_construct =
     piecewise_construct_t();
 
+  /// @cond undocumented
+
   // Forward declarations.
   template<typename...>
     class tuple;
@@ -198,21 +200,25 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif // C++11
   };
 
+  /// @endcond
+
  /**
    *  @brief Struct holding two objects of arbitrary type.
    *
    *  @tparam _T1  Type of first object.
    *  @tparam _T2  Type of second object.
+   *
+   *  <https://gcc.gnu.org/onlinedocs/libstdc++/manual/utilities.html>
    */
   template<typename _T1, typename _T2>
     struct pair
     : private __pair_base<_T1, _T2>
     {
-      typedef _T1 first_type;    /// @c first_type is the first bound type
-      typedef _T2 second_type;   /// @c second_type is the second bound type
+      typedef _T1 first_type;    ///< The type of the `first` member
+      typedef _T2 second_type;   ///< The type of the `second` member
 
-      _T1 first;                 /// @c first is a copy of the first object
-      _T2 second;                /// @c second is a copy of the second object
+      _T1 first;                 ///< The first member
+      _T2 second;                ///< The second member
 
       // _GLIBCXX_RESOLVE_LIB_DEFECTS
       // 265.  std::pair::pair() effects overly restrictive
@@ -243,14 +249,17 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       : first(), second() { }
 #endif
 
-      /** Two objects may be passed to a @c pair constructor to be copied.  */
 #if __cplusplus < 201103L
+      /// Two objects may be passed to a @c pair constructor to be copied.
       pair(const _T1& __a, const _T2& __b)
       : first(__a), second(__b) { }
 #else
       // Shortcut for constraining the templates that don't take pairs.
+      /// @cond undocumented
       using _PCCP = _PCC<true, _T1, _T2>;
+      /// @endcond
 
+      /// Construct from two const lvalues, allowing implicit conversions.
       template<typename _U1 = _T1, typename _U2=_T2, typename
 	       enable_if<_PCCP::template
 			   _ConstructiblePair<_U1, _U2>()
@@ -260,6 +269,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       constexpr pair(const _T1& __a, const _T2& __b)
       : first(__a), second(__b) { }
 
+      /// Construct from two const lvalues, disallowing implicit conversions.
        template<typename _U1 = _T1, typename _U2=_T2, typename
 		enable_if<_PCCP::template
 			    _ConstructiblePair<_U1, _U2>()
@@ -269,18 +279,21 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       explicit constexpr pair(const _T1& __a, const _T2& __b)
       : first(__a), second(__b) { }
 #endif
+      //@}
 
-      /** There is also a templated copy ctor for the @c pair class itself.  */
 #if __cplusplus < 201103L
+      /// There is also a templated constructor to convert from other pairs.
       template<typename _U1, typename _U2>
 	pair(const pair<_U1, _U2>& __p)
 	: first(__p.first), second(__p.second) { }
 #else
       // Shortcut for constraining the templates that take pairs.
+      /// @cond undocumented
       template <typename _U1, typename _U2>
         using _PCCFP = _PCC<!is_same<_T1, _U1>::value
 			    || !is_same<_T2, _U2>::value,
 			    _T1, _T2>;
+      /// @endcond
 
       template<typename _U1, typename _U2, typename
 	       enable_if<_PCCFP<_U1, _U2>::template
@@ -299,9 +312,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
                          bool>::type=false>
 	explicit constexpr pair(const pair<_U1, _U2>& __p)
 	: first(__p.first), second(__p.second) { }
+#endif
 
-      constexpr pair(const pair&) = default;
-      constexpr pair(pair&&) = default;
+#if __cplusplus >= 201103L
+      constexpr pair(const pair&) = default;	///< Copy constructor
+      constexpr pair(pair&&) = default;		///< Move constructor
 
       // DR 811.
       template<typename _U1, typename
@@ -420,6 +435,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	  return *this;
 	}
 
+      /// Swap the first members and then the second members.
       void
       swap(pair& __p)
       noexcept(__and_<__is_nothrow_swappable<_T1>,
@@ -438,6 +454,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif
     };
 
+  /// @relates pair @{
+
 #if __cpp_deduction_guides >= 201606
   template<typename _T1, typename _T2> pair(_T1, _T2) -> pair<_T1, _T2>;
 #endif
@@ -448,7 +466,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     operator==(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y)
     { return __x.first == __y.first && __x.second == __y.second; }
 
-  /// <http://gcc.gnu.org/onlinedocs/libstdc++/manual/utilities.html>
+  /** Defines a lexicographical order for pairs.
+   *
+   * For two pairs of the same type, `P` is ordered before `Q` if
+   * `P.first` is less than `Q.first`, or if `P.first` and `Q.first`
+   * are equivalent (neither is less than the other) and `P.second` is less
+   * than `Q.second`.
+  */
   template<typename _T1, typename _T2>
     inline _GLIBCXX_CONSTEXPR bool
     operator<(const pair<_T1, _T2>& __x, const pair<_T1, _T2>& __y)
@@ -480,9 +504,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     { return !(__x < __y); }
 
 #if __cplusplus >= 201103L
-  /// See std::pair::swap().
-  // Note:  no std::swap overloads in C++03 mode, this has performance
-  //        implications, see, eg, libstdc++/38466.
+  /** Swap overload for pairs. Calls std::pair::swap().
+   *
+   * @note This std::swap overload is not declared in C++03 mode,
+   * which has performance implications, e.g. see https://gcc.gnu.org/PR38466
+  */
   template<typename _T1, typename _T2>
     inline
 #if __cplusplus > 201402L || !defined(__STRICT_ANSI__) // c++1z or gnu++11
@@ -504,15 +530,20 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif
 #endif // __cplusplus >= 201103L
 
+  // @} relates pair
+
   /**
    *  @brief A convenience wrapper for creating a pair from two objects.
    *  @param  __x  The first object.
    *  @param  __y  The second object.
    *  @return   A newly-constructed pair<> object of the appropriate type.
    *
-   *  The standard requires that the objects be passed by reference-to-const,
-   *  but LWG issue #181 says they should be passed by const value.  We follow
-   *  the LWG by default.
+   *  The C++98 standard says the objects are passed by reference-to-const,
+   *  but C++03 says they are passed by value (this was LWG issue #181).
+   *
+   *  Since C++11 they have been passed by forwarding reference and then
+   *  forwarded to the new members of the pair. To create a pair with a
+   *  member of reference type, pass a `reference_wrapper` to this function.
    */
   // _GLIBCXX_RESOLVE_LIB_DEFECTS
   // 181.  make_pair() unintended behavior

libstdc++-v3/include/std/tuple

@@ -1691,6 +1691,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     struct uses_allocator<tuple<_Types...>, _Alloc> : true_type { };
 
   // See stl_pair.h...
+  /** "piecewise construction" using a tuple of arguments for each member.
+   *
+   * @param __first Arguments for the first member of the pair.
+   * @param __second Arguments for the second member of the pair.
+   *
+   * The elements of each tuple will be used as the constructor arguments
+   * for the data members of the pair.
+  */
   template<class _T1, class _T2>
     template<typename... _Args1, typename... _Args2>
       inline