From 30dd23aa7f2c7f142bab66d189f7f479091cf161 Mon Sep 17 00:00:00 2001 From: Damien George Date: Sun, 10 Aug 2014 17:50:28 +0100 Subject: [PATCH] doc: Document gc, sys, math, cmath. --- py/modcmath.c | 19 +++++++++++++++++ py/modgc.c | 12 +++++++++++ py/modmath.c | 54 +++++++++++++++++++++++++++++++++++++++++++++++ py/modsys.c | 15 +++++++++++-- stmhal/main.c | 4 ++++ stmhal/pybstdio.c | 4 ++++ 6 files changed, 106 insertions(+), 2 deletions(-) diff --git a/py/modcmath.c b/py/modcmath.c index ddd8abf71e..6fdd1f77b7 100644 --- a/py/modcmath.c +++ b/py/modcmath.c @@ -34,10 +34,19 @@ #if MICROPY_PY_BUILTINS_FLOAT && MICROPY_PY_CMATH +/// \module cmath - mathematical functions for complex numbers +/// +/// The `cmath` module provides some basic mathematical funtions for +/// working with complex numbers. + // These are defined in modmath.c +/// \constant e - base of the natural logarithm extern const mp_obj_float_t mp_math_e_obj; +/// \constant pi - the ratio of a circle's circumference to its diameter extern const mp_obj_float_t mp_math_pi_obj; +/// \function phase(z) +/// Returns the phase of the number `z`, in the range (-pi, +pi]. mp_obj_t mp_cmath_phase(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); @@ -45,6 +54,8 @@ mp_obj_t mp_cmath_phase(mp_obj_t z_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_phase_obj, mp_cmath_phase); +/// \function polar(z) +/// Returns, as a tuple, the polar form of `z`. mp_obj_t mp_cmath_polar(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); @@ -56,6 +67,8 @@ mp_obj_t mp_cmath_polar(mp_obj_t z_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_polar_obj, mp_cmath_polar); +/// \function rect(r, phi) +/// Returns the complex number with modules `r` and phase `phi`. mp_obj_t mp_cmath_rect(mp_obj_t r_obj, mp_obj_t phi_obj) { mp_float_t r = mp_obj_get_float(r_obj); mp_float_t phi = mp_obj_get_float(phi_obj); @@ -63,6 +76,7 @@ mp_obj_t mp_cmath_rect(mp_obj_t r_obj, mp_obj_t phi_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(mp_cmath_rect_obj, mp_cmath_rect); +/// \function exp(z) mp_obj_t mp_cmath_exp(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); @@ -71,6 +85,7 @@ mp_obj_t mp_cmath_exp(mp_obj_t z_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_exp_obj, mp_cmath_exp); +/// \function log(z) // TODO can take second argument, being the base mp_obj_t mp_cmath_log(mp_obj_t z_obj) { mp_float_t real, imag; @@ -79,6 +94,7 @@ mp_obj_t mp_cmath_log(mp_obj_t z_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_log_obj, mp_cmath_log); +/// \function log10(z) mp_obj_t mp_cmath_log10(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); @@ -86,6 +102,7 @@ mp_obj_t mp_cmath_log10(mp_obj_t z_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_log10_obj, mp_cmath_log10); +/// \function sqrt(z) mp_obj_t mp_cmath_sqrt(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); @@ -95,6 +112,7 @@ mp_obj_t mp_cmath_sqrt(mp_obj_t z_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_sqrt_obj, mp_cmath_sqrt); +/// \function cos(z) mp_obj_t mp_cmath_cos(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); @@ -102,6 +120,7 @@ mp_obj_t mp_cmath_cos(mp_obj_t z_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_cos_obj, mp_cmath_cos); +/// \function sin(z) mp_obj_t mp_cmath_sin(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); diff --git a/py/modgc.c b/py/modgc.c index 5fed2d8861..8c5a7053ae 100644 --- a/py/modgc.c +++ b/py/modgc.c @@ -37,8 +37,12 @@ #if MICROPY_PY_GC && MICROPY_ENABLE_GC +/// \module gc - control the garbage collector + extern uint gc_collected; +/// \function collect() +/// Run a garbage collection. STATIC mp_obj_t py_gc_collect(void) { gc_collect(); #if MICROPY_PY_GC_COLLECT_RETVAL @@ -49,18 +53,24 @@ STATIC mp_obj_t py_gc_collect(void) { } MP_DEFINE_CONST_FUN_OBJ_0(gc_collect_obj, py_gc_collect); +/// \function disable() +/// Disable the garbage collector. STATIC mp_obj_t gc_disable(void) { gc_lock(); return mp_const_none; } MP_DEFINE_CONST_FUN_OBJ_0(gc_disable_obj, gc_disable); +/// \function enable() +/// Enable the garbage collector. STATIC mp_obj_t gc_enable(void) { gc_unlock(); return mp_const_none; } MP_DEFINE_CONST_FUN_OBJ_0(gc_enable_obj, gc_enable); +/// \function mem_free() +/// Return the number of bytes of available heap RAM. STATIC mp_obj_t gc_mem_free(void) { gc_info_t info; gc_info(&info); @@ -68,6 +78,8 @@ STATIC mp_obj_t gc_mem_free(void) { } MP_DEFINE_CONST_FUN_OBJ_0(gc_mem_free_obj, gc_mem_free); +/// \function mem_alloc() +/// Return the number of bytes of heap RAM that are allocated. STATIC mp_obj_t gc_mem_alloc(void) { gc_info_t info; gc_info(&info); diff --git a/py/modmath.c b/py/modmath.c index 4db9b80547..7124820041 100644 --- a/py/modmath.c +++ b/py/modmath.c @@ -34,6 +34,11 @@ #if MICROPY_PY_BUILTINS_FLOAT && MICROPY_PY_MATH +/// \module math - mathematical functions +/// +/// The `math` module provides some basic mathematical funtions for +/// working with floating-point numbers. + //TODO: Change macros to check for overflow and raise OverflowError or RangeError #define MATH_FUN_1(py_name, c_name) \ mp_obj_t mp_math_ ## py_name(mp_obj_t x_obj) { return mp_obj_new_float(MICROPY_FLOAT_C_FUN(c_name)(mp_obj_get_float(x_obj))); } \ @@ -52,46 +57,91 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_math_## py_name ## _obj, mp_math_ ## py_name); // These are also used by cmath.c +/// \constant e - base of the natural logarithm const mp_obj_float_t mp_math_e_obj = {{&mp_type_float}, M_E}; +/// \constant pi - the ratio of a circle's circumference to its diameter const mp_obj_float_t mp_math_pi_obj = {{&mp_type_float}, M_PI}; +/// \function sqrt(x) +/// Returns the square root of `x`. MATH_FUN_1(sqrt, sqrt) +/// \function pow(x, y) +/// Returns `x` to the power of `y`. MATH_FUN_2(pow, pow) +/// \function exp(x) MATH_FUN_1(exp, exp) +/// \function expm1(x) MATH_FUN_1(expm1, expm1) +/// \function log(x) MATH_FUN_1(log, log) +/// \function log2(x) MATH_FUN_1(log2, log2) +/// \function log10(x) MATH_FUN_1(log10, log10) +/// \function cosh(x) MATH_FUN_1(cosh, cosh) +/// \function sinh(x) MATH_FUN_1(sinh, sinh) +/// \function tanh(x) MATH_FUN_1(tanh, tanh) +/// \function acosh(x) MATH_FUN_1(acosh, acosh) +/// \function asinh(x) MATH_FUN_1(asinh, asinh) +/// \function atanh(x) MATH_FUN_1(atanh, atanh) +/// \function cos(x) MATH_FUN_1(cos, cos) +/// \function sin(x) MATH_FUN_1(sin, sin) +/// \function tan(x) MATH_FUN_1(tan, tan) +/// \function acos(x) MATH_FUN_1(acos, acos) +/// \function asin(x) MATH_FUN_1(asin, asin) +/// \function atan(x) MATH_FUN_1(atan, atan) +/// \function atan2(y, x) MATH_FUN_2(atan2, atan2) +/// \function ceil(x) MATH_FUN_1_TO_INT(ceil, ceil) +/// \function copysign(x, y) MATH_FUN_2(copysign, copysign) +/// \function fabs(x) MATH_FUN_1(fabs, fabs) +/// \function floor(x) MATH_FUN_1_TO_INT(floor, floor) //TODO: delegate to x.__floor__() if x is not a float +/// \function fmod(x, y) MATH_FUN_2(fmod, fmod) +/// \function isfinite(x) MATH_FUN_1_TO_BOOL(isfinite, isfinite) +/// \function isinf(x) MATH_FUN_1_TO_BOOL(isinf, isinf) +/// \function isnan(x) MATH_FUN_1_TO_BOOL(isnan, isnan) +/// \function trunc(x) MATH_FUN_1_TO_INT(trunc, trunc) +/// \function ldexp(x, exp) MATH_FUN_2(ldexp, ldexp) +/// \function erf(x) +/// Return the error function of `x`. MATH_FUN_1(erf, erf) +/// \function erfc(x) +/// Return the complementary error function of `x`. MATH_FUN_1(erfc, erfc) +/// \function gamma(x) +/// Return the gamma function of `x`. MATH_FUN_1(gamma, tgamma) +/// \function lgamma(x) +/// return the natural logarithm of the gamma function of `x`. MATH_FUN_1(lgamma, lgamma) //TODO: factorial, fsum // Functions that return a tuple + +/// \function frexp(x) +/// Converts a floating-point number to fractional and integral components. mp_obj_t mp_math_frexp(mp_obj_t x_obj) { int int_exponent = 0; mp_float_t significand = MICROPY_FLOAT_C_FUN(frexp)(mp_obj_get_float(x_obj), &int_exponent); @@ -102,6 +152,7 @@ mp_obj_t mp_math_frexp(mp_obj_t x_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_math_frexp_obj, mp_math_frexp); +/// \function modf(x) mp_obj_t mp_math_modf(mp_obj_t x_obj) { mp_float_t int_part = 0.0; mp_float_t fractional_part = MICROPY_FLOAT_C_FUN(modf)(mp_obj_get_float(x_obj), &int_part); @@ -113,11 +164,14 @@ mp_obj_t mp_math_modf(mp_obj_t x_obj) { STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_math_modf_obj, mp_math_modf); // Angular conversions + +/// \function radians(x) mp_obj_t mp_math_radians(mp_obj_t x_obj) { return mp_obj_new_float(mp_obj_get_float(x_obj) * M_PI / 180.0); } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_math_radians_obj, mp_math_radians); +/// \function degrees(x) mp_obj_t mp_math_degrees(mp_obj_t x_obj) { return mp_obj_new_float(mp_obj_get_float(x_obj) * 180.0 / M_PI); } diff --git a/py/modsys.c b/py/modsys.c index c248e5626f..a1a9265dbd 100644 --- a/py/modsys.c +++ b/py/modsys.c @@ -40,6 +40,8 @@ #if MICROPY_PY_SYS +/// \module sys - system specific functions + // These should be implemented by ports, specific types don't matter, // only addresses. struct _dummy_t; @@ -47,14 +49,21 @@ extern struct _dummy_t mp_sys_exit_obj; extern mp_obj_int_t mp_maxsize_obj; +// TODO document these, they aren't constants or functions... mp_obj_list_t mp_sys_path_obj; mp_obj_list_t mp_sys_argv_obj; + +/// \constant version - Python language version that this implementation conforms to, as a string +STATIC const MP_DEFINE_STR_OBJ(version_obj, "3.4.0"); + +/// \constant version - Python language version that this implementation conforms to, as a tuple of ints #define I(n) MP_OBJ_NEW_SMALL_INT(n) // TODO: CPython is now at 5-element array, but save 2 els so far... STATIC const mp_obj_tuple_t mp_sys_version_info_obj = {{&mp_type_tuple}, 3, {I(3), I(4), I(0)}}; #undef I -STATIC const MP_DEFINE_STR_OBJ(version_obj, "3.4.0"); + #ifdef MICROPY_PY_SYS_PLATFORM +/// \constant platform - the platform that Micro Python is running on STATIC const MP_DEFINE_STR_OBJ(platform_obj, MICROPY_PY_SYS_PLATFORM); #endif @@ -68,6 +77,7 @@ STATIC const mp_map_elem_t mp_module_sys_globals_table[] = { #ifdef MICROPY_PY_SYS_PLATFORM { MP_OBJ_NEW_QSTR(MP_QSTR_platform), (mp_obj_t)&platform_obj }, #endif + /// \constant byteorder - the byte order of the system ("little" or "big") #if MP_ENDIANNESS_LITTLE { MP_OBJ_NEW_QSTR(MP_QSTR_byteorder), MP_OBJ_NEW_QSTR(MP_QSTR_little) }, #else @@ -86,12 +96,13 @@ STATIC const mp_map_elem_t mp_module_sys_globals_table[] = { #endif #endif - #if MICROPY_PY_SYS_EXIT + // documented per-port { MP_OBJ_NEW_QSTR(MP_QSTR_exit), (mp_obj_t)&mp_sys_exit_obj }, #endif #if MICROPY_PY_SYS_STDFILES + // documented per-port { MP_OBJ_NEW_QSTR(MP_QSTR_stdin), (mp_obj_t)&mp_sys_stdin_obj }, { MP_OBJ_NEW_QSTR(MP_QSTR_stdout), (mp_obj_t)&mp_sys_stdout_obj }, { MP_OBJ_NEW_QSTR(MP_QSTR_stderr), (mp_obj_t)&mp_sys_stderr_obj }, diff --git a/stmhal/main.c b/stmhal/main.c index 4f5277975b..2134e94fdf 100644 --- a/stmhal/main.c +++ b/stmhal/main.c @@ -569,6 +569,10 @@ soft_reset: goto soft_reset; } +/// \moduleref sys +/// \function exit([retval]) +/// Raise a `SystemExit` exception. If an argument is given, it is the +/// value given to `SystemExit`. STATIC NORETURN mp_obj_t mp_sys_exit(uint n_args, const mp_obj_t *args) { int rc = 0; if (n_args > 0) { diff --git a/stmhal/pybstdio.c b/stmhal/pybstdio.c index 2121a6cbb7..b7756d63ea 100644 --- a/stmhal/pybstdio.c +++ b/stmhal/pybstdio.c @@ -177,6 +177,10 @@ STATIC const mp_obj_type_t stdio_obj_type = { .locals_dict = (mp_obj_t)&stdio_locals_dict, }; +/// \moduleref sys +/// \constant stdin - standard input (connected to USB VCP, and optional UART object) +/// \constant stdout - standard output (connected to USB VCP, and optional UART object) +/// \constant stderr - standard error (connected to USB VCP, and optional UART object) const pyb_stdio_obj_t mp_sys_stdin_obj = {{&stdio_obj_type}, .fd = STDIO_FD_IN}; const pyb_stdio_obj_t mp_sys_stdout_obj = {{&stdio_obj_type}, .fd = STDIO_FD_OUT}; const pyb_stdio_obj_t mp_sys_stderr_obj = {{&stdio_obj_type}, .fd = STDIO_FD_ERR};