Skip to content

Commit 30dd23a

Browse files
dpgeorgedpgeorge
committed
doc: Document gc, sys, math, cmath.
1 parent 0c64c63 commit 30dd23a

6 files changed

Lines changed: 106 additions & 2 deletions

File tree

‎py/modcmath.c‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,17 +34,28 @@
3434

3535
#if MICROPY_PY_BUILTINS_FLOAT && MICROPY_PY_CMATH
3636

37+
/// \module cmath - mathematical functions for complex numbers
38+
///
39+
/// The `cmath` module provides some basic mathematical funtions for
40+
/// working with complex numbers.
41+
3742
// These are defined in modmath.c
43+
/// \constant e - base of the natural logarithm
3844
extern const mp_obj_float_t mp_math_e_obj;
45+
/// \constant pi - the ratio of a circle's circumference to its diameter
3946
extern const mp_obj_float_t mp_math_pi_obj;
4047

48+
/// \function phase(z)
49+
/// Returns the phase of the number `z`, in the range (-pi, +pi].
4150
mp_obj_t mp_cmath_phase(mp_obj_t z_obj) {
4251
mp_float_t real, imag;
4352
mp_obj_get_complex(z_obj, &real, &imag);
4453
return mp_obj_new_float(MICROPY_FLOAT_C_FUN(atan2)(imag, real));
4554
}
4655
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_phase_obj, mp_cmath_phase);
4756

57+
/// \function polar(z)
58+
/// Returns, as a tuple, the polar form of `z`.
4859
mp_obj_t mp_cmath_polar(mp_obj_t z_obj) {
4960
mp_float_t real, imag;
5061
mp_obj_get_complex(z_obj, &real, &imag);
@@ -56,13 +67,16 @@ mp_obj_t mp_cmath_polar(mp_obj_t z_obj) {
5667
}
5768
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_polar_obj, mp_cmath_polar);
5869

70+
/// \function rect(r, phi)
71+
/// Returns the complex number with modules `r` and phase `phi`.
5972
mp_obj_t mp_cmath_rect(mp_obj_t r_obj, mp_obj_t phi_obj) {
6073
mp_float_t r = mp_obj_get_float(r_obj);
6174
mp_float_t phi = mp_obj_get_float(phi_obj);
6275
return mp_obj_new_complex(r * MICROPY_FLOAT_C_FUN(cos)(phi), r * MICROPY_FLOAT_C_FUN(sin)(phi));
6376
}
6477
STATIC MP_DEFINE_CONST_FUN_OBJ_2(mp_cmath_rect_obj, mp_cmath_rect);
6578

79+
/// \function exp(z)
6680
mp_obj_t mp_cmath_exp(mp_obj_t z_obj) {
6781
mp_float_t real, imag;
6882
mp_obj_get_complex(z_obj, &real, &imag);
@@ -71,6 +85,7 @@ mp_obj_t mp_cmath_exp(mp_obj_t z_obj) {
7185
}
7286
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_exp_obj, mp_cmath_exp);
7387

88+
/// \function log(z)
7489
// TODO can take second argument, being the base
7590
mp_obj_t mp_cmath_log(mp_obj_t z_obj) {
7691
mp_float_t real, imag;
@@ -79,13 +94,15 @@ mp_obj_t mp_cmath_log(mp_obj_t z_obj) {
7994
}
8095
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_log_obj, mp_cmath_log);
8196

97+
/// \function log10(z)
8298
mp_obj_t mp_cmath_log10(mp_obj_t z_obj) {
8399
mp_float_t real, imag;
84100
mp_obj_get_complex(z_obj, &real, &imag);
85101
return mp_obj_new_complex(0.5 * MICROPY_FLOAT_C_FUN(log10)(real*real + imag*imag), MICROPY_FLOAT_C_FUN(atan2)(imag, real));
86102
}
87103
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_log10_obj, mp_cmath_log10);
88104

105+
/// \function sqrt(z)
89106
mp_obj_t mp_cmath_sqrt(mp_obj_t z_obj) {
90107
mp_float_t real, imag;
91108
mp_obj_get_complex(z_obj, &real, &imag);
@@ -95,13 +112,15 @@ mp_obj_t mp_cmath_sqrt(mp_obj_t z_obj) {
95112
}
96113
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_sqrt_obj, mp_cmath_sqrt);
97114

