From d16250de4a4c8a63ebf68095dfb18581b655734c Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Thu, 2 May 2019 16:44:59 +0100 Subject: [PATCH] Improve API docs for mathematical special functions This prevents "Mathematical Special Functions" appearing in the top-level menu of the generated HTML docs, and adds "TR1" to the title for the TR1 docs, to avoid duplicate titles. * include/bits/specfun.h: Improve docs. * include/tr1/cmath: Likewise. Fix nesting of preprocessor conditions and namespaces. From-SVN: r270806 --- libstdc++-v3/ChangeLog | 4 +++ libstdc++-v3/include/bits/specfun.h | 39 ++++++++++++---------- libstdc++-v3/include/tr1/cmath | 52 +++++++++++++++++------------ 3 files changed, 56 insertions(+), 39 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index a6469868368..596d485ff0f 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,5 +1,9 @@ 2019-05-02 Jonathan Wakely + * include/bits/specfun.h: Improve docs. + * include/tr1/cmath: Likewise. Fix nesting of preprocessor conditions + and namespaces. + * doc/doxygen/doxygroups.cc (std::tr2, std::__gnu_cxx): Improve docs. (std::experimental): Add docs. * doc/doxygen/user.cfg.in (PREDEFINED): Expand macros for __cxx11 diff --git a/libstdc++-v3/include/bits/specfun.h b/libstdc++-v3/include/bits/specfun.h index 28f9eb46f3a..1ddac5773ae 100644 --- a/libstdc++-v3/include/bits/specfun.h +++ b/libstdc++-v3/include/bits/specfun.h @@ -66,15 +66,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * @defgroup mathsf Mathematical Special Functions * @ingroup numerics * + * @section mathsf_desc Mathematical Special Functions + * * A collection of advanced mathematical special functions, - * defined by ISO/IEC IS 29124. - * @{ - */ - - /** - * @mainpage Mathematical Special Functions + * defined by ISO/IEC IS 29124 and then added to ISO C++ 2017. * - * @section intro Introduction and History + * + * @subsection mathsf_intro Introduction and History * The first significant library upgrade on the road to C++2011, * * TR1, included a set of 23 mathematical functions that significantly @@ -90,7 +88,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * * For C++17 these functions were incorporated into the main standard. * - * @section contents Contents + * @subsection mathsf_contents Contents * The following functions are implemented in namespace @c std: * - @ref assoc_laguerre "assoc_laguerre - Associated Laguerre functions" * - @ref assoc_legendre "assoc_legendre - Associated Legendre functions" @@ -121,9 +119,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * - @ref __gnu_cxx::conf_hyperg "conf_hyperg - Confluent hypergeometric functions" * - @ref __gnu_cxx::hyperg "hyperg - Hypergeometric functions" * - * @section general General Features + * * - * @subsection promotion Argument Promotion + * @subsection mathsf_promotion Argument Promotion * The arguments suppled to the non-suffixed functions will be promoted * according to the following rules: * 1. If any argument intended to be floating point is given an integral value @@ -131,12 +129,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * 2. All floating point arguments are promoted up to the largest floating * point precision among them. * - * @subsection NaN NaN Arguments + * @subsection mathsf_NaN NaN Arguments * If any of the floating point arguments supplied to these functions is * invalid or NaN (std::numeric_limits::quiet_NaN), * the value NaN is returned. * - * @section impl Implementation + * @subsection mathsf_impl Implementation * * We strive to implement the underlying math with type generic algorithms * to the greatest extent possible. In practice, the functions are thin @@ -149,23 +147,23 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * Similaryly, long double should give you more dynamic range * and slightly more pecision than @c double on many systems. * - * @section testing Testing + * @subsection mathsf_testing Testing * * These functions have been tested against equivalent implementations * from the * Gnu Scientific Library, GSL and - * Boost * and the ratio * @f[ * \frac{|f - f_{test}|}{|f_{test}|} * @f] - * is generally found to be within 10^-15 for 64-bit double on linux-x86_64 systems - * over most of the ranges of validity. + * is generally found to be within 10-15 for 64-bit double on + * linux-x86_64 systems over most of the ranges of validity. * * @todo Provide accuracy comparisons on a per-function basis for a small * number of targets. * - * @section bibliography General Bibliography + * @subsection mathsf_bibliography General Bibliography * * @see Abramowitz and Stegun: Handbook of Mathematical Functions, * with Formulas, Graphs, and Mathematical Tables @@ -192,6 +190,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * * @see The Special Functions and Their Approximations: Volumes 1 and 2, * by Yudell L. Luke, Academic Press, 1969 + * + * @{ */ // Associated Laguerre polynomials @@ -1206,6 +1206,10 @@ namespace __gnu_cxx _GLIBCXX_VISIBILITY(default) { _GLIBCXX_BEGIN_NAMESPACE_VERSION + /** @addtogroup mathsf + * @{ + */ + // Airy functions /** @@ -1376,6 +1380,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return std::__detail::__hyperg<__type>(__a, __b, __c, __x); } + // @} _GLIBCXX_END_NAMESPACE_VERSION } // namespace __gnu_cxx #endif // __STRICT_ANSI__ diff --git a/libstdc++-v3/include/tr1/cmath b/libstdc++-v3/include/tr1/cmath index 4ff82419c25..3e7276bcf00 100644 --- a/libstdc++-v3/include/tr1/cmath +++ b/libstdc++-v3/include/tr1/cmath @@ -1126,16 +1126,25 @@ namespace tr1 #endif // C++11 +} // namespace tr1 +_GLIBCXX_END_NAMESPACE_VERSION +} // namespace std + +/** + * @defgroup tr1_math_spec_func TR1 Mathematical Special Functions + * @ingroup numerics + * + * A collection of advanced mathematical special functions. + */ + #if _GLIBCXX_USE_STD_SPEC_FUNCS - /** - * @defgroup tr1_math_spec_func Mathematical Special Functions - * @ingroup numerics - * - * A collection of advanced mathematical special functions. - * @{ - */ +namespace std _GLIBCXX_VISIBILITY(default) +{ +_GLIBCXX_BEGIN_NAMESPACE_VERSION +namespace tr1 +{ using std::assoc_laguerref; using std::assoc_laguerrel; using std::assoc_laguerre; @@ -1220,15 +1229,12 @@ namespace tr1 using std::sph_neumannl; using std::sph_neumann; - /* @} */ // tr1_math_spec_func - -#else // ! _GLIBCXX_USE_STD_SPEC_FUNCS - } // namespace tr1 - _GLIBCXX_END_NAMESPACE_VERSION } // namespace std +#else // ! _GLIBCXX_USE_STD_SPEC_FUNCS + #include #include #include @@ -1247,15 +1253,10 @@ _GLIBCXX_END_NAMESPACE_VERSION namespace std _GLIBCXX_VISIBILITY(default) { _GLIBCXX_BEGIN_NAMESPACE_VERSION - namespace tr1 -{ - /** - * @defgroup tr1_math_spec_func Mathematical Special Functions - * @ingroup numerics - * - * A collection of advanced mathematical special functions. - * @{ + { + /** @addtogroup tr1_math_spec_func + * @{ */ inline float @@ -1617,14 +1618,15 @@ namespace tr1 return __detail::__sph_neumann<__type>(__n, __x); } - /* @} */ // tr1_math_spec_func -#endif // _GLIBCXX_USE_STD_SPEC_FUNCS + // @} tr1_math_spec_func } // namespace tr1 _GLIBCXX_END_NAMESPACE_VERSION } // namespace std +#endif // _GLIBCXX_USE_STD_SPEC_FUNCS + #if _GLIBCXX_USE_STD_SPEC_FUNCS && !defined(__STRICT_ANSI__) namespace std _GLIBCXX_VISIBILITY(default) { @@ -1658,6 +1660,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION namespace tr1 { + /** @addtogroup tr1_math_spec_func + * @{ + */ + inline float conf_hypergf(float __a, float __c, float __x) { return __detail::__conf_hyperg(__a, __c, __x); } @@ -1692,6 +1698,8 @@ namespace tr1 return __detail::__hyperg<__type>(__a, __b, __c, __x); } + // @} tr1_math_spec_func + } // namespace tr1 _GLIBCXX_END_NAMESPACE_VERSION -- 2.30.2