Document C++ Special Math Functions.

[Jonathan Wakely]

On 08/04/16 16:36 -0400, Ed Smith-Rowland wrote:
>I wanted to ship the TR29124 special math functions in libstdc++ with 
>some documentation.
>More could be done but this covers the function definitions, argument 
>ranges, template parms, and arguments.
>There is a little mainpage with some overview, history, biblio, and links.

This is great, thank you.

As this is only a documentation change it's OK for trunk with the typo
fixes noted below.


>2016-04-08  Edward Smith-Rowland  <3dw4rd@verizon.net>
>
>	Document C++19/TR29124 C++ Special Math Functions.
>	* include/bits/specfun.h: Add Doxygen markup.

s/C++19/C++17/

>Index: include/bits/specfun.h
>===================================================================
>--- include/bits/specfun.h	(revision 234525)
>+++ include/bits/specfun.h	(working copy)
>@@ -75,16 +75,182 @@
>    * @{
>    */
>
>+  /**
>+   * @mainpage Mathematical Special Functions
>+   *
>+   * @section 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 significntly

s/significntly/significantly/

>+   * extended the standard trancendental functions inherited from C and declared

s/trancendental/transcendental/

>+   * in @<cmath@>.
>+   *
>+   * Although most components from TR1 were eventually adopted for C++11 these
>+   * math function were left behind out of concern for implementability.
>+   * The math functions were published as a separate international standard
>+   * <a href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2010/n3060.pdf">
>+   * IS 29124 - Extensions to the C++ Library to Support Mathematical Special
>+   * Functions</a>.
>+   *
>+   * For C++17 these functions were incorporated into the main standard.
>+   *
>+   * @section contents Contents
>+   * The folowing functions are implemented in namespace @c std:

s/folowing/following/

>+   * - @ref assoc_laguerre "assoc_laguerre - Associated Laguerre functions"
>+   * - @ref assoc_legendre "assoc_legendre - Associated Legendre functions"
>+   * - @ref beta "beta - Beta functions"
>+   * - @ref comp_ellint_1 "comp_ellint_1 - Complete elliptic functions of the first kind"
>+   * - @ref comp_ellint_2 "comp_ellint_2 - Complete elliptic functions of the second kind"
>+   * - @ref comp_ellint_3 "comp_ellint_3 - Complete elliptic functions of the third kind"
>+   * - @ref cyl_bessel_i "cyl_bessel_i - Regular modified cylindrical Bessel functions"
>+   * - @ref cyl_bessel_j "cyl_bessel_j - Cylindrical Bessel functions of the first kind"
>+   * - @ref cyl_bessel_k "cyl_bessel_k - Irregular modified cylindrical Bessel functions"
>+   * - @ref cyl_neumann "cyl_neumann - Cylindrical Neumann functions or Cylindrical Bessel functions of the second kind"
>+   * - @ref ellint_1 "ellint_1 - Incomplete elliptic functions of the first kind"
>+   * - @ref ellint_2 "ellint_2 - Incomplete elliptic functions of the second kind"
>+   * - @ref ellint_3 "ellint_3 - Incomplete elliptic functions of the third kind"
>+   * - @ref expint "expint - The exponential integral"
>+   * - @ref hermite "hermite - Hermite polynomials"
>+   * - @ref laguerre "laguerre - Laguerre functions"
>+   * - @ref legendre "legendre - Legendre polynomials"
>+   * - @ref riemann_zeta "riemann_zeta - The Riemann zeta function"
>+   * - @ref sph_bessel "sph_bessel - Spherical Bessel functions"
>+   * - @ref sph_legendre "sph_legendre - Spherical Legendre functions"
>+   * - @ref sph_neumann "sph_neumann - Spherical Neumann functions"
>+   *
>+   * The hypergeometric functions were stricken from the TR29124 and C++17
>+   * versions of this math library because of implementation concerns.
>+   * However, since they were in the TR1 version and since they are popular
>+   * we kept them as an extension in namespace @c __gnu_cxx:
>+   * - @ref conf_hyperg "conf_hyperg - Confluent hypergeometric functions"
>+   * - @ref hyperg "hyperg - Hypergeometric functions"
>+   *
>+   * @section general General Features
>+   *
>+   * @subsection "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 opint is given an integral value
>+   * That integral value is promoted to double.
>+   * 2. All floating point arguments are promoted up to the largest floating
>+   *    point precision among them.
>+   *
>+   * @subsection 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
>+   *
>+   * We strive to implement the underlying math with type generic algorithms
>+   * to the greatest extent possible.  In practice, the function are thin

s/function/functions/

>+   * wrappers that dispatch to function templates. Type dependence is
>+   * controlled with std::numeric_limits and functions thereof.
>+   *
>+   * We don't promote *c float to *c double or *c double to <tt>long double</tt>

Does *c work for Doxygen here, or should it be @c?

>+   * reflexively.  The goal is for float functions to operate more quickly,
>+   * at the cost of float accuracy and possibly a smaller domain of validity.
>+   * Similaryly, <tt>long double</tt> should give you more dynamic range
>+   * and slightly more pecision than @c double on many systems.