From 4aaa0ea00864dea835161b96a75c15e8c5242744 Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Tue, 7 Mar 2017 12:58:57 +0100 Subject: [PATCH] shared-bindings: Do a pass on the docs and make sure keyword only arguments make sense and are documented correctly. Fixes #109 --- shared-bindings/bitbangio/I2C.c | 2 +- shared-bindings/bitbangio/SPI.c | 13 +++++++++++-- shared-bindings/help.c | 2 +- shared-bindings/nativeio/DigitalInOut.c | 8 ++++---- shared-bindings/nativeio/I2C.c | 5 ++++- shared-bindings/nativeio/PWMOut.c | 8 ++++---- shared-bindings/nativeio/SPI.c | 13 +++++++++++-- shared-bindings/nativeio/TouchIn.c | 2 +- shared-bindings/nativeio/UART.c | 4 ++-- shared-bindings/neopixel_write/__init__.c | 4 ++-- 10 files changed, 41 insertions(+), 20 deletions(-) diff --git a/shared-bindings/bitbangio/I2C.c b/shared-bindings/bitbangio/I2C.c index e5c9831b5d..e8153f392b 100644 --- a/shared-bindings/bitbangio/I2C.c +++ b/shared-bindings/bitbangio/I2C.c @@ -38,7 +38,7 @@ //| :class:`I2C` --- Two wire serial protocol //| ------------------------------------------ //| -//| .. class:: I2C(scl, sda, \* frequency=400000) +//| .. class:: I2C(scl, sda, \*, frequency=400000) //| //| 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 diff --git a/shared-bindings/bitbangio/SPI.c b/shared-bindings/bitbangio/SPI.c index 8ce41696ca..c973403f0c 100644 --- a/shared-bindings/bitbangio/SPI.c +++ b/shared-bindings/bitbangio/SPI.c @@ -49,7 +49,7 @@ //| select line. (This is common because multiple slaves can share the `!clock`, //| `!MOSI` and `!MISO` lines and therefore the hardware.) //| -//| .. class:: SPI(clock, MOSI, MISO) +//| .. class:: SPI(clock, MOSI=None, MISO=None) //| //| Construct an SPI object on the given pins. //| @@ -118,10 +118,16 @@ static void check_lock(bitbangio_spi_obj_t *self) { } } -//| .. method:: SPI.configure(baudrate=100000) +//| .. method:: SPI.configure(\*, baudrate=100000, polarity=0, phase=0, bits=8) //| //| Configures the SPI bus. Only valid when locked. //| +//| :param int baudrate: the clock rate in Hertz +//| :param int polarity: the base state of the clock line (0 or 1) +//| :param int phase: the edge of the clock that data is captured. First (0) +//| or second (1). Rising or falling depends on clock polarity. +//| :param int bits: the number of bits per word +//| STATIC mp_obj_t bitbangio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_baudrate, ARG_polarity, ARG_phase, ARG_bits }; static const mp_arg_t allowed_args[] = { @@ -157,6 +163,9 @@ MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_spi_configure_obj, 1, bitbangio_spi_configu //| //| Attempts to grab the SPI lock. Returns True on success. //| +//| :return: True when lock has been grabbed +//| :rtype: bool +//| STATIC mp_obj_t bitbangio_spi_obj_try_lock(mp_obj_t self_in) { return mp_obj_new_bool(shared_module_bitbangio_spi_try_lock(MP_OBJ_TO_PTR(self_in))); } diff --git a/shared-bindings/help.c b/shared-bindings/help.c index ef819a366b..1230fb04fe 100644 --- a/shared-bindings/help.c +++ b/shared-bindings/help.c @@ -28,7 +28,7 @@ #include "shared-bindings/help.h" //| :func:`help` - Built-in method to provide helpful information -//| ======================================================== +//| ============================================================== //| //| .. method:: help(object=None) //| diff --git a/shared-bindings/nativeio/DigitalInOut.c b/shared-bindings/nativeio/DigitalInOut.c index 67c6a93803..421e142771 100644 --- a/shared-bindings/nativeio/DigitalInOut.c +++ b/shared-bindings/nativeio/DigitalInOut.c @@ -116,8 +116,8 @@ extern const nativeio_digitalinout_drive_mode_obj_t nativeio_digitalinout_drive_ STATIC mp_obj_t nativeio_digitalinout_switch_to_output(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_value, ARG_drive_mode }; static const mp_arg_t allowed_args[] = { - { MP_QSTR_value, MP_ARG_KW_ONLY | MP_ARG_BOOL, {.u_bool = false} }, - { MP_QSTR_drive_mode, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_rom_obj = &nativeio_digitalinout_drive_mode_push_pull_obj} }, + { MP_QSTR_value, MP_ARG_BOOL, {.u_bool = false} }, + { MP_QSTR_drive_mode, MP_ARG_OBJ, {.u_rom_obj = &nativeio_digitalinout_drive_mode_push_pull_obj} }, }; nativeio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; @@ -159,7 +159,7 @@ extern const nativeio_digitalinout_pull_obj_t nativeio_digitalinout_pull_down_ob STATIC mp_obj_t nativeio_digitalinout_switch_to_input(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_pull }; static const mp_arg_t allowed_args[] = { - { MP_QSTR_pull, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_rom_obj = mp_const_none} }, + { MP_QSTR_pull, MP_ARG_OBJ, {.u_rom_obj = mp_const_none} }, }; nativeio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; @@ -279,7 +279,7 @@ const mp_obj_property_t nativeio_digitalinout_drive_mode_obj = { //| //| Get or set the pin pull. //| -//| :raises AttributeError: if the direction is `out`. +//| :raises AttributeError: if the direction is ~`Direction.OUT`. //| STATIC mp_obj_t nativeio_digitalinout_obj_get_pull(mp_obj_t self_in) { nativeio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); diff --git a/shared-bindings/nativeio/I2C.c b/shared-bindings/nativeio/I2C.c index 4b0f9a6402..fe3e206b29 100644 --- a/shared-bindings/nativeio/I2C.c +++ b/shared-bindings/nativeio/I2C.c @@ -53,7 +53,7 @@ //| //| :param ~microcontroller.Pin scl: The clock pin //| :param ~microcontroller.Pin sda: The data pin -//| :param int frequency: The clock frequency +//| :param int frequency: The clock frequency in Hertz //| STATIC mp_obj_t nativeio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) { mp_arg_check_num(n_args, n_kw, 0, MP_OBJ_FUN_ARGS_MAX, true); @@ -140,6 +140,9 @@ MP_DEFINE_CONST_FUN_OBJ_1(nativeio_i2c_scan_obj, nativeio_i2c_scan); //| //| Attempts to grab the I2C lock. Returns True on success. //| +//| :return: True when lock has been grabbed +//| :rtype: bool +//| STATIC mp_obj_t nativeio_i2c_obj_try_lock(mp_obj_t self_in) { return mp_obj_new_bool(common_hal_nativeio_i2c_try_lock(MP_OBJ_TO_PTR(self_in))); } diff --git a/shared-bindings/nativeio/PWMOut.c b/shared-bindings/nativeio/PWMOut.c index 4db811e1d3..ff45a22b2c 100644 --- a/shared-bindings/nativeio/PWMOut.c +++ b/shared-bindings/nativeio/PWMOut.c @@ -39,11 +39,11 @@ //| //| 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 -//| unless `variable_frequency` is True. +//| unless ``variable_frequency`` is True. //| //| .. note:: When ``variable_frequency`` is True, further PWM outputs may be //| limited because it may take more internal resources to be flexible. So, @@ -143,8 +143,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(nativeio_pwmout___exit___obj, 4, 4, n //| .. attribute:: duty_cycle //| //| 16 bit value that dictates how much of one cycle is high (1) versus low -//| (0). 255 will always be high, 0 will always be low and 127 will be half -//| high and then half low. +//| (0). 0xffff will always be high, 0 will always be low and 0x7fff will +//| be half high and then half low. STATIC mp_obj_t nativeio_pwmout_obj_get_duty_cycle(mp_obj_t self_in) { nativeio_pwmout_obj_t *self = MP_OBJ_TO_PTR(self_in); return MP_OBJ_NEW_SMALL_INT(common_hal_nativeio_pwmout_get_duty_cycle(self)); diff --git a/shared-bindings/nativeio/SPI.c b/shared-bindings/nativeio/SPI.c index be19880b5d..8d545a127b 100644 --- a/shared-bindings/nativeio/SPI.c +++ b/shared-bindings/nativeio/SPI.c @@ -50,7 +50,7 @@ //| select line. (This is common because multiple slaves can share the `!clock`, //| `!MOSI` and `!MISO` lines and therefore the hardware.) //| -//| .. class:: SPI(clock, MOSI, MISO) +//| .. class:: SPI(clock, MOSI=None, MISO=None) //| //| Construct an SPI object on the given pins. //| @@ -129,10 +129,16 @@ static void check_lock(nativeio_spi_obj_t *self) { } } -//| .. method:: SPI.configure(baudrate=100000) +//| .. method:: SPI.configure(\*, baudrate=100000, polarity=0, phase=0, bits=8) //| //| Configures the SPI bus. Only valid when locked. //| +//| :param int baudrate: the clock rate in Hertz +//| :param int polarity: the base state of the clock line (0 or 1) +//| :param int phase: the edge of the clock that data is captured. First (0) +//| or second (1). Rising or falling depends on clock polarity. +//| :param int bits: the number of bits per word +//| STATIC mp_obj_t nativeio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_baudrate, ARG_polarity, ARG_phase, ARG_bits }; static const mp_arg_t allowed_args[] = { @@ -171,6 +177,9 @@ MP_DEFINE_CONST_FUN_OBJ_KW(nativeio_spi_configure_obj, 1, nativeio_spi_configure //| //| Attempts to grab the SPI lock. Returns True on success. //| +//| :return: True when lock has been grabbed +//| :rtype: bool +//| STATIC mp_obj_t nativeio_spi_obj_try_lock(mp_obj_t self_in) { return mp_obj_new_bool(common_hal_nativeio_spi_try_lock(MP_OBJ_TO_PTR(self_in))); } diff --git a/shared-bindings/nativeio/TouchIn.c b/shared-bindings/nativeio/TouchIn.c index b0b5f46e21..7b391499c6 100644 --- a/shared-bindings/nativeio/TouchIn.c +++ b/shared-bindings/nativeio/TouchIn.c @@ -38,7 +38,7 @@ //| .. currentmodule:: nativeio //| //| :class:`TouchIn` -- Read the state of a capacitive touch sensor -//| ============================================ +//| =================================================================== //| //| Usage:: //| diff --git a/shared-bindings/nativeio/UART.c b/shared-bindings/nativeio/UART.c index b4942b72f0..c561305938 100644 --- a/shared-bindings/nativeio/UART.c +++ b/shared-bindings/nativeio/UART.c @@ -143,7 +143,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(nativeio_uart___exit___obj, 4, 4, nat // These are standard stream methods. Code is in py/stream.c. // -//| .. method:: read([nbytes]) +//| .. method:: read(nbytes=None) //| //| Read characters. If ``nbytes`` is specified then read at most that many //| bytes. Otherwise, read everything that has been buffered. @@ -151,7 +151,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(nativeio_uart___exit___obj, 4, 4, nat //| :return: Data read //| :rtype: bytes or None //| -//| .. method:: readinto(buf[, nbytes]) +//| .. method:: readinto(buf, nbytes=None) //| //| Read bytes into the ``buf``. If ``nbytes`` is specified then read at most //| that many bytes. Otherwise, read at most ``len(buf)`` bytes. diff --git a/shared-bindings/neopixel_write/__init__.c b/shared-bindings/neopixel_write/__init__.c index 703534b3f3..b0490e1ae4 100644 --- a/shared-bindings/neopixel_write/__init__.c +++ b/shared-bindings/neopixel_write/__init__.c @@ -42,8 +42,8 @@ //| //| The `neopixel_write` module contains a helper method to write out bytes in //| the 800khz neopixel protocol. - -//| .. method:: neopixel_write.neopixel_write(digitalinout, buf, is800KHz) +//| +//| .. method:: neopixel_write.neopixel_write(digitalinout, buf) //| //| Write buf out on the given DigitalInOut. //|