summaryrefslogtreecommitdiffstatshomepage
diff options
context:
space:
mode:
Diffstat
-rw-r--r--py/modcmath.c19
-rw-r--r--py/modgc.c12
-rw-r--r--py/modmath.c54
-rw-r--r--py/modsys.c15
-rw-r--r--stmhal/main.c4
-rw-r--r--stmhal/pybstdio.c4
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};
generated by cgit v1.2.3 (git 2.39.1) at 2025-05-16 14:54:13 +0000