Improve API docs for <chrono> and <ratio>

	* doc/doxygen/doxygroups.cc (std::literals): Add documentation for
	inline namespace.
	* include/std/chrono: Improve docs.
	* include/std/ratio: Do not document implementation details.
	* testsuite/20_util/ratio/cons/cons_overflow_neg.cc: Adjust dg-error
	line numbers.
	* testsuite/20_util/ratio/operations/ops_overflow_neg.cc: Likewise.

From-SVN: r270988

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index fb69a3d10507005a3a7fc1e96137dc515a670ecc..5c668bac172cfd2a070899fdd0c14a5281371ea9 100644 (file)
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,5 +1,13 @@
 2019-05-07  Jonathan Wakely  <jwakely@redhat.com>
 
+       * doc/doxygen/doxygroups.cc (std::literals): Add documentation for
+       inline namespace.
+       * include/std/chrono: Improve docs.
+       * include/std/ratio: Do not document implementation details.
+       * testsuite/20_util/ratio/cons/cons_overflow_neg.cc: Adjust dg-error
+       line numbers.
+       * testsuite/20_util/ratio/operations/ops_overflow_neg.cc: Likewise.
+
        PR libstdc++/89102
        * doc/xml/manual/intro.xml: Document DR 2408 and 2465 changes.
        * include/std/chrono (__duration_common_type_wrapper): Replace with ...

diff --git a/libstdc++-v3/doc/doxygen/doxygroups.cc b/libstdc++-v3/doc/doxygen/doxygroups.cc
index 630e02296edc2b9633968e331e4bd16e55ad1513..94ef3bb4f65b1cbdbd37bbc94a6471f55d73faa0 100644 (file)
--- a/libstdc++-v3/doc/doxygen/doxygroups.cc
+++ b/libstdc++-v3/doc/doxygen/doxygroups.cc
@@ -19,6 +19,9 @@
 /** @namespace std
  *  @brief ISO C++ entities toplevel namespace is std.
 */
+/** @namespace std
+ *  @brief ISO C++ inline namespace for literal suffixes.
+*/
 /** @namespace std::__detail
  *  @brief Implementation details not part of the namespace std interface.
 */

diff --git a/libstdc++-v3/include/std/chrono b/libstdc++-v3/include/std/chrono
index b7c1d7500673cb4472a78bc94473d22246d63633..1f2c8799b5b2ca6df7c67f58970436d8d7d62cad 100644 (file)
--- a/libstdc++-v3/include/std/chrono
+++ b/libstdc++-v3/include/std/chrono
@@ -24,6 +24,7 @@
 
 /** @file include/chrono
  *  This is a Standard C++ Library header.
+ *  @ingroup chrono
  */
 
 #ifndef _GLIBCXX_CHRONO
@@ -67,6 +68,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   // 20.11.4.3 specialization of common_type (for duration, sfinae-friendly)
 
+  /// @cond undocumented
+
   template<typename _CT, typename _Period1, typename _Period2, typename = void>
     struct __duration_common_type
     { };
@@ -90,6 +93,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     struct __duration_common_type<__failure_type, _Period1, _Period2>
     { typedef __failure_type type; };
 
+  /// @endcond
+
+  /// Specialization of common_type for chrono::duration types.
+  /// @relates duration
   template<typename _Rep1, typename _Period1, typename _Rep2, typename _Period2>
     struct common_type<chrono::duration<_Rep1, _Period1>,
                       chrono::duration<_Rep2, _Period2>>
@@ -98,6 +105,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   // 20.11.4.3 specialization of common_type (for time_point, sfinae-friendly)
 
+  /// @cond undocumented
+
   template<typename _CT, typename _Clock, typename = void>
     struct __timepoint_common_type
     { };
@@ -108,14 +117,25 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       using type = chrono::time_point<_Clock, typename _CT::type>;
     };
 
+  /// @endcond
+
+  /// Specialization of common_type for chrono::time_point types.
+  /// @relates time_point
   template<typename _Clock, typename _Duration1, typename _Duration2>
     struct common_type<chrono::time_point<_Clock, _Duration1>,
                       chrono::time_point<_Clock, _Duration2>>
     : __timepoint_common_type<common_type<_Duration1, _Duration2>, _Clock>
     { };
 
