From c6e22902adb34488c80a644cb3ac91e07cd1eaad Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Fri, 4 Dec 1998 19:26:43 +0000 Subject: [PATCH] Added Doc strings -- by Chris Petrilli. --- Modules/cmathmodule.c | 136 ++++++++++++++++++++++++++++++++++----- Modules/mathmodule.c | 145 ++++++++++++++++++++++++++++-------------- 2 files changed, 215 insertions(+), 66 deletions(-) diff --git a/Modules/cmathmodule.c b/Modules/cmathmodule.c index 583a629a2c2..45dad11e060 100644 --- a/Modules/cmathmodule.c +++ b/Modules/cmathmodule.c @@ -48,6 +48,12 @@ static Py_complex c_acos(x) c_sqrt(c_diff(c_1,c_prod(x,x)))))))); } +static char c_acos_doc [] = +"acos(x)\n\ +\n\ +Return the arc cosine of x."; + + static Py_complex c_acosh(x) Py_complex x; { @@ -55,6 +61,12 @@ static Py_complex c_acosh(x) c_sqrt(c_diff(c_1,c_prod(x,x)))))); } +static char c_acosh_doc [] = +"acosh(x)\n\ +\n\ +Return the hyperbolic cosine of x."; + + static Py_complex c_asin(x) Py_complex x; { @@ -62,24 +74,48 @@ static Py_complex c_asin(x) c_sqrt(c_diff(c_1,c_prod(x,x))))))); } +static char c_asin_doc [] = +"asin(x)\n\ +\n\ +Return the arc sine of x."; + + static Py_complex c_asinh(x) Py_complex x; { return c_neg(c_log(c_diff(c_sqrt(c_sum(c_1,c_prod(x,x))),x))); } +static char c_asinh_doc [] = +"asinh(x)\n\ +\n\ +Return the hyperbolic arc sine of x."; + + static Py_complex c_atan(x) Py_complex x; { return c_prod(c_i2,c_log(c_quot(c_sum(c_i,x),c_diff(c_i,x)))); } +static char c_atan_doc [] = +"atan(x)\n\ +\n\ +Return the arc tangent of x."; + + static Py_complex c_atanh(x) Py_complex x; { return c_prod(c_half,c_log(c_quot(c_sum(c_1,x),c_diff(c_1,x)))); } +static char c_atanh_doc [] = +"atanh(x)\n\ +\n\ +Return the hyperbolic arc tangent of x."; + + static Py_complex c_cos(x) Py_complex x; { @@ -89,6 +125,12 @@ static Py_complex c_cos(x) return r; } +static char c_cos_doc [] = +"cos(x)\n\ +\n\ +Return the cosine of x."; + + static Py_complex c_cosh(x) Py_complex x; { @@ -98,6 +140,12 @@ static Py_complex c_cosh(x) return r; } +static char c_cosh_doc [] = +"cosh(x)\n\ +\n\ +Return the hyperbolic cosine of x."; + + static Py_complex c_exp(x) Py_complex x; { @@ -108,6 +156,12 @@ static Py_complex c_exp(x) return r; } +static char c_exp_doc [] = +"exp(x)\n\ +\n\ +Return the exponential value e**x."; + + static Py_complex c_log(x) Py_complex x; { @@ -118,6 +172,12 @@ static Py_complex c_log(x) return r; } +static char c_log_doc [] = +"log(x)\n\ +\n\ +Return the natural logarithm of x."; + + static Py_complex c_log10(x) Py_complex x; { @@ -128,6 +188,13 @@ static Py_complex c_log10(x) return r; } +static char c_log10_doc [] = +"log10(x)\n\ +\n\ +Return the base-10 logarithm of x."; + + +/* internal function not available from Python */ static Py_complex c_prodi(x) Py_complex x; { @@ -137,6 +204,7 @@ static Py_complex c_prodi(x) return r; } + static Py_complex c_sin(x) Py_complex x; { @@ -146,6 +214,12 @@ static Py_complex c_sin(x) return r; } +static char c_sin_doc [] = +"sin(x)\n\ +\n\ +Return the sine of x."; + + static Py_complex c_sinh(x) Py_complex x; { @@ -155,6 +229,12 @@ static Py_complex c_sinh(x) return r; } +static char c_sinh_doc [] = +"sinh(x)\n\ +\n\ +Return the hyperbolic sine of x."; + + static Py_complex c_sqrt(x) Py_complex x; { @@ -181,6 +261,12 @@ static Py_complex c_sqrt(x) return r; } +static char c_sqrt_doc [] = +"sqrt(x)\n\ +\n\ +Return the square root of x."; + + static Py_complex c_tan(x) Py_complex x; { @@ -202,6 +288,12 @@ static Py_complex c_tan(x) return r; } +static char c_tan_doc [] = +"tan(x)\n\ +\n\ +Return the tangent of x."; + + static Py_complex c_tanh(x) Py_complex x; { @@ -223,6 +315,11 @@ static Py_complex c_tanh(x) return r; } +static char c_tanh_doc [] = +"tanh(x)\n\ +\n\ +Return the hyperbolic tangent of x."; + /* And now the glue to make them available from Python: */ @@ -281,23 +378,28 @@ FUNC1(cmath_tan, c_tan) FUNC1(cmath_tanh, c_tanh) +static char module_doc [] = +"This module is always available. It provides access to mathematical\n\ +functions for complex numbers."; + + static PyMethodDef cmath_methods[] = { - {"acos", cmath_acos, 1}, - {"acosh", cmath_acosh, 1}, - {"asin", cmath_asin, 1}, - {"asinh", cmath_asinh, 1}, - {"atan", cmath_atan, 1}, - {"atanh", cmath_atanh, 1}, - {"cos", cmath_cos, 1}, - {"cosh", cmath_cosh, 1}, - {"exp", cmath_exp, 1}, - {"log", cmath_log, 1}, - {"log10", cmath_log10, 1}, - {"sin", cmath_sin, 1}, - {"sinh", cmath_sinh, 1}, - {"sqrt", cmath_sqrt, 1}, - {"tan", cmath_tan, 1}, - {"tanh", cmath_tanh, 1}, + {"acos", cmath_acos, 1, c_acos_doc}, + {"acosh", cmath_acosh, 1, c_acosh_doc}, + {"asin", cmath_asin, 1, c_asin_doc}, + {"asinh", cmath_asinh, 1, c_asinh_doc}, + {"atan", cmath_atan, 1, c_atan_doc}, + {"atanh", cmath_atanh, 1, c_atanh_doc}, + {"cos", cmath_cos, 1, c_cos_doc}, + {"cosh", cmath_cosh, 1, c_cosh_doc}, + {"exp", cmath_exp, 1, c_exp_doc}, + {"log", cmath_log, 1, c_log_doc}, + {"log10", cmath_log10, 1, c_log10_doc}, + {"sin", cmath_sin, 1, c_sin_doc}, + {"sinh", cmath_sinh, 1, c_sinh_doc}, + {"sqrt", cmath_sqrt, 1, c_sqrt_doc}, + {"tan", cmath_tan, 1, c_tan_doc}, + {"tanh", cmath_tanh, 1, c_tanh_doc}, {NULL, NULL} /* sentinel */ }; @@ -306,7 +408,7 @@ initcmath() { PyObject *m, *d, *v; - m = Py_InitModule("cmath", cmath_methods); + m = Py_InitModule3("cmath", cmath_methods, module_doc); d = PyModule_GetDict(m); PyDict_SetItemString(d, "pi", v = PyFloat_FromDouble(atan(1.0) * 4.0)); diff --git a/Modules/mathmodule.c b/Modules/mathmodule.c index 7c11e6feb69..1d559e1e962 100644 --- a/Modules/mathmodule.c +++ b/Modules/mathmodule.c @@ -109,40 +109,63 @@ math_2(args, func) return PyFloat_FromDouble(x); } -#define FUNC1(stubname, func) \ +#define FUNC1(stubname, func, docstring_name, docstring) \ static PyObject * stubname(self, args) PyObject *self, *args; { \ return math_1(args, func); \ - } + }\ + static char docstring_name [] = docstring; -#define FUNC2(stubname, func) \ +#define FUNC2(stubname, func, docstring_name, docstring) \ static PyObject * stubname(self, args) PyObject *self, *args; { \ return math_2(args, func); \ - } + }\ + static char docstring_name [] = docstring; -FUNC1(math_acos, acos) -FUNC1(math_asin, asin) -FUNC1(math_atan, atan) -FUNC2(math_atan2, atan2) -FUNC1(math_ceil, ceil) -FUNC1(math_cos, cos) -FUNC1(math_cosh, cosh) -FUNC1(math_exp, exp) -FUNC1(math_fabs, fabs) -FUNC1(math_floor, floor) -FUNC2(math_fmod, fmod) -FUNC2(math_hypot, hypot) -FUNC1(math_log, log) -FUNC1(math_log10, log10) +FUNC1(math_acos, acos, math_acos_doc, + "acos(x)\n\nReturn the arc cosine of x.") +FUNC1(math_asin, asin, math_asin_doc, + "asin(x)\n\nReturn the arc sine of x.") +FUNC1(math_atan, atan, math_atan_doc, + "atan(x)\n\nReturn the arc tangent of x.") +FUNC2(math_atan2, atan2, math_atan2_doc, + "atan2(x)\n\nReturn atan(x /y).") +FUNC1(math_ceil, ceil, math_ceil_doc, + "ceil(x)\n\nReturn the ceiling of x as a real.") +FUNC1(math_cos, cos, math_cos_doc, + "cos(x)\n\nReturn the cosine of x.") +FUNC1(math_cosh, cosh, math_cosh_doc, + "cosh(x)\n\nReturn the hyperbolic cosine of x.") +FUNC1(math_exp, exp, math_exp_doc, + "exp(x)\n\nReturn e raised to the power of x.") +FUNC1(math_fabs, fabs, math_fabs_doc, + "fabs(x)\n\nReturn the absolute value of the real x.") +FUNC1(math_floor, floor, math_floor_doc, + "floor(x)\n\nReturn the floor of x as a real.") +FUNC2(math_fmod, fmod, math_fmod_doc, + "fmod(x,y)\n\nReturn x % y.") +FUNC2(math_hypot, hypot, math_hypot_doc, + "hypot(x,y)\n\nReturn the Euclidean distance, sqrt(x*x + y*y).") +FUNC1(math_log, log, math_log_doc, + "log(x)\n\nReturn the natural logarithm of x.") +FUNC1(math_log10, log10, math_log10_doc, + "log10(x)\n\nReturn the base-10 logarithm of x.") #ifdef MPW_3_1 /* This hack is needed for MPW 3.1 but not for 3.2 ... */ -FUNC2(math_pow, power) +FUNC2(math_pow, power, math_pow_doc, + "power(x,y)\n\nReturn x**y.") #else -FUNC2(math_pow, pow) +FUNC2(math_pow, pow, math_pow_doc, + "pow(x,y)\n\nReturn x**y.") #endif -FUNC1(math_sin, sin) -FUNC1(math_sinh, sinh) -FUNC1(math_sqrt, sqrt) -FUNC1(math_tan, tan) -FUNC1(math_tanh, tanh) +FUNC1(math_sin, sin, math_sin_doc, + "sin(x)\n\nReturn the sine of x.") +FUNC1(math_sinh, sinh, math_sinh_doc, + "sinh(x)\n\nReturn the hyperbolic sine of x.") +FUNC1(math_sqrt, sqrt, math_sqrt_doc, + "sqrt(x)\n\nReturn the square root of x.") +FUNC1(math_tan, tan, math_tan_doc, + "tan(x)\n\nReturn the tangent of x.") +FUNC1(math_tanh, tanh, math_tanh_doc, + "tanh(x)\n\nReturn the hyperbolic tangent of x.") static PyObject * @@ -162,6 +185,12 @@ math_frexp(self, args) return Py_BuildValue("(di)", x, i); } +static char math_frexp_doc [] = +"frexp(x)\n\ +\n\ +Return the matissa and exponent for x. The mantissa is positive."; + + static PyObject * math_ldexp(self, args) PyObject *self; @@ -182,6 +211,12 @@ math_ldexp(self, args) return PyFloat_FromDouble(x); } +static char math_ldexp_doc [] = +"ldexp_doc(x, i)\n\ +\n\ +Return x * (2**i)."; + + static PyObject * math_modf(self, args) PyObject *self; @@ -206,39 +241,51 @@ math_modf(self, args) return Py_BuildValue("(dd)", x, y); } +static char math_modf_doc [] = +"modf(x)\n\ +\n\ +Return the fractional and integer parts of x. Both results carry the sign\n\ +of x. The integer part is returned as a real."; + + static PyMethodDef math_methods[] = { - {"acos", math_acos}, - {"asin", math_asin}, - {"atan", math_atan}, - {"atan2", math_atan2}, - {"ceil", math_ceil}, - {"cos", math_cos}, - {"cosh", math_cosh}, - {"exp", math_exp}, - {"fabs", math_fabs}, - {"floor", math_floor}, - {"fmod", math_fmod}, - {"frexp", math_frexp}, - {"hypot", math_hypot}, - {"ldexp", math_ldexp}, - {"log", math_log}, - {"log10", math_log10}, - {"modf", math_modf}, - {"pow", math_pow}, - {"sin", math_sin}, - {"sinh", math_sinh}, - {"sqrt", math_sqrt}, - {"tan", math_tan}, - {"tanh", math_tanh}, + {"acos", math_acos, 0, math_acos_doc}, + {"asin", math_asin, 0, math_asin_doc}, + {"atan", math_atan, 0, math_atan_doc}, + {"atan2", math_atan2, 0, math_atan2_doc}, + {"ceil", math_ceil, 0, math_ceil_doc}, + {"cos", math_cos, 0, math_cos_doc}, + {"cosh", math_cosh, 0, math_cosh_doc}, + {"exp", math_exp, 0, math_exp_doc}, + {"fabs", math_fabs, 0, math_fabs_doc}, + {"floor", math_floor, 0, math_floor_doc}, + {"fmod", math_fmod, 0, math_fmod_doc}, + {"frexp", math_frexp, 0, math_frexp_doc}, + {"hypot", math_hypot, 0, math_hypot_doc}, + {"ldexp", math_ldexp, 0, math_ldexp_doc}, + {"log", math_log, 0, math_log_doc}, + {"log10", math_log10, 0, math_log10_doc}, + {"modf", math_modf, 0, math_modf_doc}, + {"pow", math_pow, 0, math_pow_doc}, + {"sin", math_sin, 0, math_sin_doc}, + {"sinh", math_sinh, 0, math_sinh_doc}, + {"sqrt", math_sqrt, 0, math_sqrt_doc}, + {"tan", math_tan, 0, math_tan_doc}, + {"tanh", math_tanh, 0, math_tanh_doc}, {NULL, NULL} /* sentinel */ }; + +static char module_doc [] = +"This module is always available. It provides access to the\n\ +mathematical functions defined by the C standard."; + DL_EXPORT(void) initmath() { PyObject *m, *d, *v; - m = Py_InitModule("math", math_methods); + m = Py_InitModule3("math", math_methods, module_doc); d = PyModule_GetDict(m); if (!(v = PyFloat_FromDouble(atan(1.0) * 4.0)))