115+
/// \function cos(z)
98116
mp_obj_t mp_cmath_cos(mp_obj_t z_obj) {
99117
mp_float_t real, imag;
100118
mp_obj_get_complex(z_obj, &real, &imag);
101119
return mp_obj_new_complex(MICROPY_FLOAT_C_FUN(cos)(real) * MICROPY_FLOAT_C_FUN(cosh)(imag), -MICROPY_FLOAT_C_FUN(sin)(real) * MICROPY_FLOAT_C_FUN(sinh)(imag));
102120
}
103121
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_cos_obj, mp_cmath_cos);
104122

123+
/// \function sin(z)
105124
mp_obj_t mp_cmath_sin(mp_obj_t z_obj) {
106125
mp_float_t real, imag;
107126
mp_obj_get_complex(z_obj, &real, &imag);

‎py/modgc.c‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,12 @@
3737

3838
#if MICROPY_PY_GC && MICROPY_ENABLE_GC
3939

40+
/// \module gc - control the garbage collector
41+
4042
extern uint gc_collected;
4143

44+
/// \function collect()
45+
/// Run a garbage collection.
4246
STATIC mp_obj_t py_gc_collect(void) {
4347
gc_collect();
4448
#if MICROPY_PY_GC_COLLECT_RETVAL
@@ -49,25 +53,33 @@ STATIC mp_obj_t py_gc_collect(void) {
4953
}
5054
MP_DEFINE_CONST_FUN_OBJ_0(gc_collect_obj, py_gc_collect);
5155

56+
/// \function disable()
57+
/// Disable the garbage collector.
5258
STATIC mp_obj_t gc_disable(void) {
5359
gc_lock();
5460
return mp_const_none;
5561
}
5662
MP_DEFINE_CONST_FUN_OBJ_0(gc_disable_obj, gc_disable);
5763

64+
/// \function enable()
65+
/// Enable the garbage collector.
5866
STATIC mp_obj_t gc_enable(void) {
5967
gc_unlock();
6068
return mp_const_none;
6169
}
6270
MP_DEFINE_CONST_FUN_OBJ_0(gc_enable_obj, gc_enable);
6371

72+
/// \function mem_free()
73+
/// Return the number of bytes of available heap RAM.
6474
STATIC mp_obj_t gc_mem_free(void) {
6575
gc_info_t info;
6676
gc_info(&info);
6777
return MP_OBJ_NEW_SMALL_INT(info.free);
6878
}
6979
MP_DEFINE_CONST_FUN_OBJ_0(gc_mem_free_obj, gc_mem_free);
7080

81+
/// \function mem_alloc()
82+
/// Return the number of bytes of heap RAM that are allocated.
7183
STATIC mp_obj_t gc_mem_alloc(void) {
7284
gc_info_t info;
7385
gc_info(&info);

‎py/modmath.c‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,11 @@
3434

3535
#if MICROPY_PY_BUILTINS_FLOAT && MICROPY_PY_MATH
3636

37+
/// \module math - mathematical functions
38+
///
39+
/// The `math` module provides some basic mathematical funtions for
40+
/// working with floating-point numbers.
41+
3742
//TODO: Change macros to check for overflow and raise OverflowError or RangeError
3843
#define MATH_FUN_1(py_name, c_name) \
3944
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 @@
5257
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_math_## py_name ## _obj, mp_math_ ## py_name);
5358

5459
// These are also used by cmath.c
60+
/// \constant e - base of the natural logarithm
5561
const mp_obj_float_t mp_math_e_obj = {{&mp_type_float}, M_E};
62+
/// \constant pi - the ratio of a circle's circumference to its diameter
5663
const mp_obj_float_t mp_math_pi_obj = {{&mp_type_float}, M_PI};
5764

65+
/// \function sqrt(x)
66+
/// Returns the square root of `x`.
5867
MATH_FUN_1(sqrt, sqrt)
68+
/// \function pow(x, y)
69+
/// Returns `x` to the power of `y`.
5970
MATH_FUN_2(pow, pow)
71+
/// \function exp(x)
6072
MATH_FUN_1(exp, exp)
73+
/// \function expm1(x)
6174
MATH_FUN_1(expm1, expm1)
75+
/// \function log(x)
6276
MATH_FUN_1(log, log)
77+
/// \function log2(x)
6378
MATH_FUN_1(log2, log2)
79+
/// \function log10(x)
6480
MATH_FUN_1(log10, log10)
81+
/// \function cosh(x)
6582
MATH_FUN_1(cosh, cosh)
83+
/// \function sinh(x)
6684
MATH_FUN_1(sinh, sinh)
85+
/// \function tanh(x)
6786
MATH_FUN_1(tanh, tanh)
87+
/// \function acosh(x)
6888
MATH_FUN_1(acosh, acosh)
89+
/// \function asinh(x)
6990
MATH_FUN_1(asinh, asinh)
91+
/// \function atanh(x)
7092
MATH_FUN_1(atanh, atanh)
93+
/// \function cos(x)
7194
MATH_FUN_1(cos, cos)
95+
/// \function sin(x)
7296
MATH_FUN_1(sin, sin)
97+
/// \function tan(x)
7398
MATH_FUN_1(tan, tan)
99+
/// \function acos(x)
74100
MATH_FUN_1(acos, acos)
101+
/// \function asin(x)
75102
MATH_FUN_1(asin, asin)
103+
/// \function atan(x)
76104
MATH_FUN_1(atan, atan)
105+
/// \function atan2(y, x)
77106
MATH_FUN_2(atan2, atan2)
107+
/// \function ceil(x)
78108
MATH_FUN_1_TO_INT(ceil, ceil)
109+
/// \function copysign(x, y)
79110
MATH_FUN_2(copysign, copysign)
111+
/// \function fabs(x)
80112
MATH_FUN_1(fabs, fabs)
113+
/// \function floor(x)
81114
MATH_FUN_1_TO_INT(floor, floor) //TODO: delegate to x.__floor__() if x is not a float
115+
/// \function fmod(x, y)
82116
MATH_FUN_2(fmod, fmod)
117+
/// \function isfinite(x)
83118
MATH_FUN_1_TO_BOOL(isfinite, isfinite)
119+
/// \function isinf(x)
84120
MATH_FUN_1_TO_BOOL(isinf, isinf)
121+
/// \function isnan(x)
85122
MATH_FUN_1_TO_BOOL(isnan, isnan)
123+
/// \function trunc(x)
86124
MATH_FUN_1_TO_INT(trunc, trunc)
125+
/// \function ldexp(x, exp)
87126
MATH_FUN_2(ldexp, ldexp)
127+
/// \function erf(x)
128+
/// Return the error function of `x`.
88129
MATH_FUN_1(erf, erf)
130+
/// \function erfc(x)
131+
/// Return the complementary error function of `x`.
89132
MATH_FUN_1(erfc, erfc)
133+
/// \function gamma(x)
134+
/// Return the gamma function of `x`.
90135
MATH_FUN_1(gamma, tgamma)
136+
/// \function lgamma(x)
137+
/// return the natural logarithm of the gamma function of `x`.
91138
MATH_FUN_1(lgamma, lgamma)
92139
//TODO: factorial, fsum
93140

94141
// Functions that return a tuple
142+
143+
/// \function frexp(x)
144+
/// Converts a floating-point number to fractional and integral components.
95145
mp_obj_t mp_math_frexp(mp_obj_t x_obj) {
96146
int int_exponent = 0;
97147
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) {
102152
}
103153
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_math_frexp_obj, mp_math_frexp);
104154

155+
/// \function modf(x)
105156
mp_obj_t mp_math_modf(mp_obj_t x_obj) {
106157
mp_float_t int_part = 0.0;
107158
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) {
113164
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_math_modf_obj, mp_math_modf);
114165

115166
// Angular conversions
167+
168+
/// \function radians(x)
116169
mp_obj_t mp_math_radians(mp_obj_t x_obj) {
117170
return mp_obj_new_float(mp_obj_get_float(x_obj) * M_PI / 180.0);
118171
}
119172
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_math_radians_obj, mp_math_radians);
120173

174+
/// \function degrees(x)
121175
mp_obj_t mp_math_degrees(mp_obj_t x_obj) {
122176
return mp_obj_new_float(mp_obj_get_float(x_obj) * 180.0 / M_PI);
123177
}

‎py/modsys.c‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,21 +40,30 @@
4040

4141
#if MICROPY_PY_SYS
4242

43+
/// \module sys - system specific functions
44+
4345
// These should be implemented by ports, specific types don't matter,
4446
// only addresses.
4547
struct _dummy_t;
4648
extern struct _dummy_t mp_sys_exit_obj;
4749

4850
extern mp_obj_int_t mp_maxsize_obj;
4951

52+
// TODO document these, they aren't constants or functions...
5053
mp_obj_list_t mp_sys_path_obj;
5154
mp_obj_list_t mp_sys_argv_obj;
55+
56+
/// \constant version - Python language version that this implementation conforms to, as a string
57+
STATIC const MP_DEFINE_STR_OBJ(version_obj, "3.4.0");
58+
59+
/// \constant version - Python language version that this implementation conforms to, as a tuple of ints
5260
#define I(n) MP_OBJ_NEW_SMALL_INT(n)
5361
// TODO: CPython is now at 5-element array, but save 2 els so far...
5462
STATIC const mp_obj_tuple_t mp_sys_version_info_obj = {{&mp_type_tuple}, 3, {I(3), I(4), I(0)}};
5563
#undef I
56-
STATIC const MP_DEFINE_STR_OBJ(version_obj, "3.4.0");
64+
5765
#ifdef MICROPY_PY_SYS_PLATFORM
66+
/// \constant platform - the platform that Micro Python is running on
5867
STATIC const MP_DEFINE_STR_OBJ(platform_obj, MICROPY_PY_SYS_PLATFORM);
5968
#endif
6069

@@ -68,6 +77,7 @@ STATIC const mp_map_elem_t mp_module_sys_globals_table[] = {
6877
#ifdef MICROPY_PY_SYS_PLATFORM
6978
{ MP_OBJ_NEW_QSTR(MP_QSTR_platform), (mp_obj_t)&platform_obj },
7079
#endif
80+
/// \constant byteorder - the byte order of the system ("little" or "big")
7181
#if MP_ENDIANNESS_LITTLE
7282
{ MP_OBJ_NEW_QSTR(MP_QSTR_byteorder), MP_OBJ_NEW_QSTR(MP_QSTR_little) },
7383
#else
@@ -86,12 +96,13 @@ STATIC const mp_map_elem_t mp_module_sys_globals_table[] = {
8696
#endif
8797
#endif
8898

89-
9099
#if MICROPY_PY_SYS_EXIT
100+
// documented per-port
91101
{ MP_OBJ_NEW_QSTR(MP_QSTR_exit), (mp_obj_t)&mp_sys_exit_obj },
92102
#endif
93103

94104
#if MICROPY_PY_SYS_STDFILES
105+
// documented per-port
95106
{ MP_OBJ_NEW_QSTR(MP_QSTR_stdin), (mp_obj_t)&mp_sys_stdin_obj },
96107
{ MP_OBJ_NEW_QSTR(MP_QSTR_stdout), (mp_obj_t)&mp_sys_stdout_obj },
97108
{ MP_OBJ_NEW_QSTR(MP_QSTR_stderr), (mp_obj_t)&mp_sys_stderr_obj },

‎stmhal/main.c‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -569,6 +569,10 @@ int main(void) {
569569
goto soft_reset;
570570
}
571571

572+
/// \moduleref sys
573+
/// \function exit([retval])
574+
/// Raise a `SystemExit` exception. If an argument is given, it is the
575+
/// value given to `SystemExit`.
572576
STATIC NORETURN mp_obj_t mp_sys_exit(uint n_args, const mp_obj_t *args) {
573577
int rc = 0;
574578
if (n_args > 0) {

‎stmhal/pybstdio.c‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,10 @@ STATIC const mp_obj_type_t stdio_obj_type = {
177177
.locals_dict = (mp_obj_t)&stdio_locals_dict,
178178
};
179179

180+
/// \moduleref sys
181+
/// \constant stdin - standard input (connected to USB VCP, and optional UART object)
182+
/// \constant stdout - standard output (connected to USB VCP, and optional UART object)
183+
/// \constant stderr - standard error (connected to USB VCP, and optional UART object)
180184
const pyb_stdio_obj_t mp_sys_stdin_obj = {{&stdio_obj_type}, .fd = STDIO_FD_IN};
181185
const pyb_stdio_obj_t mp_sys_stdout_obj = {{&stdio_obj_type}, .fd = STDIO_FD_OUT};
182186
const pyb_stdio_obj_t mp_sys_stderr_obj = {{&stdio_obj_type}, .fd = STDIO_FD_ERR};

0 commit comments

Comments
 (0)