+  // @} group chrono
+
   namespace chrono
   {
+    /// @addtogroup chrono
+    /// @{
+
+    /// @cond undocumented
+
     // Primary template for duration_cast impl.
     template<typename _ToDur, typename _CF, typename _CR,
             bool _NumIsOne = false, bool _DenIsOne = false>
@@ -188,6 +208,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       using __disable_if_is_duration
        = typename enable_if<!__is_duration<_Tp>::value, _Tp>::type;
 
+    /// @endcond
+
     /// duration_cast
     template<typename _ToDur, typename _Rep, typename _Period>
       constexpr __enable_if_is_duration<_ToDur>
@@ -288,6 +310,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        { return numeric_limits<_Rep>::lowest(); }
       };
 
+    /// @cond undocumented
+
     template<typename _Tp>
       struct __is_ratio
       : std::false_type
@@ -298,6 +322,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       : std::true_type
       { };
 
+    /// @endcond
+
     /// duration
     template<typename _Rep, typename _Period>
       struct duration
@@ -446,6 +472,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        rep __r;
       };
 
+    /// @relates duration @{
+
+    /// The sum of two durations.
     template<typename _Rep1, typename _Period1,
             typename _Rep2, typename _Period2>
       constexpr typename common_type<duration<_Rep1, _Period1>,
@@ -459,6 +488,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        return __cd(__cd(__lhs).count() + __cd(__rhs).count());
       }
 
+    /// The difference between two durations.
     template<typename _Rep1, typename _Period1,
             typename _Rep2, typename _Period2>
       constexpr typename common_type<duration<_Rep1, _Period1>,
@@ -472,6 +502,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        return __cd(__cd(__lhs).count() - __cd(__rhs).count());
       }
 
+    /// @}
+
+    /// @cond undocumented
+
     // SFINAE helper to obtain common_type<_Rep1, _Rep2> only if _Rep2
     // is implicitly convertible to it.
     // _GLIBCXX_RESOLVE_LIB_DEFECTS
@@ -481,6 +515,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       using __common_rep_t = typename
        enable_if<is_convertible<const _Rep2&, _CRep>::value, _CRep>::type;
 
+    /// @endcond
+
+    /// @relates duration @{
+
+    /// Multiply a duration by a scalar value.
     template<typename _Rep1, typename _Period, typename _Rep2>
       constexpr duration<__common_rep_t<_Rep1, _Rep2>, _Period>
       operator*(const duration<_Rep1, _Period>& __d, const _Rep2& __s)
@@ -490,6 +529,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        return __cd(__cd(__d).count() * __s);
       }
 
+    /// Multiply a duration by a scalar value.
     template<typename _Rep1, typename _Rep2, typename _Period>
       constexpr duration<__common_rep_t<_Rep2, _Rep1>, _Period>
       operator*(const _Rep1& __s, const duration<_Rep2, _Period>& __d)
@@ -542,6 +582,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       }
 
     // comparisons
+
     template<typename _Rep1, typename _Period1,
             typename _Rep2, typename _Period2>
       constexpr bool
@@ -594,6 +635,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
                 const duration<_Rep2, _Period2>& __rhs)
       { return !(__lhs < __rhs); }
 
+    /// @}
+
 #ifdef _GLIBCXX_USE_C99_STDINT_TR1
 # define _GLIBCXX_CHRONO_INT64_T int64_t
 #elif defined __INT64_TYPE__
@@ -721,6 +764,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       }
 #endif // C++17
 
+    /// @relates time_point @{
+
+    /// Adjust a time point forwards by the given duration.
     template<typename _Clock, typename _Dur1,
             typename _Rep2, typename _Period2>
       constexpr time_point<_Clock,
@@ -734,6 +780,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        return __time_point(__lhs.time_since_epoch() + __rhs);
       }
 
+    /// Adjust a time point forwards by the given duration.
     template<typename _Rep1, typename _Period1,
             typename _Clock, typename _Dur2>
       constexpr time_point<_Clock,
