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  <3dw...@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.

Reply via email to