Skip to content

Commit 0102ee0

Browse files
dpgeorgedpgeorge
committed
py: Change obsolete "///" comment formatting to normal comments.
This comment style is no longer used because the docs are written by hand, not generated.
1 parent 71c9cfb commit 0102ee0

4 files changed

Lines changed: 55 additions & 95 deletions

File tree

‎py/modcmath.c‎

Lines changed: 9 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -30,22 +30,15 @@
3030

3131
#include <math.h>
3232

33-
/// \module cmath - mathematical functions for complex numbers
34-
///
35-
/// The `cmath` module provides some basic mathematical funtions for
36-
/// working with complex numbers.
37-
38-
/// \function phase(z)
39-
/// Returns the phase of the number `z`, in the range (-pi, +pi].
33+
// phase(z): returns the phase of the number z in the range (-pi, +pi]
4034
STATIC mp_obj_t mp_cmath_phase(mp_obj_t z_obj) {
4135
mp_float_t real, imag;
4236
mp_obj_get_complex(z_obj, &real, &imag);
4337
return mp_obj_new_float(MICROPY_FLOAT_C_FUN(atan2)(imag, real));
4438
}
4539
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_phase_obj, mp_cmath_phase);
4640

47-
/// \function polar(z)
48-
/// Returns, as a tuple, the polar form of `z`.
41+
// polar(z): returns the polar form of z as a tuple
4942
STATIC mp_obj_t mp_cmath_polar(mp_obj_t z_obj) {
5043
mp_float_t real, imag;
5144
mp_obj_get_complex(z_obj, &real, &imag);
@@ -57,17 +50,15 @@ STATIC mp_obj_t mp_cmath_polar(mp_obj_t z_obj) {
5750
}
5851
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_polar_obj, mp_cmath_polar);
5952

60-
/// \function rect(r, phi)
61-
/// Returns the complex number with modulus `r` and phase `phi`.
53+
// rect(r, phi): returns the complex number with modulus r and phase phi
6254
STATIC mp_obj_t mp_cmath_rect(mp_obj_t r_obj, mp_obj_t phi_obj) {
6355
mp_float_t r = mp_obj_get_float(r_obj);
6456
mp_float_t phi = mp_obj_get_float(phi_obj);
6557
return mp_obj_new_complex(r * MICROPY_FLOAT_C_FUN(cos)(phi), r * MICROPY_FLOAT_C_FUN(sin)(phi));
6658
}
6759
STATIC MP_DEFINE_CONST_FUN_OBJ_2(mp_cmath_rect_obj, mp_cmath_rect);
6860

69-
/// \function exp(z)
70-
/// Return the exponential of `z`.
61+
// exp(z): return the exponential of z
7162
STATIC mp_obj_t mp_cmath_exp(mp_obj_t z_obj) {
7263
mp_float_t real, imag;
7364
mp_obj_get_complex(z_obj, &real, &imag);
@@ -76,8 +67,7 @@ STATIC mp_obj_t mp_cmath_exp(mp_obj_t z_obj) {
7667
}
7768
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_exp_obj, mp_cmath_exp);
7869

79-
/// \function log(z)
80-
/// Return the natural logarithm of `z`. The branch cut is along the negative real axis.
70+
// log(z): return the natural logarithm of z, with branch cut along the negative real axis
8171
// TODO can take second argument, being the base
8272
STATIC mp_obj_t mp_cmath_log(mp_obj_t z_obj) {
8373
mp_float_t real, imag;
@@ -87,8 +77,7 @@ STATIC mp_obj_t mp_cmath_log(mp_obj_t z_obj) {
8777
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_log_obj, mp_cmath_log);
8878

8979
#if MICROPY_PY_MATH_SPECIAL_FUNCTIONS
90-
/// \function log10(z)
91-
/// Return the base-10 logarithm of `z`. The branch cut is along the negative real axis.
80+
// log10(z): return the base-10 logarithm of z, with branch cut along the negative real axis
9281
STATIC mp_obj_t mp_cmath_log10(mp_obj_t z_obj) {
9382
mp_float_t real, imag;
9483
mp_obj_get_complex(z_obj, &real, &imag);
@@ -97,8 +86,7 @@ STATIC mp_obj_t mp_cmath_log10(mp_obj_t z_obj) {
9786
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_log10_obj, mp_cmath_log10);
9887
#endif
9988

100-
/// \function sqrt(z)
101-
/// Return the square-root of `z`.
89+
// sqrt(z): return the square-root of z
10290
STATIC mp_obj_t mp_cmath_sqrt(mp_obj_t z_obj) {
10391
mp_float_t real, imag;
10492
mp_obj_get_complex(z_obj, &real, &imag);
@@ -108,17 +96,15 @@ STATIC mp_obj_t mp_cmath_sqrt(mp_obj_t z_obj) {
10896
}
10997
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_sqrt_obj, mp_cmath_sqrt);
11098

111-
/// \function cos(z)
112-
/// Return the cosine of `z`.
99+
// cos(z): return the cosine of z
113100
STATIC mp_obj_t mp_cmath_cos(mp_obj_t z_obj) {
114101
mp_float_t real, imag;
115102
mp_obj_get_complex(z_obj, &real, &imag);
116103
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));
117104
}
118105
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_cmath_cos_obj, mp_cmath_cos);
119106