@@ -747,6 +794,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        return __time_point(__rhs.time_since_epoch() + __lhs);
       }
 
+    /// Adjust a time point backwards by the given duration.
     template<typename _Clock, typename _Dur1,
             typename _Rep2, typename _Period2>
       constexpr time_point<_Clock,
@@ -760,6 +808,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        return __time_point(__lhs.time_since_epoch() -__rhs);
       }
 
+    /// @}
+
+    /// @relates time_point @{
+
+    /// The difference between two time points (as a duration)
     template<typename _Clock, typename _Dur1, typename _Dur2>
       constexpr typename common_type<_Dur1, _Dur2>::type
       operator-(const time_point<_Clock, _Dur1>& __lhs,
@@ -802,6 +855,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
                 const time_point<_Clock, _Dur2>& __rhs)
       { return !(__lhs < __rhs); }
 
+    // @}
 
     // Clocks.
 
@@ -827,6 +881,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
      *  @brief System clock.
      *
      *  Time returned represents wall time from the system-wide clock.
+     *  @ingroup chrono
     */
     struct system_clock
     {
@@ -866,6 +921,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
      *  @brief Monotonic clock
      *
      *  Time returned has the property of only increasing at a uniform rate.
+     *  @ingroup chrono
     */
     struct steady_clock
     {
@@ -887,10 +943,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
      *  This is the clock "with the shortest tick period." Alias to
      *  std::system_clock until higher-than-nanosecond definitions
      *  become feasible.
+     *  @ingroup chrono
     */
     using high_resolution_clock = system_clock;
 
     } // end inline namespace _V2
+    // @}
   } // namespace chrono
 
 #if __cplusplus > 201103L
