From 0102ee092b590be2736521ebf165c96bcf0bcbe6 Mon Sep 17 00:00:00 2001 From: Damien George Date: Wed, 30 Aug 2017 21:02:00 +1000 Subject: [PATCH] py: Change obsolete "///" comment formatting to normal comments. This comment style is no longer used because the docs are written by hand, not generated. --- py/modcmath.c | 32 ++++++------------- py/modgc.c | 17 +++------- py/modmath.c | 86 ++++++++++++++++++++++----------------------------- py/modsys.c | 15 +++------ 4 files changed, 55 insertions(+), 95 deletions(-) diff --git a/py/modcmath.c b/py/modcmath.c index 627a2cbadb..70fd542af9 100644 --- a/py/modcmath.c +++ b/py/modcmath.c @@ -30,13 +30,7 @@ #include -/// \module cmath - mathematical functions for complex numbers -/// -/// The `cmath` module provides some basic mathematical funtions for -/// working with complex numbers. - -/// \function phase(z) -/// Returns the phase of the number `z`, in the range (-pi, +pi]. +// phase(z): returns the phase of the number z in the range (-pi, +pi] STATIC mp_obj_t mp_cmath_phase(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); @@ -44,8 +38,7 @@ STATIC 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`. +// polar(z): returns the polar form of z as a tuple STATIC mp_obj_t mp_cmath_polar(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); @@ -57,8 +50,7 @@ STATIC 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 modulus `r` and phase `phi`. +// rect(r, phi): returns the complex number with modulus r and phase phi STATIC 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); @@ -66,8 +58,7 @@ STATIC 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) -/// Return the exponential of `z`. +// exp(z): return the exponential of z STATIC mp_obj_t mp_cmath_exp(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); @@ -76,8 +67,7 @@ STATIC 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) -/// Return the natural logarithm of `z`. The branch cut is along the negative real axis. +// log(z): return the natural logarithm of z, with branch cut along the negative real axis // TODO can take second argument, being the base STATIC mp_obj_t mp_cmath_log(mp_obj_t z_obj) { mp_float_t real, imag; @@ -87,8 +77,7 @@ STATIC 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); #if MICROPY_PY_MATH_SPECIAL_FUNCTIONS -/// \function log10(z) -/// Return the base-10 logarithm of `z`. The branch cut is along the negative real axis. +// log10(z): return the base-10 logarithm of z, with branch cut along the negative real axis STATIC mp_obj_t mp_cmath_log10(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); @@ -97,8 +86,7 @@ STATIC 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); #endif -/// \function sqrt(z) -/// Return the square-root of `z`. +// sqrt(z): return the square-root of z STATIC mp_obj_t mp_cmath_sqrt(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); @@ -108,8 +96,7 @@ STATIC 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) -/// Return the cosine of `z`. +// cos(z): return the cosine of z STATIC mp_obj_t mp_cmath_cos(mp_obj_t z_obj) { mp_float_t real, imag; mp_obj_get_complex(z_obj, &real, &imag); @@ -117,8 +104,7 @@ STATIC 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) -/// Return the sine of `z`. +// sin(z): return the sine of z STATIC 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 d45e007ebe..55e73defce 100644 --- a/py/modgc.c +++ b/py/modgc.c @@ -30,10 +30,7 @@ #if MICROPY_PY_GC && MICROPY_ENABLE_GC -/// \module gc - control the garbage collector - -/// \function collect() -/// Run a garbage collection. +// collect(): run a garbage collection STATIC mp_obj_t py_gc_collect(void) { gc_collect(); #if MICROPY_PY_GC_COLLECT_RETVAL @@ -44,16 +41,14 @@ 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. +// disable(): disable the garbage collector STATIC mp_obj_t gc_disable(void) { MP_STATE_MEM(gc_auto_collect_enabled) = 0; return mp_const_none; } MP_DEFINE_CONST_FUN_OBJ_0(gc_disable_obj, gc_disable); -/// \function enable() -/// Enable the garbage collector. +// enable(): enable the garbage collector STATIC mp_obj_t gc_enable(void) { MP_STATE_MEM(gc_auto_collect_enabled) = 1; return mp_const_none; @@ -65,8 +60,7 @@ STATIC mp_obj_t gc_isenabled(void) { } MP_DEFINE_CONST_FUN_OBJ_0(gc_isenabled_obj, gc_isenabled); -/// \function mem_free() -/// Return the number of bytes of available heap RAM. +// 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); @@ -74,8 +68,7 @@ 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. +// 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 c56056a5dd..4d627c67f4 100644 --- a/py/modmath.c +++ b/py/modmath.c @@ -35,11 +35,6 @@ // And by defining our own we can ensure it uses the correct const format. #define MP_PI MICROPY_FLOAT_CONST(3.14159265358979323846) -/// \module math - mathematical functions -/// -/// The `math` module provides some basic mathematical funtions for -/// working with floating-point numbers. - STATIC NORETURN void math_error(void) { mp_raise_ValueError("math domain error"); } @@ -75,80 +70,74 @@ STATIC NORETURN void math_error(void) { #define log2(x) (log(x) * 1.442695040888963407354163704) #endif -/// \function sqrt(x) -/// Returns the square root of `x`. +// sqrt(x): returns the square root of x MATH_FUN_1_ERRCOND(sqrt, sqrt, (x < (mp_float_t)0.0)) -/// \function pow(x, y) -/// Returns `x` to the power of `y`. +// pow(x, y): returns x to the power of y MATH_FUN_2(pow, pow) -/// \function exp(x) +// exp(x) MATH_FUN_1(exp, exp) #if MICROPY_PY_MATH_SPECIAL_FUNCTIONS -/// \function expm1(x) +// expm1(x) MATH_FUN_1(expm1, expm1) -/// \function log2(x) +// log2(x) MATH_FUN_1_ERRCOND(log2, log2, (x <= (mp_float_t)0.0)) -/// \function log10(x) +// log10(x) MATH_FUN_1_ERRCOND(log10, log10, (x <= (mp_float_t)0.0)) -/// \function cosh(x) +// cosh(x) MATH_FUN_1(cosh, cosh) -/// \function sinh(x) +// sinh(x) MATH_FUN_1(sinh, sinh) -/// \function tanh(x) +// tanh(x) MATH_FUN_1(tanh, tanh) -/// \function acosh(x) +// acosh(x) MATH_FUN_1(acosh, acosh) -/// \function asinh(x) +// asinh(x) MATH_FUN_1(asinh, asinh) -/// \function atanh(x) +// atanh(x) MATH_FUN_1(atanh, atanh) #endif -/// \function cos(x) +// cos(x) MATH_FUN_1(cos, cos) -/// \function sin(x) +// sin(x) MATH_FUN_1(sin, sin) -/// \function tan(x) +// tan(x) MATH_FUN_1(tan, tan) -/// \function acos(x) +// acos(x) MATH_FUN_1(acos, acos) -/// \function asin(x) +// asin(x) MATH_FUN_1(asin, asin) -/// \function atan(x) +// atan(x) MATH_FUN_1(atan, atan) -/// \function atan2(y, x) +// atan2(y, x) MATH_FUN_2(atan2, atan2) -/// \function ceil(x) +// ceil(x) MATH_FUN_1_TO_INT(ceil, ceil) -/// \function copysign(x, y) +// copysign(x, y) MATH_FUN_2(copysign, copysign) -/// \function fabs(x) +// fabs(x) MATH_FUN_1(fabs, fabs) -/// \function floor(x) +// floor(x) MATH_FUN_1_TO_INT(floor, floor) //TODO: delegate to x.__floor__() if x is not a float -/// \function fmod(x, y) +// fmod(x, y) MATH_FUN_2(fmod, fmod) -/// \function isfinite(x) +// isfinite(x) MATH_FUN_1_TO_BOOL(isfinite, isfinite) -/// \function isinf(x) +// isinf(x) MATH_FUN_1_TO_BOOL(isinf, isinf) -/// \function isnan(x) +// isnan(x) MATH_FUN_1_TO_BOOL(isnan, isnan) -/// \function trunc(x) +// trunc(x) MATH_FUN_1_TO_INT(trunc, trunc) -/// \function ldexp(x, exp) +// ldexp(x, exp) MATH_FUN_2(ldexp, ldexp) #if MICROPY_PY_MATH_SPECIAL_FUNCTIONS -/// \function erf(x) -/// Return the error function of `x`. +// erf(x): return the error function of x MATH_FUN_1(erf, erf) -/// \function erfc(x) -/// Return the complementary error function of `x`. +// erfc(x): return the complementary error function of x MATH_FUN_1(erfc, erfc) -/// \function gamma(x) -/// Return the gamma function of `x`. +// 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`. +// lgamma(x): return the natural logarithm of the gamma function of x MATH_FUN_1(lgamma, lgamma) #endif //TODO: factorial, fsum @@ -178,8 +167,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mp_math_log_obj, 1, 2, mp_math_log); // Functions that return a tuple -/// \function frexp(x) -/// Converts a floating-point number to fractional and integral components. +// frexp(x): converts a floating-point number to fractional and integral components STATIC 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); @@ -190,7 +178,7 @@ STATIC 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) +// modf(x) STATIC 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); @@ -203,13 +191,13 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_math_modf_obj, mp_math_modf); // Angular conversions -/// \function radians(x) +// radians(x) STATIC mp_obj_t mp_math_radians(mp_obj_t x_obj) { return mp_obj_new_float(mp_obj_get_float(x_obj) * (MP_PI / MICROPY_FLOAT_CONST(180.0))); } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_math_radians_obj, mp_math_radians); -/// \function degrees(x) +// degrees(x) STATIC mp_obj_t mp_math_degrees(mp_obj_t x_obj) { return mp_obj_new_float(mp_obj_get_float(x_obj) * (MICROPY_FLOAT_CONST(180.0) / MP_PI)); } diff --git a/py/modsys.c b/py/modsys.c index b7d55fdcc6..ecc0b6065f 100644 --- a/py/modsys.c +++ b/py/modsys.c @@ -42,8 +42,6 @@ #include "genhdr/mpversion.h" -/// \module sys - system specific functions - // defined per port; type of these is irrelevant, just need pointer extern struct _mp_dummy_t mp_sys_stdin_obj; extern struct _mp_dummy_t mp_sys_stdout_obj; @@ -53,10 +51,10 @@ extern struct _mp_dummy_t mp_sys_stderr_obj; const mp_print_t mp_sys_stdout_print = {&mp_sys_stdout_obj, mp_stream_write_adaptor}; #endif -/// \constant version - Python language version that this implementation conforms to, as a string +// 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_info - Python language version that this implementation conforms to, as a tuple of ints +// version_info - 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)}}; @@ -91,13 +89,11 @@ STATIC const mp_rom_obj_tuple_t mp_sys_implementation_obj = { #undef I #ifdef MICROPY_PY_SYS_PLATFORM -/// \constant platform - the platform that MicroPython is running on +// platform - the platform that MicroPython is running on STATIC const MP_DEFINE_STR_OBJ(platform_obj, MICROPY_PY_SYS_PLATFORM); #endif -/// \function exit([retval]) -/// Raise a `SystemExit` exception. If an argument is given, it is the -/// value given to `SystemExit`. +// exit([retval]): raise SystemExit, with optional argument given to the exception STATIC mp_obj_t mp_sys_exit(size_t n_args, const mp_obj_t *args) { mp_obj_t exc; if (n_args == 0) { @@ -163,7 +159,6 @@ STATIC const mp_rom_map_elem_t mp_module_sys_globals_table[] = { #ifdef MICROPY_PY_SYS_PLATFORM { MP_ROM_QSTR(MP_QSTR_platform), MP_ROM_PTR(&platform_obj) }, #endif - /// \constant byteorder - the byte order of the system ("little" or "big") #if MP_ENDIANNESS_LITTLE { MP_ROM_QSTR(MP_QSTR_byteorder), MP_ROM_QSTR(MP_QSTR_little) }, #else @@ -184,12 +179,10 @@ STATIC const mp_rom_map_elem_t mp_module_sys_globals_table[] = { #endif #if MICROPY_PY_SYS_EXIT - // documented per-port { MP_ROM_QSTR(MP_QSTR_exit), MP_ROM_PTR(&mp_sys_exit_obj) }, #endif #if MICROPY_PY_SYS_STDFILES - // documented per-port { MP_ROM_QSTR(MP_QSTR_stdin), MP_ROM_PTR(&mp_sys_stdin_obj) }, { MP_ROM_QSTR(MP_QSTR_stdout), MP_ROM_PTR(&mp_sys_stdout_obj) }, { MP_ROM_QSTR(MP_QSTR_stderr), MP_ROM_PTR(&mp_sys_stderr_obj) },