120-
/// \function sin(z)
121-
/// Return the sine of `z`.
107+
// sin(z): return the sine of z
122108
STATIC mp_obj_t mp_cmath_sin(mp_obj_t z_obj) {
123109
mp_float_t real, imag;
124110
mp_obj_get_complex(z_obj, &real, &imag);

‎py/modgc.c‎

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,7 @@
3030

3131
#if MICROPY_PY_GC && MICROPY_ENABLE_GC
3232

33-
/// \module gc - control the garbage collector
34-
35-
/// \function collect()
36-
/// Run a garbage collection.
33+
// collect(): run a garbage collection
3734
STATIC mp_obj_t py_gc_collect(void) {
3835
gc_collect();
3936
#if MICROPY_PY_GC_COLLECT_RETVAL
@@ -44,16 +41,14 @@ STATIC mp_obj_t py_gc_collect(void) {
4441
}
4542
MP_DEFINE_CONST_FUN_OBJ_0(gc_collect_obj, py_gc_collect);
4643

47-
/// \function disable()
48-
/// Disable the garbage collector.
44+
// disable(): disable the garbage collector
4945
STATIC mp_obj_t gc_disable(void) {
5046
MP_STATE_MEM(gc_auto_collect_enabled) = 0;
5147
return mp_const_none;
5248
}
5349
MP_DEFINE_CONST_FUN_OBJ_0(gc_disable_obj, gc_disable);
5450

55-
/// \function enable()
56-
/// Enable the garbage collector.
51+
// enable(): enable the garbage collector
5752
STATIC mp_obj_t gc_enable(void) {
5853
MP_STATE_MEM(gc_auto_collect_enabled) = 1;
5954
return mp_const_none;
@@ -65,17 +60,15 @@ STATIC mp_obj_t gc_isenabled(void) {
6560
}
6661
MP_DEFINE_CONST_FUN_OBJ_0(gc_isenabled_obj, gc_isenabled);
6762

68-
/// \function mem_free()
69-
/// Return the number of bytes of available heap RAM.
63+
// mem_free(): return the number of bytes of available heap RAM
7064
STATIC mp_obj_t gc_mem_free(void) {
7165
gc_info_t info;
7266
gc_info(&info);
7367
return MP_OBJ_NEW_SMALL_INT(info.free);
7468
}
7569
MP_DEFINE_CONST_FUN_OBJ_0(gc_mem_free_obj, gc_mem_free);
7670

77-
/// \function mem_alloc()
78-
/// Return the number of bytes of heap RAM that are allocated.
71+
// mem_alloc(): return the number of bytes of heap RAM that are allocated
7972
STATIC mp_obj_t gc_mem_alloc(void) {
8073
gc_info_t info;
8174
gc_info(&info);

‎py/modmath.c‎

Lines changed: 37 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,6 @@
3535
// And by defining our own we can ensure it uses the correct const format.
3636
#define MP_PI MICROPY_FLOAT_CONST(3.14159265358979323846)
3737

38-
/// \module math - mathematical functions
39-
///
40-
/// The `math` module provides some basic mathematical funtions for
41-
/// working with floating-point numbers.
42-
4338
STATIC NORETURN void math_error(void) {
4439
mp_raise_ValueError("math domain error");
4540
}
@@ -75,80 +70,74 @@ STATIC NORETURN void math_error(void) {
7570
#define log2(x) (log(x) * 1.442695040888963407354163704)
7671
#endif
7772

78-
/// \function sqrt(x)
79-
/// Returns the square root of `x`.
73+
// sqrt(x): returns the square root of x
8074
MATH_FUN_1_ERRCOND(sqrt, sqrt, (x < (mp_float_t)0.0))
81-
/// \function pow(x, y)
82-
/// Returns `x` to the power of `y`.
75+
// pow(x, y): returns x to the power of y
8376
MATH_FUN_2(pow, pow)
84-
/// \function exp(x)
77+
// exp(x)
8578
MATH_FUN_1(exp, exp)
8679
#if MICROPY_PY_MATH_SPECIAL_FUNCTIONS
87-
/// \function expm1(x)
80+
// expm1(x)
8881
MATH_FUN_1(expm1, expm1)
89-
/// \function log2(x)
82+
// log2(x)
9083
MATH_FUN_1_ERRCOND(log2, log2, (x <= (mp_float_t)0.0))
91-
/// \function log10(x)
84+
// log10(x)
9285
MATH_FUN_1_ERRCOND(log10, log10, (x <= (mp_float_t)0.0))
93-
/// \function cosh(x)
86+
// cosh(x)
9487
MATH_FUN_1(cosh, cosh)
95-
/// \function sinh(x)
88+
// sinh(x)
9689
MATH_FUN_1(sinh, sinh)
97-
/// \function tanh(x)
90+
// tanh(x)
9891
MATH_FUN_1(tanh, tanh)
99-
/// \function acosh(x)
92+
// acosh(x)
10093
MATH_FUN_1(acosh, acosh)
101-
/// \function asinh(x)
94+
// asinh(x)
10295
MATH_FUN_1(asinh, asinh)
103-
/// \function atanh(x)
96+
// atanh(x)
10497
MATH_FUN_1(atanh, atanh)
10598
#endif
106-
/// \function cos(x)
99+
// cos(x)
107100
MATH_FUN_1(cos, cos)
108-
/// \function sin(x)
101+
// sin(x)
109102
MATH_FUN_1(sin, sin)
110-
/// \function tan(x)
103+
// tan(x)
111104
MATH_FUN_1(tan, tan)
112-
/// \function acos(x)
105+
// acos(x)
113106
MATH_FUN_1(acos, acos)
114-
/// \function asin(x)
107+
// asin(x)
115108
MATH_FUN_1(asin, asin)
116-
/// \function atan(x)
109+
// atan(x)
117110
MATH_FUN_1(atan, atan)
118-
/// \function atan2(y, x)
111+
// atan2(y, x)
119112
MATH_FUN_2(atan2, atan2)
120-
/// \function ceil(x)
113+
// ceil(x)
121114
MATH_FUN_1_TO_INT(ceil, ceil)
122-
/// \function copysign(x, y)
115+
// copysign(x, y)
123116
MATH_FUN_2(copysign, copysign)
124-
/// \function fabs(x)
117+
// fabs(x)
125118
MATH_FUN_1(fabs, fabs)
126-
/// \function floor(x)
119+
// floor(x)
127120
MATH_FUN_1_TO_INT(floor, floor) //TODO: delegate to x.__floor__() if x is not a float
128-
/// \function fmod(x, y)
121+
// fmod(x, y)
129122
MATH_FUN_2(fmod, fmod)
130-
/// \function isfinite(x)
123+
// isfinite(x)
131124
MATH_FUN_1_TO_BOOL(isfinite, isfinite)
132-
/// \function isinf(x)
125+
// isinf(x)
133126
MATH_FUN_1_TO_BOOL(isinf, isinf)
134-
/// \function isnan(x)
127+
// isnan(x)
135128
MATH_FUN_1_TO_BOOL(isnan, isnan)
136-
/// \function trunc(x)
129+
// trunc(x)
137130
MATH_FUN_1_TO_INT(trunc, trunc)
138-
/// \function ldexp(x, exp)
131+
// ldexp(x, exp)
139132
MATH_FUN_2(ldexp, ldexp)
140133
#if MICROPY_PY_MATH_SPECIAL_FUNCTIONS
141-
/// \function erf(x)
142-
/// Return the error function of `x`.
134+
// erf(x): return the error function of x
143135
MATH_FUN_1(erf, erf)
144-
/// \function erfc(x)
145-
/// Return the complementary error function of `x`.
136+
// erfc(x): return the complementary error function of x
146137
MATH_FUN_1(erfc, erfc)
147-
/// \function gamma(x)
148-
/// Return the gamma function of `x`.
138+
// gamma(x): return the gamma function of x
149139
MATH_FUN_1(gamma, tgamma)
150-
/// \function lgamma(x)
151-
/// return the natural logarithm of the gamma function of `x`.
140+
// lgamma(x): return the natural logarithm of the gamma function of x
152141
MATH_FUN_1(lgamma, lgamma)
153142
#endif
154143
//TODO: factorial, fsum
@@ -178,8 +167,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mp_math_log_obj, 1, 2, mp_math_log);
178167

179168
// Functions that return a tuple
180169

181-
/// \function frexp(x)
182-
/// Converts a floating-point number to fractional and integral components.
170+
// frexp(x): converts a floating-point number to fractional and integral components
183171
STATIC mp_obj_t mp_math_frexp(mp_obj_t x_obj) {
184172
int int_exponent = 0;
185173
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) {
190178
}
191179
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_math_frexp_obj, mp_math_frexp);
192180

193-
/// \function modf(x)
181+
// modf(x)
194182
STATIC mp_obj_t mp_math_modf(mp_obj_t x_obj) {
195183
mp_float_t int_part = 0.0;
196184
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);
203191

204192
// Angular conversions
205193

206-
/// \function radians(x)
194+
// radians(x)
207195
STATIC mp_obj_t mp_math_radians(mp_obj_t x_obj) {
208196
return mp_obj_new_float(mp_obj_get_float(x_obj) * (MP_PI / MICROPY_FLOAT_CONST(180.0)));
209197
}
210198
STATIC MP_DEFINE_CONST_FUN_OBJ_1(mp_math_radians_obj, mp_math_radians);
211199

212-
/// \function degrees(x)
200+
// degrees(x)
213201
STATIC mp_obj_t mp_math_degrees(mp_obj_t x_obj) {
214202
return mp_obj_new_float(mp_obj_get_float(x_obj) * (MICROPY_FLOAT_CONST(180.0) / MP_PI));
215203
}

‎py/modsys.c‎

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,6 @@
4242

4343
#include "genhdr/mpversion.h"
4444

45-
/// \module sys - system specific functions
46-
4745
// defined per port; type of these is irrelevant, just need pointer
4846
extern struct _mp_dummy_t mp_sys_stdin_obj;
4947
extern struct _mp_dummy_t mp_sys_stdout_obj;
@@ -53,10 +51,10 @@ extern struct _mp_dummy_t mp_sys_stderr_obj;
5351
const mp_print_t mp_sys_stdout_print = {&mp_sys_stdout_obj, mp_stream_write_adaptor};
5452
#endif
5553

56-
/// \constant version - Python language version that this implementation conforms to, as a string
54+
// version - Python language version that this implementation conforms to, as a string
5755
STATIC const MP_DEFINE_STR_OBJ(version_obj, "3.4.0");
5856

59-
/// \constant version_info - Python language version that this implementation conforms to, as a tuple of ints
57+
// version_info - Python language version that this implementation conforms to, as a tuple of ints
6058
#define I(n) MP_OBJ_NEW_SMALL_INT(n)
6159
// TODO: CPython is now at 5-element array, but save 2 els so far...
6260
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 = {
9189
#undef I
9290

9391
#ifdef MICROPY_PY_SYS_PLATFORM
94-
/// \constant platform - the platform that MicroPython is running on
92+
// platform - the platform that MicroPython is running on
9593
STATIC const MP_DEFINE_STR_OBJ(platform_obj, MICROPY_PY_SYS_PLATFORM);
9694
#endif
9795

98-
/// \function exit([retval])
99-
/// Raise a `SystemExit` exception. If an argument is given, it is the
100-
/// value given to `SystemExit`.
96+
// exit([retval]): raise SystemExit, with optional argument given to the exception
10197
STATIC mp_obj_t mp_sys_exit(size_t n_args, const mp_obj_t *args) {
10298
mp_obj_t exc;
10399
if (n_args == 0) {
@@ -163,7 +159,6 @@ STATIC const mp_rom_map_elem_t mp_module_sys_globals_table[] = {
163159
#ifdef MICROPY_PY_SYS_PLATFORM
164160
{ MP_ROM_QSTR(MP_QSTR_platform), MP_ROM_PTR(&platform_obj) },
165161
#endif
166-
/// \constant byteorder - the byte order of the system ("little" or "big")
167162
#if MP_ENDIANNESS_LITTLE
168163
{ MP_ROM_QSTR(MP_QSTR_byteorder), MP_ROM_QSTR(MP_QSTR_little) },
169164
#else
@@ -184,12 +179,10 @@ STATIC const mp_rom_map_elem_t mp_module_sys_globals_table[] = {
184179
#endif
185180

186181
#if MICROPY_PY_SYS_EXIT
187-
// documented per-port
188182
{ MP_ROM_QSTR(MP_QSTR_exit), MP_ROM_PTR(&mp_sys_exit_obj) },
189183
#endif
190184

191185
#if MICROPY_PY_SYS_STDFILES
192-
// documented per-port
193186
{ MP_ROM_QSTR(MP_QSTR_stdin), MP_ROM_PTR(&mp_sys_stdin_obj) },
194187
{ MP_ROM_QSTR(MP_QSTR_stdout), MP_ROM_PTR(&mp_sys_stdout_obj) },
195188
{ MP_ROM_QSTR(MP_QSTR_stderr), MP_ROM_PTR(&mp_sys_stderr_obj) },

0 commit comments

Comments
 (0)