@@ -899,10 +957,34 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   inline namespace literals
   {
+  /** ISO C++ 2014  namespace for suffixes for duration literals.
+   *
+   * These suffixes can be used to create `chrono::duration` values with
+   * tick periods of hours, minutes, seconds, milliseconds, microseconds
+   * or nanoseconds. For example, `std::chrono::seconds(5)` can be written
+   * as `5s` after making the suffix visible in the current scope.
+   * The suffixes can be made visible by a using-directive or
+   * using-declaration such as:
+   *  - `using namespace std::chrono_literals;`
+   *  - `using namespace std::literals;`
+   *  - `using namespace std::chrono;`
+   *  - `using namespace std;`
+   *  - `using std::chrono_literals::operator""s;`
+   *
+   * The result of these suffixes on an integer literal is one of the
+   * standard typedefs such as `std::chrono::hours`.
+   * The result on a floating-point literal is a duration type with the
+   * specified tick period and an unspecified floating-point representation,
+   * for example `1.5e2ms` might be equivalent to
+   * `chrono::duration<long double, chrono::milli>(1.5e2)`.
+   *
+   * @ingroup chrono
+   */
   inline namespace chrono_literals
   {
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wliteral-suffix"
+    /// @cond undocumented
     template<typename _Dur, char... _Digits>
       constexpr _Dur __check_overflow()
       {
@@ -912,56 +994,69 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
                      "literal value cannot be represented by duration type");
        return _Dur(__repval);
       }
+    /// @endcond
 
+    /// Literal suffix for durations representing non-integer hours
     constexpr chrono::duration<long double, ratio<3600,1>>
     operator""h(long double __hours)
     { return chrono::duration<long double, ratio<3600,1>>{__hours}; }
 
+    /// Literal suffix for durations of type `std::chrono::hours`
     template <char... _Digits>
       constexpr chrono::hours
       operator""h()
       { return __check_overflow<chrono::hours, _Digits...>(); }
 
+    /// Literal suffix for durations representing non-integer minutes
     constexpr chrono::duration<long double, ratio<60,1>>
     operator""min(long double __mins)
     { return chrono::duration<long double, ratio<60,1>>{__mins}; }
 
+    /// Literal suffix for durations of type `std::chrono::minutes`
     template <char... _Digits>
       constexpr chrono::minutes
       operator""min()
       { return __check_overflow<chrono::minutes, _Digits...>(); }
 
+    /// Literal suffix for durations representing non-integer seconds
     constexpr chrono::duration<long double>
     operator""s(long double __secs)
     { return chrono::duration<long double>{__secs}; }
 
+    /// Literal suffix for durations of type `std::chrono::seconds`
     template <char... _Digits>
       constexpr chrono::seconds
       operator""s()
       { return __check_overflow<chrono::seconds, _Digits...>(); }
 
+    /// Literal suffix for durations representing non-integer milliseconds
     constexpr chrono::duration<long double, milli>
     operator""ms(long double __msecs)
     { return chrono::duration<long double, milli>{__msecs}; }
 
+    /// Literal suffix for durations of type `std::chrono::milliseconds`
     template <char... _Digits>
       constexpr chrono::milliseconds
       operator""ms()
       { return __check_overflow<chrono::milliseconds, _Digits...>(); }
 
+    /// Literal suffix for durations representing non-integer microseconds
     constexpr chrono::duration<long double, micro>
     operator""us(long double __usecs)
     { return chrono::duration<long double, micro>{__usecs}; }
 
+    /// Literal suffix for durations of type `std::chrono::microseconds`
     template <char... _Digits>
       constexpr chrono::microseconds
       operator""us()
       { return __check_overflow<chrono::microseconds, _Digits...>(); }
 
+    /// Literal suffix for durations representing non-integer nanoseconds
     constexpr chrono::duration<long double, nano>
     operator""ns(long double __nsecs)
     { return chrono::duration<long double, nano>{__nsecs}; }
 
+    /// Literal suffix for durations of type `std::chrono::nanoseconds`
     template <char... _Digits>
       constexpr chrono::nanoseconds
       operator""ns()
@@ -978,8 +1073,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
 #endif // C++14
 
-  // @} group chrono
-
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace std
 

diff --git a/libstdc++-v3/include/std/ratio b/libstdc++-v3/include/std/ratio
index 8bbdcce957b5769e6f836ee2cb7da19c8b1bd036..645525bd30d7c662f5facde095efba72c661dacc 100644 (file)
--- a/libstdc++-v3/include/std/ratio
+++ b/libstdc++-v3/include/std/ratio
@@ -24,6 +24,7 @@
 
 /** @file include/ratio
  *  This is a Standard C++ Library header.
+ *  @ingroup ratio
  */
 
 #ifndef _GLIBCXX_RATIO
@@ -50,6 +51,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    * @{
    */
 
+  /// @cond undocumented
+
   template<intmax_t _Pn>
     struct __static_sign
     : integral_constant<intmax_t, (_Pn < 0) ? -1 : 1>
@@ -243,6 +246,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       static_assert(__rem < __d, "Internal library error");
     };
 
+  /// @endcond
+
   /**
    *  @brief Provides compile-time rational arithmetic.
    *
@@ -280,6 +285,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   template<intmax_t _Num, intmax_t _Den>
     constexpr intmax_t ratio<_Num, _Den>::den;
 
+  /// @cond undocumented
+
   template<typename _R1, typename _R2>
     struct __ratio_multiply
     {
@@ -306,10 +313,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   template<typename _R1, typename _R2>
     constexpr intmax_t __ratio_multiply<_R1, _R2>::den;
 
+  /// @endcond
+
   /// ratio_multiply
   template<typename _R1, typename _R2>
     using ratio_multiply = typename __ratio_multiply<_R1, _R2>::type;
 
+  /// @cond undocumented
+
   template<typename _R1, typename _R2>
     struct __ratio_divide
     {
@@ -329,6 +340,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   template<typename _R1, typename _R2>
     constexpr intmax_t __ratio_divide<_R1, _R2>::den;
 
+  /// @endcond
+
   /// ratio_divide
   template<typename _R1, typename _R2>
     using ratio_divide = typename __ratio_divide<_R1, _R2>::type;
@@ -345,6 +358,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     : integral_constant<bool, !ratio_equal<_R1, _R2>::value>
     { };
 
+  /// @cond undocumented
+
   // Both numbers are positive.
   template<typename _R1, typename _R2,
            typename _Left = __big_mul<_R1::num,_R2::den>,
@@ -375,6 +390,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
            ratio<-_R1::num, _R1::den> >::type
     { };
 
+  /// @endcond
+
   /// ratio_less
   template<typename _R1, typename _R2>
     struct ratio_less
@@ -416,6 +433,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     = ratio_greater_equal<_R1, _R2>::value;
 #endif // C++17
 
+  /// @cond undocumented
+
   template<typename _R1, typename _R2,
       bool = (_R1::num >= 0),
       bool = (_R2::num >= 0),
@@ -499,10 +518,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   template<typename _R1, typename _R2>
     constexpr intmax_t __ratio_add<_R1, _R2>::den;
 
+  /// @endcond
+
   /// ratio_add
   template<typename _R1, typename _R2>
     using ratio_add = typename __ratio_add<_R1, _R2>::type;
 
+  /// @cond undocumented
+
   template<typename _R1, typename _R2>
     struct __ratio_subtract
     {
@@ -520,6 +543,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   template<typename _R1, typename _R2>
     constexpr intmax_t __ratio_subtract<_R1, _R2>::den;
 
+  /// @endcond
+
   /// ratio_subtract
   template<typename _R1, typename _R2>
     using ratio_subtract = typename __ratio_subtract<_R1, _R2>::type;

diff --git a/libstdc++-v3/testsuite/20_util/ratio/cons/cons_overflow_neg.cc b/libstdc++-v3/testsuite/20_util/ratio/cons/cons_overflow_neg.cc
index a4cb0d040eeda34e6724c7ed2aed0d605d57c43f..0dc6bd7e6adf76ff857ee0a3c35d4da77f4760b5 100644 (file)
--- a/libstdc++-v3/testsuite/20_util/ratio/cons/cons_overflow_neg.cc
+++ b/libstdc++-v3/testsuite/20_util/ratio/cons/cons_overflow_neg.cc
@@ -45,7 +45,7 @@ test04()
   std::ratio<1,0> r1 __attribute__((unused)); // { dg-error "required from here" }
 }
 
-// { dg-error "denominator cannot be zero" "" { target *-*-* } 263 }
-// { dg-error "out of range" "" { target *-*-* } 264 }
-// { dg-error "overflow in constant expression" "" { target *-*-* } 59 }
+// { dg-error "denominator cannot be zero" "" { target *-*-* } 0 }
+// { dg-error "out of range" "" { target *-*-* } 0 }
+// { dg-error "overflow in constant expression" "" { target *-*-* } 0 }
 // { dg-prune-output "not a member" }

diff --git a/libstdc++-v3/testsuite/20_util/ratio/operations/ops_overflow_neg.cc b/libstdc++-v3/testsuite/20_util/ratio/operations/ops_overflow_neg.cc
index f74927b9970416ef26e87811a0ecc725bfd87ed0..de6f6276ffee0a393cfb366f8b44c5a1e94bc0ee 100644 (file)
--- a/libstdc++-v3/testsuite/20_util/ratio/operations/ops_overflow_neg.cc
+++ b/libstdc++-v3/testsuite/20_util/ratio/operations/ops_overflow_neg.cc
@@ -41,10 +41,10 @@ test02()
 // { dg-error "required from here" "" { target *-*-* } 28 }
 // { dg-error "expected initializer" "" { target *-*-* } 35 }
 // { dg-error "expected initializer" "" { target *-*-* } 37 }
-// { dg-error "overflow in addition" "" { target *-*-* } 450 }
-// { dg-error "overflow in multiplication" "" { target *-*-* } 95 }
-// { dg-error "overflow in multiplication" "" { target *-*-* } 97 }
-// { dg-error "overflow in multiplication" "" { target *-*-* } 99 }
-// { dg-error "overflow in constant expression" "" { target *-*-* } 106 }
+// { dg-error "overflow in addition" "" { target *-*-* } 0 }
+// { dg-error "overflow in multiplication" "" { target *-*-* } 98 }
+// { dg-error "overflow in multiplication" "" { target *-*-* } 100 }
+// { dg-error "overflow in multiplication" "" { target *-*-* } 102 }
+// { dg-error "overflow in constant expression" "" { target *-*-* } 0 }
 // { dg-prune-output "out of range" }
 // { dg-prune-output "not usable in a constant expression" }