diff --git a/extmod/moductypes.c b/extmod/moductypes.c index 79a49d5c32..51626600cc 100644 --- a/extmod/moductypes.c +++ b/extmod/moductypes.c @@ -34,38 +34,10 @@ #if MICROPY_PY_UCTYPES -/// \module uctypes - Access data structures in memory -/// -/// The module allows to define layout of raw data structure (using terms -/// of C language), and then access memory buffers using this definition. -/// The module also provides convenience functions to access memory buffers -/// contained in Python objects or wrap memory buffers in Python objects. -/// \constant UINT8_1 - uint8_t value type - -/// \class struct - C-like structure -/// -/// Encapsulalation of in-memory data structure. This class doesn't define -/// any methods, only attribute access (for structure fields) and -/// indexing (for pointer and array fields). -/// -/// Usage: -/// -/// # Define layout of a structure with 2 fields -/// # 0 and 4 are byte offsets of fields from the beginning of struct -/// # they are logically ORed with field type -/// FOO_STRUCT = {"a": 0 | uctypes.UINT32, "b": 4 | uctypes.UINT8} -/// -/// # Example memory buffer to access (contained in bytes object) -/// buf = b"\x64\0\0\0\0x14" -/// -/// # Create structure object referring to address of -/// # the data in the buffer above -/// s = uctypes.struct(FOO_STRUCT, uctypes.addressof(buf)) -/// -/// # Access fields -/// print(s.a, s.b) -/// # Result: -/// # 100, 20 +// The uctypes module allows defining the layout of a raw data structure (using +// terms of the C language), and then access memory buffers using this definition. +// The module also provides convenience functions to access memory buffers +// contained in Python objects or wrap memory buffers in Python objects. #define LAYOUT_LITTLE_ENDIAN (0) #define LAYOUT_BIG_ENDIAN (1) @@ -647,9 +619,8 @@ STATIC mp_int_t uctypes_get_buffer(mp_obj_t self_in, mp_buffer_info_t *bufinfo, return 0; } -/// \function addressof() -/// Return address of object's data (applies to object providing buffer -/// interface). +// addressof() +// Return address of object's data (applies to objects providing the buffer interface). STATIC mp_obj_t uctypes_struct_addressof(mp_obj_t buf) { mp_buffer_info_t bufinfo; mp_get_buffer_raise(buf, &bufinfo, MP_BUFFER_READ); @@ -657,19 +628,15 @@ STATIC mp_obj_t uctypes_struct_addressof(mp_obj_t buf) { } MP_DEFINE_CONST_FUN_OBJ_1(uctypes_struct_addressof_obj, uctypes_struct_addressof); -/// \function bytearray_at() -/// Capture memory at given address of given size as bytearray. Memory is -/// captured by reference (and thus memory pointed by bytearray may change -/// or become invalid at later time). Use bytes_at() to capture by value. +// bytearray_at() +// Capture memory at given address of given size as bytearray. STATIC mp_obj_t uctypes_struct_bytearray_at(mp_obj_t ptr, mp_obj_t size) { return mp_obj_new_bytearray_by_ref(mp_obj_int_get_truncated(size), (void *)(uintptr_t)mp_obj_int_get_truncated(ptr)); } MP_DEFINE_CONST_FUN_OBJ_2(uctypes_struct_bytearray_at_obj, uctypes_struct_bytearray_at); -/// \function bytes_at() -/// Capture memory at given address of given size as bytes. Memory is -/// captured by value, i.e. copied. Use bytearray_at() to capture by reference -/// ("zero copy"). +// bytes_at() +// Capture memory at given address of given size as bytes. STATIC mp_obj_t uctypes_struct_bytes_at(mp_obj_t ptr, mp_obj_t size) { return mp_obj_new_bytes((void *)(uintptr_t)mp_obj_int_get_truncated(ptr), mp_obj_int_get_truncated(size)); } @@ -695,36 +662,19 @@ STATIC const mp_rom_map_elem_t mp_module_uctypes_globals_table[] = { { MP_ROM_QSTR(MP_QSTR_bytes_at), MP_ROM_PTR(&uctypes_struct_bytes_at_obj) }, { MP_ROM_QSTR(MP_QSTR_bytearray_at), MP_ROM_PTR(&uctypes_struct_bytearray_at_obj) }, - /// \moduleref uctypes - - /// \constant NATIVE - Native structure layout - native endianness, - /// platform-specific field alignment { MP_ROM_QSTR(MP_QSTR_NATIVE), MP_ROM_INT(LAYOUT_NATIVE) }, - /// \constant LITTLE_ENDIAN - Little-endian structure layout, tightly packed - /// (no alignment constraints) { MP_ROM_QSTR(MP_QSTR_LITTLE_ENDIAN), MP_ROM_INT(LAYOUT_LITTLE_ENDIAN) }, - /// \constant BIG_ENDIAN - Big-endian structure layout, tightly packed - /// (no alignment constraints) { MP_ROM_QSTR(MP_QSTR_BIG_ENDIAN), MP_ROM_INT(LAYOUT_BIG_ENDIAN) }, - /// \constant VOID - void value type, may be used only as pointer target type. { MP_ROM_QSTR(MP_QSTR_VOID), MP_ROM_INT(TYPE2SMALLINT(UINT8, VAL_TYPE_BITS)) }, - /// \constant UINT8 - uint8_t value type { MP_ROM_QSTR(MP_QSTR_UINT8), MP_ROM_INT(TYPE2SMALLINT(UINT8, 4)) }, - /// \constant INT8 - int8_t value type { MP_ROM_QSTR(MP_QSTR_INT8), MP_ROM_INT(TYPE2SMALLINT(INT8, 4)) }, - /// \constant UINT16 - uint16_t value type { MP_ROM_QSTR(MP_QSTR_UINT16), MP_ROM_INT(TYPE2SMALLINT(UINT16, 4)) }, - /// \constant INT16 - int16_t value type { MP_ROM_QSTR(MP_QSTR_INT16), MP_ROM_INT(TYPE2SMALLINT(INT16, 4)) }, - /// \constant UINT32 - uint32_t value type { MP_ROM_QSTR(MP_QSTR_UINT32), MP_ROM_INT(TYPE2SMALLINT(UINT32, 4)) }, - /// \constant INT32 - int32_t value type { MP_ROM_QSTR(MP_QSTR_INT32), MP_ROM_INT(TYPE2SMALLINT(INT32, 4)) }, - /// \constant UINT64 - uint64_t value type { MP_ROM_QSTR(MP_QSTR_UINT64), MP_ROM_INT(TYPE2SMALLINT(UINT64, 4)) }, - /// \constant INT64 - int64_t value type { MP_ROM_QSTR(MP_QSTR_INT64), MP_ROM_INT(TYPE2SMALLINT(INT64, 4)) }, { MP_ROM_QSTR(MP_QSTR_BFUINT8), MP_ROM_INT(TYPE2SMALLINT(BFUINT8, 4)) }, diff --git a/extmod/moduselect.c b/extmod/moduselect.c index 6d8249f427..fbd51960d5 100644 --- a/extmod/moduselect.c +++ b/extmod/moduselect.c @@ -40,10 +40,6 @@ // Flags for poll() #define FLAG_ONESHOT (1) -/// \module select - Provides select function to wait for events on a stream -/// -/// This module provides the select function. - typedef struct _poll_obj_t { mp_obj_t obj; mp_uint_t (*ioctl)(mp_obj_t obj, mp_uint_t request, uintptr_t arg, int *errcode); @@ -111,7 +107,7 @@ STATIC mp_uint_t poll_map_poll(mp_map_t *poll_map, size_t *rwx_num) { return n_ready; } -/// \function select(rlist, wlist, xlist[, timeout]) +// select(rlist, wlist, xlist[, timeout]) STATIC mp_obj_t select_select(size_t n_args, const mp_obj_t *args) { // get array data from tuple/list arguments size_t rwx_len[3]; @@ -178,8 +174,6 @@ STATIC mp_obj_t select_select(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mp_select_select_obj, 3, 4, select_select); -/// \class Poll - poll class - typedef struct _mp_obj_poll_t { mp_obj_base_t base; mp_map_t poll_map; @@ -190,7 +184,7 @@ typedef struct _mp_obj_poll_t { mp_obj_t ret_tuple; } mp_obj_poll_t; -/// \method register(obj[, eventmask]) +// register(obj[, eventmask]) STATIC mp_obj_t poll_register(size_t n_args, const mp_obj_t *args) { mp_obj_poll_t *self = MP_OBJ_TO_PTR(args[0]); mp_uint_t flags; @@ -204,7 +198,7 @@ STATIC mp_obj_t poll_register(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(poll_register_obj, 2, 3, poll_register); -/// \method unregister(obj) +// unregister(obj) STATIC mp_obj_t poll_unregister(mp_obj_t self_in, mp_obj_t obj_in) { mp_obj_poll_t *self = MP_OBJ_TO_PTR(self_in); mp_map_lookup(&self->poll_map, mp_obj_id(obj_in), MP_MAP_LOOKUP_REMOVE_IF_FOUND); @@ -213,7 +207,7 @@ STATIC mp_obj_t poll_unregister(mp_obj_t self_in, mp_obj_t obj_in) { } MP_DEFINE_CONST_FUN_OBJ_2(poll_unregister_obj, poll_unregister); -/// \method modify(obj, eventmask) +// modify(obj, eventmask) STATIC mp_obj_t poll_modify(mp_obj_t self_in, mp_obj_t obj_in, mp_obj_t eventmask_in) { mp_obj_poll_t *self = MP_OBJ_TO_PTR(self_in); mp_map_elem_t *elem = mp_map_lookup(&self->poll_map, mp_obj_id(obj_in), MP_MAP_LOOKUP); @@ -348,7 +342,7 @@ STATIC const mp_obj_type_t mp_type_poll = { .locals_dict = (void *)&poll_locals_dict, }; -/// \function poll() +// poll() STATIC mp_obj_t select_poll(void) { mp_obj_poll_t *poll = m_new_obj(mp_obj_poll_t); poll->base.type = &mp_type_poll; diff --git a/extmod/vfs_fat.c b/extmod/vfs_fat.c index 95b7ad9944..644be57ae7 100644 --- a/extmod/vfs_fat.c +++ b/extmod/vfs_fat.c @@ -256,7 +256,7 @@ STATIC mp_obj_t fat_vfs_mkdir(mp_obj_t vfs_in, mp_obj_t path_o) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(fat_vfs_mkdir_obj, fat_vfs_mkdir); -/// Change current directory. +// Change current directory. STATIC mp_obj_t fat_vfs_chdir(mp_obj_t vfs_in, mp_obj_t path_in) { mp_obj_fat_vfs_t *self = MP_OBJ_TO_PTR(vfs_in); const char *path; @@ -272,7 +272,7 @@ STATIC mp_obj_t fat_vfs_chdir(mp_obj_t vfs_in, mp_obj_t path_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_2(fat_vfs_chdir_obj, fat_vfs_chdir); -/// Get the current directory. +// Get the current directory. STATIC mp_obj_t fat_vfs_getcwd(mp_obj_t vfs_in) { mp_obj_fat_vfs_t *self = MP_OBJ_TO_PTR(vfs_in); char buf[MICROPY_ALLOC_PATH_MAX + 1]; @@ -284,8 +284,7 @@ STATIC mp_obj_t fat_vfs_getcwd(mp_obj_t vfs_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(fat_vfs_getcwd_obj, fat_vfs_getcwd); -/// \function stat(path) -/// Get the status of a file or directory. +// Get the status of a file or directory. STATIC mp_obj_t fat_vfs_stat(mp_obj_t vfs_in, mp_obj_t path_in) { mp_obj_fat_vfs_t *self = MP_OBJ_TO_PTR(vfs_in); const char *path = mp_obj_str_get_str(path_in);