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

3 files changed, 56 insertions, 39 deletions

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index a646986..596d485 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,5 +1,9 @@
 2019-05-02  Jonathan Wakely  <jwakely@redhat.com>
 
+	* 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 28f9eb4..1ddac57 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,
    * <a href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1836.pdf">
    * TR1</a>, 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 mathsf_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<Tp>::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, <tt>long double</tt> 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 <a href="http://www.gnu.org/software/gsl">
    * Gnu Scientific Library, GSL</a> and
-   * <a href="http://www.boost.org/doc/libs/1_60_0/libs/math/doc/html/index.html>Boost</a>
+   * <a href="http://www.boost.org/doc/libs/1_60_0/libs/math/doc/html/index.html">Boost</a>
    * 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<sup>-15</sup> 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 4ff8241..3e7276b 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 <bits/stl_algobase.h>
 #include <limits>
 #include <tr1/type_traits>
@@ -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<float>(__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