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.
