Skip to content

Commit 4aaa0ea

Browse files
tannewttannewt
committed
shared-bindings: Do a pass on the docs and make sure keyword only arguments make sense and are documented correctly. Fixes adafruit#109 
1 parent 3891dde commit 4aaa0ea

10 files changed

Lines changed: 41 additions & 20 deletions

File tree

‎shared-bindings/bitbangio/I2C.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
//| :class:`I2C` --- Two wire serial protocol
3939
//| ------------------------------------------
4040
//|
41-
//| .. class:: I2C(scl, sda, \* frequency=400000)
41+
//| .. class:: I2C(scl, sda, \*, frequency=400000)
4242
//|
4343
//| I2C is a two-wire protocol for communicating between devices. At the
4444
//| physical level it consists of 2 wires: SCL and SDA, the clock and data

‎shared-bindings/bitbangio/SPI.c‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@
4949
//| select line. (This is common because multiple slaves can share the `!clock`,
5050
//| `!MOSI` and `!MISO` lines and therefore the hardware.)
5151
//|
52-
//| .. class:: SPI(clock, MOSI, MISO)
52+
//| .. class:: SPI(clock, MOSI=None, MISO=None)
5353
//|
5454
//| Construct an SPI object on the given pins.
5555
//|
@@ -118,10 +118,16 @@ static void check_lock(bitbangio_spi_obj_t *self) {
118118
}
119119
}
120120

121-
//| .. method:: SPI.configure(baudrate=100000)
121+
//| .. method:: SPI.configure(\*, baudrate=100000, polarity=0, phase=0, bits=8)
122122
//|
123123
//| Configures the SPI bus. Only valid when locked.
124124
//|
125+
//| :param int baudrate: the clock rate in Hertz
126+
//| :param int polarity: the base state of the clock line (0 or 1)
127+
//| :param int phase: the edge of the clock that data is captured. First (0)
128+
//| or second (1). Rising or falling depends on clock polarity.
129+
//| :param int bits: the number of bits per word
130+
//|
125131
STATIC mp_obj_t bitbangio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
126132
enum { ARG_baudrate, ARG_polarity, ARG_phase, ARG_bits };
127133
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
157163
//|
158164
//| Attempts to grab the SPI lock. Returns True on success.
159165
//|
166+
//| :return: True when lock has been grabbed
167+
//| :rtype: bool
168+
//|
160169
STATIC mp_obj_t bitbangio_spi_obj_try_lock(mp_obj_t self_in) {
161170
return mp_obj_new_bool(shared_module_bitbangio_spi_try_lock(MP_OBJ_TO_PTR(self_in)));
162171
}

‎shared-bindings/help.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
#include "shared-bindings/help.h"
2929

3030
//| :func:`help` - Built-in method to provide helpful information
31-
//| ========================================================
31+
//| ==============================================================
3232
//|
3333
//| .. method:: help(object=None)
3434
//|

‎shared-bindings/nativeio/DigitalInOut.c‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -116,8 +116,8 @@ extern const nativeio_digitalinout_drive_mode_obj_t nativeio_digitalinout_drive_
116116
STATIC mp_obj_t nativeio_digitalinout_switch_to_output(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
117117
enum { ARG_value, ARG_drive_mode };
118118
static const mp_arg_t allowed_args[] = {
119-
{ MP_QSTR_value, MP_ARG_KW_ONLY | MP_ARG_BOOL, {.u_bool = false} },
120-
{ MP_QSTR_drive_mode, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_rom_obj = &nativeio_digitalinout_drive_mode_push_pull_obj} },
119+
{ MP_QSTR_value, MP_ARG_BOOL, {.u_bool = false} },
120+
{ MP_QSTR_drive_mode, MP_ARG_OBJ, {.u_rom_obj = &nativeio_digitalinout_drive_mode_push_pull_obj} },
121121
};
122122
nativeio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
123123
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
159159
STATIC mp_obj_t nativeio_digitalinout_switch_to_input(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
160160
enum { ARG_pull };
161161
static const mp_arg_t allowed_args[] = {
162-
{ MP_QSTR_pull, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_rom_obj = mp_const_none} },
162+
{ MP_QSTR_pull, MP_ARG_OBJ, {.u_rom_obj = mp_const_none} },
163163
};
164164
nativeio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
165165
mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
@@ -279,7 +279,7 @@ const mp_obj_property_t nativeio_digitalinout_drive_mode_obj = {
279279
//|
280280
//| Get or set the pin pull.
281281
//|
282-
//| :raises AttributeError: if the direction is `out`.
282+
//| :raises AttributeError: if the direction is ~`Direction.OUT`.
283283
//|
284284
STATIC mp_obj_t nativeio_digitalinout_obj_get_pull(mp_obj_t self_in) {
285285
nativeio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);

‎shared-bindings/nativeio/I2C.c‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@
5353
//|
5454
//| :param ~microcontroller.Pin scl: The clock pin
5555
//| :param ~microcontroller.Pin sda: The data pin
56-
//| :param int frequency: The clock frequency
56+
//| :param int frequency: The clock frequency in Hertz
5757
//|
5858
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) {
5959
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);
140140
//|
141141
//| Attempts to grab the I2C lock. Returns True on success.
142142
//|
143+
//| :return: True when lock has been grabbed
144+
//| :rtype: bool
145+
//|
143146
STATIC mp_obj_t nativeio_i2c_obj_try_lock(mp_obj_t self_in) {
144147
return mp_obj_new_bool(common_hal_nativeio_i2c_try_lock(MP_OBJ_TO_PTR(self_in)));
145148
}

