Skip to content

Commit

Permalink
py: Change obsolete "///" comment formatting to normal comments.
Browse files Browse the repository at this point in the history 
This comment style is no longer used because the docs are written by hand,
not generated.
  • Loading branch information
@dpgeorge
dpgeorge committed Aug 30, 2017
1 parent 71c9cfb commit 0102ee0
Show file tree
Hide file tree
Showing 4 changed files with 55 additions and 95 deletions.
32 changes: 9 additions & 23 deletions py/modcmath.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,22 +30,15 @@

#include <math.h>

/// \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);
return mp_obj_new_float(MICROPY_FLOAT_C_FUN(atan2)(imag, real));
}
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);
Expand All @@ -57,17 +50,15 @@ 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);
return mp_obj_new_complex(r * MICROPY_FLOAT_C_FUN(cos)(phi), r * MICROPY_FLOAT_C_FUN(sin)(phi));
}
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);
Expand All @@ -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;
Expand All @@ -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);
Expand All @@ -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);
Expand All @@ -108,17 +96,15 @@ 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);
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));
}
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);
Expand Down
17 changes: 5 additions & 12 deletions py/modgc.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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;
Expand All @@ -65,17 +60,15 @@ 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);
return MP_OBJ_NEW_SMALL_INT(info.free);
}
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);
Expand Down
86 changes: 37 additions & 49 deletions py/modmath.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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");
}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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);
Expand All @@ -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);
Expand All @@ -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));
}
Expand Down
15 changes: 4 additions & 11 deletions py/modsys.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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)}};
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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
Expand All @@ -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) },
Expand Down

0 comments on commit 0102ee0

Please sign in to comment.