From cfe24b85322a029758c3376eed2726657397bf33 Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Thu, 30 May 2019 19:01:27 -0700 Subject: [PATCH] Improve rST consistency for rst2pyi use --- shared-bindings/_pixelbuf/PixelBuf.c | 42 ++++++++++---------- shared-bindings/_pixelbuf/__init__.c | 38 +++++++++--------- shared-bindings/audiobusio/PDMIn.c | 2 +- shared-bindings/audioio/WaveFile.c | 4 +- shared-bindings/bitbangio/I2C.c | 18 ++++----- shared-bindings/bitbangio/SPI.c | 22 +++++----- shared-bindings/bleio/AddressType.c | 2 +- shared-bindings/bleio/CharacteristicBuffer.c | 2 +- shared-bindings/bleio/UUID.c | 18 ++++++--- shared-bindings/board/__init__.c | 6 +-- shared-bindings/busio/I2C.c | 22 +++++----- shared-bindings/busio/SPI.c | 26 ++++++------ shared-bindings/busio/UART.c | 4 +- shared-bindings/displayio/TileGrid.c | 2 +- shared-bindings/displayio/__init__.c | 2 +- shared-bindings/help.c | 2 +- shared-bindings/microcontroller/Pin.c | 2 +- shared-bindings/microcontroller/RunMode.c | 14 +++++-- shared-bindings/microcontroller/__init__.c | 16 ++++---- shared-bindings/neopixel_write/__init__.c | 4 +- shared-bindings/network/__init__.c | 2 +- shared-bindings/pulseio/PWMOut.c | 2 +- shared-bindings/pulseio/PulseIn.c | 2 +- shared-bindings/socket/__init__.c | 2 +- shared-bindings/storage/__init__.c | 6 +-- shared-bindings/struct/__init__.c | 8 ++-- shared-bindings/time/__init__.c | 33 +++++++-------- shared-bindings/uheap/__init__.c | 2 +- shared-bindings/ustack/__init__.c | 6 +-- shared-bindings/wiznet/wiznet5k.c | 2 +- 30 files changed, 165 insertions(+), 148 deletions(-) diff --git a/shared-bindings/_pixelbuf/PixelBuf.c b/shared-bindings/_pixelbuf/PixelBuf.c index 7c2766aa3f..420720e622 100644 --- a/shared-bindings/_pixelbuf/PixelBuf.c +++ b/shared-bindings/_pixelbuf/PixelBuf.c @@ -51,7 +51,7 @@ extern const int32_t colorwheel(float pos); //| //| :class:`~_pixelbuf.PixelBuf` implements an RGB[W] bytearray abstraction. //| -//| .. class:: PixelBuf(size, buf, byteorder=BGR, bpp=3) +//| .. class:: PixelBuf(size, buf, byteorder=BGR, brightness=0, rawbuf=None, offset=0, dotstar=False, auto_write=False, write_function=None, write_args=None) //| //| Create a PixelBuf object of the specified size, byteorder, and bits per pixel. //| @@ -66,14 +66,14 @@ extern const int32_t colorwheel(float pos); //| //| :param ~int size: Number of pixelsx //| :param ~bytearray buf: Bytearray to store pixel data in -//| :param ~_pixelbuf.ByteOrder byteorder: Byte order constant from `_pixelbuf` (also sets the bpp) +//| :param ~_pixelbuf.ByteOrder byteorder: Byte order constant from `_pixelbuf` //| :param ~float brightness: Brightness (0 to 1.0, default 1.0) //| :param ~bytearray rawbuf: Bytearray to store raw pixel colors in //| :param ~int offset: Offset from start of buffer (default 0) //| :param ~bool dotstar: Dotstar mode (default False) //| :param ~bool auto_write: Whether to automatically write pixels (Default False) //| :param ~callable write_function: (optional) Callable to use to send pixels -//| :param ~list write_args: (optional) Tuple or list of args to pass to ``write_function``. The +//| :param ~list write_args: (optional) Tuple or list of args to pass to ``write_function``. The //| PixelBuf instance is appended after these args. //| STATIC mp_obj_t pixelbuf_pixelbuf_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -95,7 +95,7 @@ STATIC mp_obj_t pixelbuf_pixelbuf_make_new(const mp_obj_type_t *type, size_t n_a mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); - if (mp_obj_is_subclass_fast(args[ARG_byteorder].u_obj, &pixelbuf_byteorder_type)) + if (mp_obj_is_subclass_fast(args[ARG_byteorder].u_obj, &pixelbuf_byteorder_type)) mp_raise_TypeError_varg(translate("byteorder is not an instance of ByteOrder (got a %s)"), mp_obj_get_type_str(args[ARG_byteorder].u_obj)); pixelbuf_byteorder_obj_t *byteorder = (args[ARG_byteorder].u_obj == mp_const_none) ? MP_OBJ_FROM_PTR(&byteorder_BGR) : args[ARG_byteorder].u_obj; @@ -122,7 +122,7 @@ STATIC mp_obj_t pixelbuf_pixelbuf_make_new(const mp_obj_type_t *type, size_t n_a if (!MP_OBJ_IS_TYPE(args[ARG_write_args].u_obj, &mp_type_list) && !MP_OBJ_IS_TYPE(args[ARG_write_args].u_obj, &mp_type_tuple) && - args[ARG_write_args].u_obj != mp_const_none) + args[ARG_write_args].u_obj != mp_const_none) { mp_raise_ValueError(translate("write_args must be a list, tuple, or None")); } @@ -186,8 +186,8 @@ STATIC mp_obj_t pixelbuf_pixelbuf_make_new(const mp_obj_type_t *type, size_t n_a else if (self->brightness > 1) self->brightness = 1; } - - if (self->dotstar_mode) { + + if (self->dotstar_mode) { // Initialize the buffer with the dotstar start bytes. // Header and end must be setup by caller for (uint i = 0; i < self->pixels * 4; i += 4) { @@ -197,7 +197,7 @@ STATIC mp_obj_t pixelbuf_pixelbuf_make_new(const mp_obj_type_t *type, size_t n_a } } } - + return MP_OBJ_FROM_PTR(self); } @@ -227,7 +227,7 @@ const mp_obj_property_t pixelbuf_pixelbuf_bpp_obj = { //| setting this value causes a recomputation of the values in buf. //| If only a buf was provided, then the brightness only applies to //| future pixel changes. -//| In DotStar mode +//| In DotStar mode //| STATIC mp_obj_t pixelbuf_pixelbuf_obj_get_brightness(mp_obj_t self_in) { mp_check_self(MP_OBJ_IS_TYPE(self_in, &pixelbuf_pixelbuf_type)); @@ -266,7 +266,7 @@ void pixelbuf_recalculate_brightness(pixelbuf_pixelbuf_obj_t *self) { // Compensate for shifted buffer (bpp=3 dotstar) for (uint i = 0; i < self->bytes; i++) { // Don't adjust per-pixel luminance bytes in dotstar mode - if (!self->dotstar_mode || (i % 4 != 0)) + if (!self->dotstar_mode || (i % 4 != 0)) buf[i] = rawbuf[i] * self->brightness; } } @@ -367,11 +367,13 @@ void call_write_function(pixelbuf_pixelbuf_obj_t *self) { } } - - -//| .. method:: [] +//| .. method:: __getitem__(index) //| -//| Get or set pixels. Supports individual pixels and slices. +//| Returns the pixel value at the given index. +//| +//| .. method:: __setitem__(index, value) +//| +//| Sets the pixel value at the given index. //| STATIC mp_obj_t pixelbuf_pixelbuf_subscr(mp_obj_t self_in, mp_obj_t index_in, mp_obj_t value) { mp_check_self(MP_OBJ_IS_TYPE(self_in, &pixelbuf_pixelbuf_type)); @@ -380,7 +382,7 @@ STATIC mp_obj_t pixelbuf_pixelbuf_subscr(mp_obj_t self_in, mp_obj_t index_in, mp // delete item // slice deletion return MP_OBJ_NULL; // op not supported - } + } pixelbuf_pixelbuf_obj_t *self = MP_OBJ_TO_PTR(self_in); if (0) { @@ -390,7 +392,7 @@ STATIC mp_obj_t pixelbuf_pixelbuf_subscr(mp_obj_t self_in, mp_obj_t index_in, mp if (!mp_seq_get_fast_slice_indexes(self->bytes, index_in, &slice)) mp_raise_NotImplementedError(translate("Only slices with step=1 (aka None) are supported")); - if ((slice.stop * self->pixel_step) > self->bytes) + if ((slice.stop * self->pixel_step) > self->bytes) mp_raise_IndexError(translate("Range out of bounds")); if (value == MP_OBJ_SENTINEL) { // Get @@ -422,8 +424,8 @@ STATIC mp_obj_t pixelbuf_pixelbuf_subscr(mp_obj_t self_in, mp_obj_t index_in, mp for (size_t i = slice.start; i < slice.stop; i++) { mp_obj_t *item = src_objs[i-slice.start]; if (MP_OBJ_IS_TYPE(value, &mp_type_list) || MP_OBJ_IS_TYPE(value, &mp_type_tuple) || MP_OBJ_IS_INT(value)) { - pixelbuf_set_pixel(self->buf + (i * self->pixel_step), - self->two_buffers ? self->rawbuf + (i * self->pixel_step) : NULL, + pixelbuf_set_pixel(self->buf + (i * self->pixel_step), + self->two_buffers ? self->rawbuf + (i * self->pixel_step) : NULL, self->brightness, item, &self->byteorder, self->dotstar_mode); } } @@ -438,14 +440,14 @@ STATIC mp_obj_t pixelbuf_pixelbuf_subscr(mp_obj_t self_in, mp_obj_t index_in, mp } else { // Single index rather than slice. size_t index = mp_get_index(self->base.type, self->pixels, index_in, false); size_t offset = (index * self->pixel_step); - if (offset > self->bytes) + if (offset > self->bytes) mp_raise_IndexError(translate("Pixel beyond bounds of buffer")); if (value == MP_OBJ_SENTINEL) { // Get uint8_t *pixelstart = (uint8_t *)(self->two_buffers ? self->rawbuf : self->buf) + offset; return pixelbuf_get_pixel(pixelstart, &self->byteorder, self->dotstar_mode); } else { // Store - pixelbuf_set_pixel(self->buf + offset, self->two_buffers ? self->rawbuf + offset : NULL, + pixelbuf_set_pixel(self->buf + offset, self->two_buffers ? self->rawbuf + offset : NULL, self->brightness, value, &self->byteorder, self->dotstar_mode); if (self->auto_write) call_write_function(self); diff --git a/shared-bindings/_pixelbuf/__init__.c b/shared-bindings/_pixelbuf/__init__.c index 31defc7fbc..48b9f1cef1 100644 --- a/shared-bindings/_pixelbuf/__init__.c +++ b/shared-bindings/_pixelbuf/__init__.c @@ -53,7 +53,7 @@ //| //| PixelBuf -//| .. class:: ByteOrder +//| .. class:: ByteOrder() //| //| Classes representing byteorders for circuitpython @@ -169,34 +169,34 @@ const int32_t colorwheel(float pos) { /// RGB -//| .. class:: RGB +//| .. data:: RGB //| //| * **order** Red, Green, Blue //| * **bpp** 3 PIXELBUF_BYTEORDER(RGB, 3, 0, 1, 2, 3, false, false) -//| .. class:: RBG +//| .. data:: RBG //| //| * **order** Red, Blue, Green //| * **bpp** 3 PIXELBUF_BYTEORDER(RBG, 3, 0, 2, 1, 3, false, false) -//| .. class:: GRB +//| .. data:: GRB //| //| * **order** Green, Red, Blue //| * **bpp** 3 //| //| Commonly used by NeoPixel. PIXELBUF_BYTEORDER(GRB, 3, 1, 0, 2, 3, false, false) -//| .. class:: GBR +//| .. data:: GBR //| //| * **order** Green, Blue, Red //| * **bpp** 3 PIXELBUF_BYTEORDER(GBR, 3, 1, 2, 0, 3, false, false) -//| .. class:: BRG +//| .. data:: BRG //| //| * **order** Blue, Red, Green //| * **bpp** 3 PIXELBUF_BYTEORDER(BRG, 3, 2, 0, 1, 3, false, false) -//| .. class:: BGR +//| .. data:: BGR //| //| * **order** Blue, Green, Red //| * **bpp** 3 @@ -205,19 +205,19 @@ PIXELBUF_BYTEORDER(BRG, 3, 2, 0, 1, 3, false, false) PIXELBUF_BYTEORDER(BGR, 3, 2, 1, 0, 3, false, false) // RGBW -//| .. class:: RGBW +//| .. data:: RGBW //| //| * **order** Red, Green, Blue, White //| * **bpp** 4 //| * **has_white** True PIXELBUF_BYTEORDER(RGBW, 4, 0, 1, 2, 3, true, false) -//| .. class:: RBGW +//| .. data:: RBGW //| //| * **order** Red, Blue, Green, White //| * **bpp** 4 //| * **has_white** True PIXELBUF_BYTEORDER(RBGW, 4, 0, 2, 1, 3, true, false) -//| .. class:: GRBW +//| .. data:: GRBW //| //| * **order** Green, Red, Blue, White //| * **bpp** 4 @@ -225,19 +225,19 @@ PIXELBUF_BYTEORDER(RBGW, 4, 0, 2, 1, 3, true, false) //| //| Commonly used by RGBW NeoPixels. PIXELBUF_BYTEORDER(GRBW, 4, 1, 0, 2, 3, true, false) -//| .. class:: GBRW +//| .. data:: GBRW //| //| * **order** Green, Blue, Red, White //| * **bpp** 4 //| * **has_white** True PIXELBUF_BYTEORDER(GBRW, 4, 1, 2, 0, 3, true, false) -//| .. class:: BRGW +//| .. data:: BRGW //| //| * **order** Blue, Red, Green, White //| * **bpp** 4 //| * **has_white** True PIXELBUF_BYTEORDER(BRGW, 4, 2, 0, 1, 3, true, false) -//| .. class:: BGRW +//| .. data:: BGRW //| //| * **order** Blue, Green, Red, White //| * **bpp** 4 @@ -248,37 +248,37 @@ PIXELBUF_BYTEORDER(BGRW, 4, 2, 1, 0, 3, true, false) // Luminosity chosen because the luminosity of a Dotstar at full bright // burns the eyes like looking at the Sun. // https://www.thesaurus.com/browse/luminosity?s=t -//| .. class:: LRGB +//| .. data:: LRGB //| //| * **order** *Luminosity*, Red, Green, Blue //| * **bpp** 4 //| * **has_luminosity** True PIXELBUF_BYTEORDER(LRGB, 4, 1, 2, 3, 0, false, true) -//| .. class:: LRBG +//| .. data:: LRBG //| //| * **order** *Luminosity*, Red, Blue, Green //| * **bpp** 4 //| * **has_luminosity** True PIXELBUF_BYTEORDER(LRBG, 4, 1, 3, 2, 0, false, true) -//| .. class:: LGRB +//| .. data:: LGRB //| //| * **order** *Luminosity*, Green, Red, Blue //| * **bpp** 4 //| * **has_luminosity** True PIXELBUF_BYTEORDER(LGRB, 4, 2, 1, 3, 0, false, true) -//| .. class:: LGBR +//| .. data:: LGBR //| //| * **order** *Luminosity*, Green, Blue, Red //| * **bpp** 4 //| * **has_luminosity** True PIXELBUF_BYTEORDER(LGBR, 4, 2, 3, 1, 0, false, true) -//| .. class:: LBRG +//| .. data:: LBRG //| //| * **order** *Luminosity*, Blue, Red, Green //| * **bpp** 4 //| * **has_luminosity** True PIXELBUF_BYTEORDER(LBRG, 4, 3, 1, 2, 0, false, true) -//| .. class:: LBGR +//| .. data:: LBGR //| //| * **order** *Luminosity*, Blue, Green, Red //| * **bpp** 4 diff --git a/shared-bindings/audiobusio/PDMIn.c b/shared-bindings/audiobusio/PDMIn.c index 5dca3fa598..0f19e2587e 100644 --- a/shared-bindings/audiobusio/PDMIn.c +++ b/shared-bindings/audiobusio/PDMIn.c @@ -43,7 +43,7 @@ //| //| PDMIn can be used to record an input audio signal on a given set of pins. //| -//| .. class:: PDMIn(clock_pin, data_pin, \*, sample_rate=16000, bit_depth=8, mono=True, oversample=64, startup_delay=0.11) +//| .. class:: PDMIn(clock_pin, data_pin, *, sample_rate=16000, bit_depth=8, mono=True, oversample=64, startup_delay=0.11) //| //| Create a PDMIn object associated with the given pins. This allows you to //| record audio signals from the given pins. Individual ports may put further diff --git a/shared-bindings/audioio/WaveFile.c b/shared-bindings/audioio/WaveFile.c index cddeef7695..a4e37231a8 100644 --- a/shared-bindings/audioio/WaveFile.c +++ b/shared-bindings/audioio/WaveFile.c @@ -41,11 +41,11 @@ //| A .wav file prepped for audio playback. Only mono and stereo files are supported. Samples must //| be 8 bit unsigned or 16 bit signed. //| -//| .. class:: WaveFile(filename) +//| .. class:: WaveFile(file) //| //| Load a .wav file for playback with `audioio.AudioOut` or `audiobusio.I2SOut`. //| -//| :param bytes-like file: Already opened wave file +//| :param typing.BinaryIO file: Already opened wave file //| //| Playing a wave file from flash:: //| diff --git a/shared-bindings/bitbangio/I2C.c b/shared-bindings/bitbangio/I2C.c index 374268e3db..a74f08b0bc 100644 --- a/shared-bindings/bitbangio/I2C.c +++ b/shared-bindings/bitbangio/I2C.c @@ -42,7 +42,7 @@ //| :class:`I2C` --- Two wire serial protocol //| ------------------------------------------ //| -//| .. class:: I2C(scl, sda, \*, frequency=400000) +//| .. class:: I2C(scl, sda, *, frequency=400000, timeout) //| //| I2C is a two-wire protocol for communicating between devices. At the //| physical level it consists of 2 wires: SCL and SDA, the clock and data @@ -75,7 +75,7 @@ STATIC mp_obj_t bitbangio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, return (mp_obj_t)self; } -//| .. method:: I2C.deinit() +//| .. method:: deinit() //| //| Releases control of the underlying hardware so other classes can use it. //| @@ -86,13 +86,13 @@ STATIC mp_obj_t bitbangio_i2c_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_deinit_obj, bitbangio_i2c_obj_deinit); -//| .. method:: I2C.__enter__() +//| .. method:: __enter__() //| //| No-op used in Context Managers. //| // Provided by context manager helper. -//| .. method:: I2C.__exit__() +//| .. method:: __exit__() //| //| Automatically deinitializes the hardware on context exit. See //| :ref:`lifetime-and-contextmanagers` for more info. @@ -110,7 +110,7 @@ static void check_lock(bitbangio_i2c_obj_t *self) { } } -//| .. method:: I2C.scan() +//| .. method:: scan() //| //| Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of //| those that respond. A device responds if it pulls the SDA line low after @@ -132,7 +132,7 @@ STATIC mp_obj_t bitbangio_i2c_scan(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_scan_obj, bitbangio_i2c_scan); -//| .. method:: I2C.try_lock() +//| .. method:: try_lock() //| //| Attempts to grab the I2C lock. Returns True on success. //| @@ -143,7 +143,7 @@ STATIC mp_obj_t bitbangio_i2c_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_try_lock_obj, bitbangio_i2c_obj_try_lock); -//| .. method:: I2C.unlock() +//| .. method:: unlock() //| //| Releases the I2C lock. //| @@ -155,7 +155,7 @@ STATIC mp_obj_t bitbangio_i2c_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_unlock_obj, bitbangio_i2c_obj_unlock); -//| .. method:: I2C.readfrom_into(address, buffer, \*, start=0, end=len(buffer)) +//| .. method:: readfrom_into(address, buffer, *, start=0, end=None) //| //| Read into ``buffer`` from the slave specified by ``address``. //| The number of bytes read will be the length of ``buffer``. @@ -203,7 +203,7 @@ STATIC mp_obj_t bitbangio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_a } MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_i2c_readfrom_into_obj, 3, bitbangio_i2c_readfrom_into); -//| .. method:: I2C.writeto(address, buffer, \*, start=0, end=len(buffer), stop=True) +//| .. method:: writeto(address, buffer, *, start=0, end=None, stop=True) //| //| Write the bytes from ``buffer`` to the slave specified by ``address``. //| Transmits a stop bit if ``stop`` is set. diff --git a/shared-bindings/bitbangio/SPI.c b/shared-bindings/bitbangio/SPI.c index 974ec99e2b..9d00264cd3 100644 --- a/shared-bindings/bitbangio/SPI.c +++ b/shared-bindings/bitbangio/SPI.c @@ -84,7 +84,7 @@ STATIC mp_obj_t bitbangio_spi_make_new(const mp_obj_type_t *type, size_t n_args, return (mp_obj_t)self; } -//| .. method:: SPI.deinit() +//| .. method:: deinit() //| //| Turn off the SPI bus. //| @@ -95,13 +95,13 @@ STATIC mp_obj_t bitbangio_spi_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_spi_deinit_obj, bitbangio_spi_obj_deinit); -//| .. method:: SPI.__enter__() +//| .. method:: __enter__() //| //| No-op used by Context Managers. //| // Provided by context manager helper. -//| .. method:: SPI.__exit__() +//| .. method:: __exit__() //| //| Automatically deinitializes the hardware when exiting a context. See //| :ref:`lifetime-and-contextmanagers` for more info. @@ -120,7 +120,7 @@ static void check_lock(bitbangio_spi_obj_t *self) { } } -//| .. method:: SPI.configure(\*, baudrate=100000, polarity=0, phase=0, bits=8) +//| .. method:: configure(*, baudrate=100000, polarity=0, phase=0, bits=8) //| //| Configures the SPI bus. Only valid when locked. //| @@ -162,7 +162,7 @@ STATIC mp_obj_t bitbangio_spi_configure(size_t n_args, const mp_obj_t *pos_args, } MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_spi_configure_obj, 1, bitbangio_spi_configure); -//| .. method:: SPI.try_lock() +//| .. method:: try_lock() //| //| Attempts to grab the SPI lock. Returns True on success. //| @@ -176,7 +176,7 @@ STATIC mp_obj_t bitbangio_spi_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_spi_try_lock_obj, bitbangio_spi_obj_try_lock); -//| .. method:: SPI.unlock() +//| .. method:: unlock() //| //| Releases the SPI lock. //| @@ -188,7 +188,7 @@ STATIC mp_obj_t bitbangio_spi_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_spi_unlock_obj, bitbangio_spi_obj_unlock); -//| .. method:: SPI.write(buf) +//| .. method:: write(buf) //| //| Write the data contained in ``buf``. Requires the SPI being locked. //| If the buffer is empty, nothing happens. @@ -212,7 +212,7 @@ STATIC mp_obj_t bitbangio_spi_write(mp_obj_t self_in, mp_obj_t wr_buf) { MP_DEFINE_CONST_FUN_OBJ_2(bitbangio_spi_write_obj, bitbangio_spi_write); -//| .. method:: SPI.readinto(buf) +//| .. method:: readinto(buf) //| //| Read into the buffer specified by ``buf`` while writing zeroes. //| Requires the SPI being locked. @@ -236,7 +236,7 @@ STATIC mp_obj_t bitbangio_spi_readinto(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(bitbangio_spi_readinto_obj, 2, 2, bitbangio_spi_readinto); -//| .. method:: SPI.write_readinto(buffer_out, buffer_in, \*, out_start=0, out_end=len(buffer_out), in_start=0, in_end=len(buffer_in)) +//| .. method:: write_readinto(buffer_out, buffer_in, *, out_start=0, out_end=None, in_start=0, in_end=None) //| //| Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. //| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` @@ -246,9 +246,9 @@ MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(bitbangio_spi_readinto_obj, 2, 2, bitbangio_ //| :param bytearray buffer_out: Write out the data in this buffer //| :param bytearray buffer_in: Read data into this buffer //| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` -//| :param int out_end: End of the slice; this index is not included +//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` //| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` -//| :param int in_end: End of the slice; this index is not included +//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)`` //| STATIC mp_obj_t bitbangio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; diff --git a/shared-bindings/bleio/AddressType.c b/shared-bindings/bleio/AddressType.c index cf2151c947..7edf3c1700 100644 --- a/shared-bindings/bleio/AddressType.c +++ b/shared-bindings/bleio/AddressType.c @@ -31,7 +31,7 @@ //| :class:`AddressType` -- defines the type of a BLE address //| ============================================================= //| -//| .. class:: bleio.AddressType +//| .. class:: AddressType() //| //| Enum-like class to define the type of a BLE address, see also `bleio.Address`. //| diff --git a/shared-bindings/bleio/CharacteristicBuffer.c b/shared-bindings/bleio/CharacteristicBuffer.c index c368de3614..3604aeedb3 100644 --- a/shared-bindings/bleio/CharacteristicBuffer.c +++ b/shared-bindings/bleio/CharacteristicBuffer.c @@ -47,7 +47,7 @@ STATIC void raise_error_if_not_connected(bleio_characteristic_buffer_obj_t *self //| //| Accumulates a Characteristic's incoming values in a FIFO buffer. //| -//| .. class:: CharacteristicBuffer(Characteristic, *, timeout=1, buffer_size=64) +//| .. class:: CharacteristicBuffer(characteristic, *, timeout=1, buffer_size=64) //| //| Create a new Characteristic object identified by the specified UUID. //| diff --git a/shared-bindings/bleio/UUID.c b/shared-bindings/bleio/UUID.c index c6ad9e6266..fa2472b48c 100644 --- a/shared-bindings/bleio/UUID.c +++ b/shared-bindings/bleio/UUID.c @@ -47,9 +47,10 @@ //| The value can be one of: //| //| - an `int` value in range 0 to 0xFFFF (Bluetooth SIG 16-bit UUID) -//| - a buffer object (bytearray, bytes) of 16 bytes in little-endian order (128-bit UUID) +//| - a buffer object (bytearray, bytes) of 16 bytes in little-endian order (128-bit UUID) //| -//| :param int/buffer value: The uuid value to encapsulate +//| :param value: The uuid value to encapsulate +//| :type value: int or typing.ByteString //| STATIC mp_obj_t bleio_uuid_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { mp_arg_check_num(n_args, kw_args, 1, 1, false); @@ -124,6 +125,8 @@ STATIC mp_obj_t bleio_uuid_make_new(const mp_obj_type_t *type, size_t n_args, co //| //| The 16-bit part of the UUID. (read-only) //| +//| :type: int +//| STATIC mp_obj_t bleio_uuid_get_uuid16(mp_obj_t self_in) { bleio_uuid_obj_t *self = MP_OBJ_TO_PTR(self_in); return MP_OBJ_NEW_SMALL_INT(common_hal_bleio_uuid_get_uuid16(self)); @@ -140,9 +143,11 @@ const mp_obj_property_t bleio_uuid_uuid16_obj = { //| .. attribute:: uuid128 //| -//| The 128-bit value of the UUID, returned as bytes. +//| The 128-bit value of the UUID //| Raises AttributeError if this is a 16-bit UUID. (read-only) //| +//| :type: bytes +//| STATIC mp_obj_t bleio_uuid_get_uuid128(mp_obj_t self_in) { bleio_uuid_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -164,9 +169,10 @@ const mp_obj_property_t bleio_uuid_uuid128_obj = { //| .. attribute:: size //| -//| Returns 128 if this UUID represents a 128-bit vendor-specific UUID. -//| Returns 16 if this UUID represents a 16-bit Bluetooth SIG assigned UUID. (read-only) -//| 32-bit UUIDs are not currently supported. +//| 128 if this UUID represents a 128-bit vendor-specific UUID. 16 if this UUID represents a +//| 16-bit Bluetooth SIG assigned UUID. (read-only) 32-bit UUIDs are not currently supported. +//| +//| :type: int //| STATIC mp_obj_t bleio_uuid_get_size(mp_obj_t self_in) { bleio_uuid_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/board/__init__.c b/shared-bindings/board/__init__.c index 82a0cab675..b4cc8cb12f 100644 --- a/shared-bindings/board/__init__.c +++ b/shared-bindings/board/__init__.c @@ -42,7 +42,7 @@ //| .. warning:: The board module varies by board. The APIs documented here may or may not be //| available on a specific board. -//| .. method:: I2C() +//| .. function:: I2C() //| //| Returns the `busio.I2C` object for the board designated SDA and SCL pins. It is a singleton. //| @@ -66,7 +66,7 @@ mp_obj_t board_i2c(void) { MP_DEFINE_CONST_FUN_OBJ_0(board_i2c_obj, board_i2c); -//| .. method:: SPI() +//| .. function:: SPI() //| //| Returns the `busio.SPI` object for the board designated SCK, MOSI and MISO pins. It is a //| singleton. @@ -90,7 +90,7 @@ mp_obj_t board_spi(void) { #endif MP_DEFINE_CONST_FUN_OBJ_0(board_spi_obj, board_spi); -//| .. method:: UART() +//| .. function:: UART() //| //| Returns the `busio.UART` object for the board designated TX and RX pins. It is a singleton. //| diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index e17a72b481..1c50c07b02 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -41,7 +41,7 @@ //| :class:`I2C` --- Two wire serial protocol //| ------------------------------------------ //| -//| .. class:: I2C(scl, sda, \*, frequency=400000) +//| .. class:: I2C(scl, sda, *, frequency=400000, timeout=255) //| //| I2C is a two-wire protocol for communicating between devices. At the //| physical level it consists of 2 wires: SCL and SDA, the clock and data @@ -82,7 +82,7 @@ STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, con return (mp_obj_t)self; } -//| .. method:: I2C.deinit() +//| .. method:: deinit() //| //| Releases control of the underlying hardware so other classes can use it. //| @@ -93,13 +93,13 @@ STATIC mp_obj_t busio_i2c_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_deinit_obj, busio_i2c_obj_deinit); -//| .. method:: I2C.__enter__() +//| .. method:: __enter__() //| //| No-op used in Context Managers. //| // Provided by context manager helper. -//| .. method:: I2C.__exit__() +//| .. method:: __exit__() //| //| Automatically deinitializes the hardware on context exit. See //| :ref:`lifetime-and-contextmanagers` for more info. @@ -118,7 +118,7 @@ static void check_lock(busio_i2c_obj_t *self) { } } -//| .. method:: I2C.scan() +//| .. method:: scan() //| //| Scan all I2C addresses between 0x08 and 0x77 inclusive and return a //| list of those that respond. @@ -142,7 +142,7 @@ STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_scan_obj, busio_i2c_scan); -//| .. method:: I2C.try_lock() +//| .. method:: try_lock() //| //| Attempts to grab the I2C lock. Returns True on success. //| @@ -156,7 +156,7 @@ STATIC mp_obj_t busio_i2c_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_try_lock_obj, busio_i2c_obj_try_lock); -//| .. method:: I2C.unlock() +//| .. method:: unlock() //| //| Releases the I2C lock. //| @@ -168,7 +168,7 @@ STATIC mp_obj_t busio_i2c_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_unlock_obj, busio_i2c_obj_unlock); -//| .. method:: I2C.readfrom_into(address, buffer, \*, start=0, end=len(buffer)) +//| .. method:: readfrom_into(address, buffer, *, start=0, end=None) //| //| Read into ``buffer`` from the slave specified by ``address``. //| The number of bytes read will be the length of ``buffer``. @@ -181,7 +181,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_unlock_obj, busio_i2c_obj_unlock); //| :param int address: 7-bit device address //| :param bytearray buffer: buffer to write into //| :param int start: Index to start writing at -//| :param int end: Index to write up to but not include +//| :param int end: Index to write up to but not include. Defaults to ``len(buffer)`` //| STATIC mp_obj_t busio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_address, ARG_buffer, ARG_start, ARG_end }; @@ -216,7 +216,7 @@ STATIC mp_obj_t busio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_args, } MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_readfrom_into_obj, 3, busio_i2c_readfrom_into); -//| .. method:: I2C.writeto(address, buffer, \*, start=0, end=len(buffer), stop=True) +//| .. method:: writeto(address, buffer, *, start=0, end=None, stop=True) //| //| Write the bytes from ``buffer`` to the slave specified by ``address``. //| Transmits a stop bit if ``stop`` is set. @@ -231,7 +231,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_readfrom_into_obj, 3, busio_i2c_readfrom_in //| :param int address: 7-bit device address //| :param bytearray buffer: buffer containing the bytes to write //| :param int start: Index to start writing from -//| :param int end: Index to read up to but not include +//| :param int end: Index to read up to but not include. Defaults to ``len(buffer)`` //| :param bool stop: If true, output an I2C stop condition after the //| buffer is written //| diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index f690eea189..bd788365e4 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -95,7 +95,7 @@ STATIC mp_obj_t busio_spi_make_new(const mp_obj_type_t *type, size_t n_args, con return (mp_obj_t)self; } -//| .. method:: SPI.deinit() +//| .. method:: deinit() //| //| Turn off the SPI bus. //| @@ -106,13 +106,13 @@ STATIC mp_obj_t busio_spi_obj_deinit(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_deinit_obj, busio_spi_obj_deinit); -//| .. method:: SPI.__enter__() +//| .. method:: __enter__() //| //| No-op used by Context Managers. //| // Provided by context manager helper. -//| .. method:: SPI.__exit__() +//| .. method:: __exit__() //| //| Automatically deinitializes the hardware when exiting a context. See //| :ref:`lifetime-and-contextmanagers` for more info. @@ -131,7 +131,7 @@ static void check_lock(busio_spi_obj_t *self) { } } -//| .. method:: SPI.configure(\*, baudrate=100000, polarity=0, phase=0, bits=8) +//| .. method:: configure(*, baudrate=100000, polarity=0, phase=0, bits=8) //| //| Configures the SPI bus. The SPI object must be locked. //| @@ -188,7 +188,7 @@ STATIC mp_obj_t busio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_ } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_configure_obj, 1, busio_spi_configure); -//| .. method:: SPI.try_lock() +//| .. method:: try_lock() //| //| Attempts to grab the SPI lock. Returns True on success. //| @@ -202,7 +202,7 @@ STATIC mp_obj_t busio_spi_obj_try_lock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_try_lock_obj, busio_spi_obj_try_lock); -//| .. method:: SPI.unlock() +//| .. method:: unlock() //| //| Releases the SPI lock. //| @@ -214,14 +214,14 @@ STATIC mp_obj_t busio_spi_obj_unlock(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_unlock_obj, busio_spi_obj_unlock); -//| .. method:: SPI.write(buffer, \*, start=0, end=len(buffer)) +//| .. method:: write(buffer, *, start=0, end=None) //| //| Write the data contained in ``buffer``. The SPI object must be locked. //| If the buffer is empty, nothing happens. //| //| :param bytearray buffer: Write out the data in this buffer //| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included +//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` //| STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end }; @@ -255,7 +255,7 @@ STATIC mp_obj_t busio_spi_write(size_t n_args, const mp_obj_t *pos_args, mp_map_ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 2, busio_spi_write); -//| .. method:: SPI.readinto(buffer, \*, start=0, end=len(buffer), write_value=0) +//| .. method:: readinto(buffer, *, start=0, end=None, write_value=0) //| //| Read into ``buffer`` while writing ``write_value`` for each byte read. //| The SPI object must be locked. @@ -263,7 +263,7 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 2, busio_spi_write); //| //| :param bytearray buffer: Read data into this buffer //| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included +//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` //| :param int write_value: Value to write while reading. (Usually ignored.) //| STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -298,7 +298,7 @@ STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_m } MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 2, busio_spi_readinto); -//| .. method:: SPI.write_readinto(buffer_out, buffer_in, \*, out_start=0, out_end=len(buffer_out), in_start=0, in_end=len(buffer_in)) +//| .. method:: write_readinto(buffer_out, buffer_in, *, out_start=0, out_end=None, in_start=0, in_end=None) //| //| Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. //| The SPI object must be locked. @@ -309,9 +309,9 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 2, busio_spi_readinto); //| :param bytearray buffer_out: Write out the data in this buffer //| :param bytearray buffer_in: Read data into this buffer //| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` -//| :param int out_end: End of the slice; this index is not included +//| :param int out_end: End of the slice; this index is not included. Defaults to ``len(buffer_out)`` //| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` -//| :param int in_end: End of the slice; this index is not included +//| :param int in_end: End of the slice; this index is not included. Defaults to ``len(buffer_in)`` //| STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index 94ad1bd3ed..eeffb62ef2 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -46,7 +46,7 @@ //| ================================================= //| //| -//| .. class:: UART(tx, rx, \*, baudrate=9600, bits=8, parity=None, stop=1, timeout=1, receiver_buffer_size=64) +//| .. class:: UART(tx, rx, *, baudrate=9600, bits=8, parity=None, stop=1, timeout=1, receiver_buffer_size=64) //| //| A common bidirectional serial protocol that uses an an agreed upon speed //| rather than a shared clock line. @@ -292,7 +292,7 @@ STATIC mp_obj_t busio_uart_obj_reset_input_buffer(mp_obj_t self_in) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_uart_reset_input_buffer_obj, busio_uart_obj_reset_input_buffer); -//| .. class:: busio.UART.Parity +//| .. class:: busio.UART.Parity() //| //| Enum-like class to define the parity used to verify correct data transfer. //| diff --git a/shared-bindings/displayio/TileGrid.c b/shared-bindings/displayio/TileGrid.c index 6d18ac78f1..10bed4c776 100644 --- a/shared-bindings/displayio/TileGrid.c +++ b/shared-bindings/displayio/TileGrid.c @@ -64,7 +64,7 @@ //| :param int height: Height of the grid in tiles. //| :param int tile_width: Width of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions. //| :param int tile_height: Height of a single tile in pixels. Defaults to the full Bitmap and must evenly divide into the Bitmap's dimensions. -//| :param in default_tile: Default tile index to show. +//| :param int default_tile: Default tile index to show. //| :param int x: Initial x position of the left edge within the parent. //| :param int y: Initial y position of the top edge within the parent. //| diff --git a/shared-bindings/displayio/__init__.c b/shared-bindings/displayio/__init__.c index 44b1e0b079..9dc17103b4 100644 --- a/shared-bindings/displayio/__init__.c +++ b/shared-bindings/displayio/__init__.c @@ -69,7 +69,7 @@ //| -//| .. method:: release_displays() +//| .. function:: release_displays() //| //| Releases any actively used displays so their busses and pins can be used again. This will also //| release the builtin display on boards that have one. You will need to reinitialize it yourself diff --git a/shared-bindings/help.c b/shared-bindings/help.c index e0770ff3ce..4e7c3a78bb 100644 --- a/shared-bindings/help.c +++ b/shared-bindings/help.c @@ -27,7 +27,7 @@ //| :func:`help` - Built-in method to provide helpful information //| ============================================================== //| -//| .. method:: help(object=None) +//| .. function:: help(object=None) //| //| Prints a help method about the given object. When ``object`` is none, //| prints general port information. diff --git a/shared-bindings/microcontroller/Pin.c b/shared-bindings/microcontroller/Pin.c index e796631070..3635f0afbd 100644 --- a/shared-bindings/microcontroller/Pin.c +++ b/shared-bindings/microcontroller/Pin.c @@ -40,7 +40,7 @@ //| //| Identifies an IO pin on the microcontroller. //| -//| .. class:: Pin +//| .. class:: Pin() //| //| Identifies an IO pin on the microcontroller. They are fixed by the //| hardware so they cannot be constructed on demand. Instead, use diff --git a/shared-bindings/microcontroller/RunMode.c b/shared-bindings/microcontroller/RunMode.c index 7c3f84fcac..913242ad26 100644 --- a/shared-bindings/microcontroller/RunMode.c +++ b/shared-bindings/microcontroller/RunMode.c @@ -31,24 +31,30 @@ //| :class:`RunMode` -- run state of the microcontroller //| ============================================================= //| -//| .. class:: microcontroller.RunMode +//| .. class:: RunMode() //| //| Enum-like class to define the run mode of the microcontroller and //| CircuitPython. //| -//| .. data:: NORMAL +//| .. attribute:: NORMAL //| //| Run CircuitPython as normal. //| -//| .. data:: SAFE_MODE +//| :type microcontroller.RunMode: +//| +//| .. attribute:: SAFE_MODE //| //| Run CircuitPython in safe mode. User code will not be run and the //| file system will be writeable over USB. //| -//| .. data:: BOOTLOADER +//| :type microcontroller.RunMode: +//| +//| .. attribute:: BOOTLOADER //| //| Run the bootloader. //| +//| :type microcontroller.RunMode: +//| const mp_obj_type_t mcu_runmode_type; const mcu_runmode_obj_t mcu_runmode_normal_obj = { diff --git a/shared-bindings/microcontroller/__init__.c b/shared-bindings/microcontroller/__init__.c index da8d0bd940..090c4564da 100644 --- a/shared-bindings/microcontroller/__init__.c +++ b/shared-bindings/microcontroller/__init__.c @@ -62,14 +62,14 @@ //| RunMode //| -//| .. attribute:: cpu +//| .. data:: cpu //| //| CPU information and control, such as ``cpu.temperature`` and ``cpu.frequency`` //| (clock frequency). //| This object is the sole instance of `microcontroller.Processor`. //| -//| .. method:: delay_us(delay) +//| .. function:: delay_us(delay) //| //| Dedicated delay method used for very short delays. **Do not** do long delays //| because this stops all other functions from completing. Think of this as an empty @@ -87,7 +87,7 @@ STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_delay_us_obj, mcu_delay_us); -//| .. method:: disable_interrupts() +//| .. function:: disable_interrupts() //| //| Disable all interrupts. Be very careful, this can stall everything. //| @@ -97,7 +97,7 @@ STATIC mp_obj_t mcu_disable_interrupts(void) { } STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_disable_interrupts_obj, mcu_disable_interrupts); -//| .. method:: enable_interrupts() +//| .. function:: enable_interrupts() //| //| Enable the interrupts that were enabled at the last disable. //| @@ -107,7 +107,7 @@ STATIC mp_obj_t mcu_enable_interrupts(void) { } STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_enable_interrupts_obj, mcu_enable_interrupts); -//| .. method:: on_next_reset(run_mode) +//| .. function:: on_next_reset(run_mode) //| //| Configure the run mode used the next time the microcontroller is reset but //| not powered down. @@ -132,7 +132,7 @@ STATIC mp_obj_t mcu_on_next_reset(mp_obj_t run_mode_obj) { } STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_on_next_reset_obj, mcu_on_next_reset); -//| .. method:: reset() +//| .. function:: reset() //| //| Reset the microcontroller. After reset, the microcontroller will enter the //| run mode last set by `on_next_reset`. @@ -148,11 +148,13 @@ STATIC mp_obj_t mcu_reset(void) { } STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_reset_obj, mcu_reset); -//| .. attribute:: nvm +//| .. data:: nvm //| //| Available non-volatile memory. //| This object is the sole instance of `nvm.ByteArray` when available or ``None`` otherwise. //| +//| :type: nvm.ByteArray or None +//| //| :mod:`microcontroller.pin` --- Microcontroller pin names //| -------------------------------------------------------- diff --git a/shared-bindings/neopixel_write/__init__.c b/shared-bindings/neopixel_write/__init__.c index 05d6fd97ae..1ee66337bb 100644 --- a/shared-bindings/neopixel_write/__init__.c +++ b/shared-bindings/neopixel_write/__init__.c @@ -55,11 +55,11 @@ //| pixel_off = bytearray([0, 0, 0]) //| neopixel_write.neopixel_write(pin, pixel_off) //| -//| .. method:: neopixel_write.neopixel_write(digitalinout, buf) +//| .. function:: neopixel_write(digitalinout, buf) //| //| Write buf out on the given DigitalInOut. //| -//| :param ~digitalio.DigitalInOut gpio: the DigitalInOut to output with +//| :param ~digitalio.DigitalInOut digitalinout: the DigitalInOut to output with //| :param bytearray buf: The bytes to clock out. No assumption is made about color order //| STATIC mp_obj_t neopixel_write_neopixel_write_(mp_obj_t digitalinout_obj, mp_obj_t buf) { diff --git a/shared-bindings/network/__init__.c b/shared-bindings/network/__init__.c index 1067ea5497..01763a73c5 100644 --- a/shared-bindings/network/__init__.c +++ b/shared-bindings/network/__init__.c @@ -49,7 +49,7 @@ //| It is used by the 'socket' module to look up a suitable //| NIC when a socket is created. //| -//| .. function:: route +//| .. function:: route() //| //| Returns a list of all configured NICs. //| diff --git a/shared-bindings/pulseio/PWMOut.c b/shared-bindings/pulseio/PWMOut.c index 37939a07ab..a7a90fb0d6 100644 --- a/shared-bindings/pulseio/PWMOut.c +++ b/shared-bindings/pulseio/PWMOut.c @@ -42,7 +42,7 @@ //| //| PWMOut can be used to output a PWM signal on a given pin. //| -//| .. class:: PWMOut(pin, \*, duty_cycle=0, frequency=500, variable_frequency=False) +//| .. class:: PWMOut(pin, *, duty_cycle=0, frequency=500, variable_frequency=False) //| //| Create a PWM object associated with the given pin. This allows you to //| write PWM signals out on the given pin. Frequency is fixed after init diff --git a/shared-bindings/pulseio/PulseIn.c b/shared-bindings/pulseio/PulseIn.c index 426ac4384e..9f37c65c9c 100644 --- a/shared-bindings/pulseio/PulseIn.c +++ b/shared-bindings/pulseio/PulseIn.c @@ -45,7 +45,7 @@ //| The pulsed signal consists of timed active and idle periods. Unlike PWM, //| there is no set duration for active and idle pairs. //| -//| .. class:: PulseIn(pin, maxlen=2, \*, idle_state=False) +//| .. class:: PulseIn(pin, maxlen=2, *, idle_state=False) //| //| Create a PulseIn object associated with the given pin. The object acts as //| a read-only sequence of pulse lengths with a given max length. When it is diff --git a/shared-bindings/socket/__init__.c b/shared-bindings/socket/__init__.c index 085d4e6906..6d04a98936 100644 --- a/shared-bindings/socket/__init__.c +++ b/shared-bindings/socket/__init__.c @@ -51,7 +51,7 @@ STATIC const mp_obj_type_t socket_type; //| .. currentmodule:: socket //| -//| .. class:: socket(family, type, proto, ...) +//| .. class:: socket(family, type, proto) //| //| Create a new socket //| diff --git a/shared-bindings/storage/__init__.c b/shared-bindings/storage/__init__.c index 4db3a9feca..ba439b951c 100644 --- a/shared-bindings/storage/__init__.c +++ b/shared-bindings/storage/__init__.c @@ -48,7 +48,7 @@ //| directly. //| -//| .. function:: mount(filesystem, mount_path, \*, readonly=False) +//| .. function:: mount(filesystem, mount_path, *, readonly=False) //| //| Mounts the given filesystem object at the given path. //| @@ -183,7 +183,7 @@ STATIC const mp_rom_map_elem_t storage_module_globals_table[] = { //| this property can only be set when the device is writable by the //| microcontroller. //| - //| .. method:: mkfs + //| .. method:: mkfs() //| //| Format the block device, deleting any data that may have been there //| @@ -216,7 +216,7 @@ STATIC const mp_rom_map_elem_t storage_module_globals_table[] = { //| //| Don't call this directly, call `storage.mount`. //| - //| .. method:: umount + //| .. method:: umount() //| //| Don't call this directly, call `storage.umount`. //| diff --git a/shared-bindings/struct/__init__.c b/shared-bindings/struct/__init__.c index 9240a15bb1..ea14b37637 100644 --- a/shared-bindings/struct/__init__.c +++ b/shared-bindings/struct/__init__.c @@ -67,9 +67,9 @@ STATIC mp_obj_t struct_calcsize(mp_obj_t fmt_in) { } MP_DEFINE_CONST_FUN_OBJ_1(struct_calcsize_obj, struct_calcsize); -//| .. function:: pack(fmt, v1, v2, ...) +//| .. function:: pack(fmt, *values) //| -//| Pack the values v1, v2, ... according to the format string fmt. +//| Pack the values according to the format string fmt. //| The return value is a bytes object encoding the values. //| @@ -85,9 +85,9 @@ STATIC mp_obj_t struct_pack(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(struct_pack_obj, 1, MP_OBJ_FUN_ARGS_MAX, struct_pack); -//| .. function:: pack_into(fmt, buffer, offset, v1, v2, ...) +//| .. function:: pack_into(fmt, buffer, offset, *values) //| -//| Pack the values v1, v2, ... according to the format string fmt into a buffer +//| Pack the values according to the format string fmt into a buffer //| starting at offset. offset may be negative to count from the end of buffer. //| diff --git a/shared-bindings/time/__init__.c b/shared-bindings/time/__init__.c index 3babe2db4b..70c01c2d83 100644 --- a/shared-bindings/time/__init__.c +++ b/shared-bindings/time/__init__.c @@ -47,7 +47,7 @@ //| written in MicroPython will work in CPython but not necessarily the other //| way around. //| -//| .. method:: monotonic() +//| .. function:: monotonic() //| //| Returns an always increasing value of time with an unknown reference //| point. Only use it to compare against other values from `monotonic`. @@ -62,7 +62,7 @@ STATIC mp_obj_t time_monotonic(void) { } MP_DEFINE_CONST_FUN_OBJ_0(time_monotonic_obj, time_monotonic); -//| .. method:: sleep(seconds) +//| .. function:: sleep(seconds) //| //| Sleep for a given number of seconds. //| @@ -95,19 +95,20 @@ mp_obj_t struct_time_make_new(const mp_obj_type_t *type, size_t n_args, const mp return namedtuple_make_new(type, 9, tuple->items, NULL); } -//| .. class:: struct_time((tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst)) +//| .. class:: struct_time(time_tuple) //| //| Structure used to capture a date and time. Note that it takes a tuple! //| -//| :param int tm_year: the year, 2017 for example -//| :param int tm_mon: the month, range [1, 12] -//| :param int tm_mday: the day of the month, range [1, 31] -//| :param int tm_hour: the hour, range [0, 23] -//| :param int tm_min: the minute, range [0, 59] -//| :param int tm_sec: the second, range [0, 61] -//| :param int tm_wday: the day of the week, range [0, 6], Monday is 0 -//| :param int tm_yday: the day of the year, range [1, 366], -1 indicates not known -//| :param int tm_isdst: 1 when in daylight savings, 0 when not, -1 if unknown. +//| :param Tuple[tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst] time_tuple: Tuple of time info. +//| * the year, 2017 for example +//| * the month, range [1, 12] +//| * the day of the month, range [1, 31] +//| * the hour, range [0, 23] +//| * the minute, range [0, 59] +//| * the second, range [0, 61] +//| * the day of the week, range [0, 6], Monday is 0 +//| * the day of the year, range [1, 366], -1 indicates not known +//| * 1 when in daylight savings, 0 when not, -1 if unknown. //| const mp_obj_namedtuple_type_t struct_time_type_obj = { .base = { @@ -190,7 +191,7 @@ mp_obj_t MP_WEAK rtc_get_time_source_time(void) { mp_raise_RuntimeError(translate("RTC is not supported on this board")); } -//| .. method:: time() +//| .. function:: time() //| //| Return the current time in seconds since since Jan 1, 1970. //| @@ -206,7 +207,7 @@ STATIC mp_obj_t time_time(void) { } MP_DEFINE_CONST_FUN_OBJ_0(time_time_obj, time_time); -//| .. method:: monotonic_ns() +//| .. function:: monotonic_ns() //| //| Return the time of the specified clock clk_id in nanoseconds. //| @@ -219,7 +220,7 @@ STATIC mp_obj_t time_monotonic_ns(void) { } MP_DEFINE_CONST_FUN_OBJ_0(time_monotonic_ns_obj, time_monotonic_ns); -//| .. method:: localtime([secs]) +//| .. function:: localtime([secs]) //| //| Convert a time expressed in seconds since Jan 1, 1970 to a struct_time in //| local time. If secs is not provided or None, the current time as returned @@ -245,7 +246,7 @@ STATIC mp_obj_t time_localtime(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(time_localtime_obj, 0, 1, time_localtime); -//| .. method:: mktime(t) +//| .. function:: mktime(t) //| //| This is the inverse function of localtime(). Its argument is the //| struct_time or full 9-tuple (since the dst flag is needed; use -1 as the diff --git a/shared-bindings/uheap/__init__.c b/shared-bindings/uheap/__init__.c index df18237acc..0d699cd282 100644 --- a/shared-bindings/uheap/__init__.c +++ b/shared-bindings/uheap/__init__.c @@ -38,7 +38,7 @@ //| :synopsis: Heap size analysis //| -//| .. method:: info(object) +//| .. function:: info(object) //| //| Prints memory debugging info for the given object and returns the //| estimated size. diff --git a/shared-bindings/ustack/__init__.c b/shared-bindings/ustack/__init__.c index c4391c1323..08b772e41e 100644 --- a/shared-bindings/ustack/__init__.c +++ b/shared-bindings/ustack/__init__.c @@ -39,7 +39,7 @@ //| #if MICROPY_MAX_STACK_USAGE -//| .. method:: max_stack_usage() +//| .. function:: max_stack_usage() //| //| Return the maximum excursion of the stack so far. //| @@ -50,7 +50,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_0(max_stack_usage_obj, max_stack_usage); #endif // MICROPY_MAX_STACK_USAGE -//| .. method:: stack_size() +//| .. function:: stack_size() //| //| Return the size of the entire stack. //| Same as in micropython.mem_info(), but returns a value instead @@ -61,7 +61,7 @@ STATIC mp_obj_t stack_size(void) { } STATIC MP_DEFINE_CONST_FUN_OBJ_0(stack_size_obj, stack_size); -//| .. method:: stack_usage() +//| .. function:: stack_usage() //| //| Return how much stack is currently in use. //| Same as micropython.stack_use(); duplicated here for convenience. diff --git a/shared-bindings/wiznet/wiznet5k.c b/shared-bindings/wiznet/wiznet5k.c index 878095b2aa..ac89cc691e 100644 --- a/shared-bindings/wiznet/wiznet5k.c +++ b/shared-bindings/wiznet/wiznet5k.c @@ -138,7 +138,7 @@ const mp_obj_property_t wiznet5k_dhcp_obj = { (mp_obj_t)&mp_const_none_obj}, }; -//| .. method:: ifconfig(...) +//| .. method:: ifconfig(params=None) //| //| Called without parameters, returns a tuple of //| (ip_address, subnet_mask, gateway_address, dns_server)