‎shared-bindings/nativeio/PWMOut.c‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,11 +39,11 @@
3939
//|
4040
//| PWMOut can be used to output a PWM signal on a given pin.
4141
//|
42-
//| .. class:: PWMOut(pin, duty_cycle=0, frequency=500, variable_frequency=False)
42+
//| .. class:: PWMOut(pin, \*, duty_cycle=0, frequency=500, variable_frequency=False)
4343
//|
4444
//| Create a PWM object associated with the given pin. This allows you to
4545
//| write PWM signals out on the given pin. Frequency is fixed after init
46-
//| unless `variable_frequency` is True.
46+
//| unless ``variable_frequency`` is True.
4747
//|
4848
//| .. note:: When ``variable_frequency`` is True, further PWM outputs may be
4949
//| 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
143143
//| .. attribute:: duty_cycle
144144
//|
145145
//| 16 bit value that dictates how much of one cycle is high (1) versus low
146-
//| (0). 255 will always be high, 0 will always be low and 127 will be half
147-
//| high and then half low.
146+
//| (0). 0xffff will always be high, 0 will always be low and 0x7fff will
147+
//| be half high and then half low.
148148
STATIC mp_obj_t nativeio_pwmout_obj_get_duty_cycle(mp_obj_t self_in) {
149149
nativeio_pwmout_obj_t *self = MP_OBJ_TO_PTR(self_in);
150150
return MP_OBJ_NEW_SMALL_INT(common_hal_nativeio_pwmout_get_duty_cycle(self));

‎shared-bindings/nativeio/SPI.c‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@
5050
//| select line. (This is common because multiple slaves can share the `!clock`,
5151
//| `!MOSI` and `!MISO` lines and therefore the hardware.)
5252
//|
53-
//| .. class:: SPI(clock, MOSI, MISO)
53+
//| .. class:: SPI(clock, MOSI=None, MISO=None)
5454
//|
5555
//| Construct an SPI object on the given pins.
5656
//|
@@ -129,10 +129,16 @@ static void check_lock(nativeio_spi_obj_t *self) {
129129
}
130130
}
131131

132-
//| .. method:: SPI.configure(baudrate=100000)
132+
//| .. method:: SPI.configure(\*, baudrate=100000, polarity=0, phase=0, bits=8)
133133
//|
134134
//| Configures the SPI bus. Only valid when locked.
135135
//|
136+
//| :param int baudrate: the clock rate in Hertz
137+
//| :param int polarity: the base state of the clock line (0 or 1)
138+
//| :param int phase: the edge of the clock that data is captured. First (0)
139+
//| or second (1). Rising or falling depends on clock polarity.
140+
//| :param int bits: the number of bits per word
141+
//|
136142
STATIC mp_obj_t nativeio_spi_configure(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
137143
enum { ARG_baudrate, ARG_polarity, ARG_phase, ARG_bits };
138144
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
171177
//|
172178
//| Attempts to grab the SPI lock. Returns True on success.
173179
//|
180+
//| :return: True when lock has been grabbed
181+
//| :rtype: bool
182+
//|
174183
STATIC mp_obj_t nativeio_spi_obj_try_lock(mp_obj_t self_in) {
175184
return mp_obj_new_bool(common_hal_nativeio_spi_try_lock(MP_OBJ_TO_PTR(self_in)));
176185
}

‎shared-bindings/nativeio/TouchIn.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
//| .. currentmodule:: nativeio
3939
//|
4040
//| :class:`TouchIn` -- Read the state of a capacitive touch sensor
41-
//| ============================================
41+
//| ===================================================================
4242
//|
4343
//| Usage::
4444
//|

‎shared-bindings/nativeio/UART.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -143,15 +143,15 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(nativeio_uart___exit___obj, 4, 4, nat
143143

144144
// These are standard stream methods. Code is in py/stream.c.
145145
//
146-
//| .. method:: read([nbytes])
146+
//| .. method:: read(nbytes=None)
147147
//|
148148
//| Read characters. If ``nbytes`` is specified then read at most that many
149149
//| bytes. Otherwise, read everything that has been buffered.
150150
//|
151151
//| :return: Data read
152152
//| :rtype: bytes or None
153153
//|
154-
//| .. method:: readinto(buf[, nbytes])
154+
//| .. method:: readinto(buf, nbytes=None)
155155
//|
156156
//| Read bytes into the ``buf``. If ``nbytes`` is specified then read at most
157157
//| that many bytes. Otherwise, read at most ``len(buf)`` bytes.

‎shared-bindings/neopixel_write/__init__.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,8 @@
4242
//|
4343
//| The `neopixel_write` module contains a helper method to write out bytes in
4444
//| the 800khz neopixel protocol.
45-
46-
//| .. method:: neopixel_write.neopixel_write(digitalinout, buf, is800KHz)
45+
//|
46+
//| .. method:: neopixel_write.neopixel_write(digitalinout, buf)
4747
//|
4848
//| Write buf out on the given DigitalInOut.
4949
//|

0 commit comments

Comments
 (0)