From c34d3fd3068c5f991f75017023ba8eb36879ffa3 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Tue, 7 May 2019 23:46:53 +0100 Subject: [PATCH] Improve API docs for and * 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 --- libstdc++-v3/ChangeLog | 8 ++ libstdc++-v3/doc/doxygen/doxygroups.cc | 3 + libstdc++-v3/include/std/chrono | 97 ++++++++++++++++++- libstdc++-v3/include/std/ratio | 25 +++++ .../20_util/ratio/cons/cons_overflow_neg.cc | 6 +- .../ratio/operations/ops_overflow_neg.cc | 10 +- 6 files changed, 139 insertions(+), 10 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index fb69a3d1050..5c668bac172 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,5 +1,13 @@ 2019-05-07 Jonathan Wakely + * 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 630e02296ed..94ef3bb4f65 100644 --- 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 b7c1d750067..1f2c8799b5b 100644 --- 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 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 struct common_type, 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 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 struct common_type, chrono::time_point<_Clock, _Duration2>> : __timepoint_common_type, _Clock> { }; + // @} group chrono + namespace chrono { + /// @addtogroup chrono + /// @{ + + /// @cond undocumented + // Primary template for duration_cast impl. template @@ -188,6 +208,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION using __disable_if_is_duration = typename enable_if::value, _Tp>::type; + /// @endcond + /// duration_cast template constexpr __enable_if_is_duration<_ToDur> @@ -288,6 +310,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { return numeric_limits<_Rep>::lowest(); } }; + /// @cond undocumented + template struct __is_ratio : std::false_type @@ -298,6 +322,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION : std::true_type { }; + /// @endcond + /// duration template struct duration @@ -446,6 +472,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION rep __r; }; + /// @relates duration @{ + + /// The sum of two durations. template constexpr typename common_type, @@ -459,6 +488,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return __cd(__cd(__lhs).count() + __cd(__rhs).count()); } + /// The difference between two durations. template constexpr typename common_type, @@ -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::value, _CRep>::type; + /// @endcond + + /// @relates duration @{ + + /// Multiply a duration by a scalar value. template 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 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 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 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 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 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 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(1.5e2)`. + * + * @ingroup chrono + */ inline namespace chrono_literals { #pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wliteral-suffix" + /// @cond undocumented template 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> operator""h(long double __hours) { return chrono::duration>{__hours}; } + /// Literal suffix for durations of type `std::chrono::hours` template constexpr chrono::hours operator""h() { return __check_overflow(); } + /// Literal suffix for durations representing non-integer minutes constexpr chrono::duration> operator""min(long double __mins) { return chrono::duration>{__mins}; } + /// Literal suffix for durations of type `std::chrono::minutes` template constexpr chrono::minutes operator""min() { return __check_overflow(); } + /// Literal suffix for durations representing non-integer seconds constexpr chrono::duration operator""s(long double __secs) { return chrono::duration{__secs}; } + /// Literal suffix for durations of type `std::chrono::seconds` template constexpr chrono::seconds operator""s() { return __check_overflow(); } + /// Literal suffix for durations representing non-integer milliseconds constexpr chrono::duration operator""ms(long double __msecs) { return chrono::duration{__msecs}; } + /// Literal suffix for durations of type `std::chrono::milliseconds` template constexpr chrono::milliseconds operator""ms() { return __check_overflow(); } + /// Literal suffix for durations representing non-integer microseconds constexpr chrono::duration operator""us(long double __usecs) { return chrono::duration{__usecs}; } + /// Literal suffix for durations of type `std::chrono::microseconds` template constexpr chrono::microseconds operator""us() { return __check_overflow(); } + /// Literal suffix for durations representing non-integer nanoseconds constexpr chrono::duration operator""ns(long double __nsecs) { return chrono::duration{__nsecs}; } + /// Literal suffix for durations of type `std::chrono::nanoseconds` template 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 8bbdcce957b..645525bd30d 100644 --- 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 struct __static_sign : integral_constant @@ -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 constexpr intmax_t ratio<_Num, _Den>::den; + /// @cond undocumented + template struct __ratio_multiply { @@ -306,10 +313,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION template constexpr intmax_t __ratio_multiply<_R1, _R2>::den; + /// @endcond + /// ratio_multiply template using ratio_multiply = typename __ratio_multiply<_R1, _R2>::type; + /// @cond undocumented + template struct __ratio_divide { @@ -329,6 +340,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION template constexpr intmax_t __ratio_divide<_R1, _R2>::den; + /// @endcond + /// ratio_divide template using ratio_divide = typename __ratio_divide<_R1, _R2>::type; @@ -345,6 +358,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION : integral_constant::value> { }; + /// @cond undocumented + // Both numbers are positive. template, @@ -375,6 +390,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ratio<-_R1::num, _R1::den> >::type { }; + /// @endcond + /// ratio_less template struct ratio_less @@ -416,6 +433,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION = ratio_greater_equal<_R1, _R2>::value; #endif // C++17 + /// @cond undocumented + template= 0), bool = (_R2::num >= 0), @@ -499,10 +518,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION template constexpr intmax_t __ratio_add<_R1, _R2>::den; + /// @endcond + /// ratio_add template using ratio_add = typename __ratio_add<_R1, _R2>::type; + /// @cond undocumented + template struct __ratio_subtract { @@ -520,6 +543,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION template constexpr intmax_t __ratio_subtract<_R1, _R2>::den; + /// @endcond + /// ratio_subtract template 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 a4cb0d040ee..0dc6bd7e6ad 100644 --- 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 f74927b9970..de6f6276ffe 100644 --- 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" } -- 2.30.2