Skip to content

Commit 767eed7

Browse files
dhalbertdhalbert
committed
big cleanup of SPI and I2C doc; fix arg names on SPI
1 parent b48bb75 commit 767eed7

File tree

5 files changed

+151
-103
lines changed

5 files changed

+151
-103
lines changed

‎shared-bindings/adafruit_bus_device/I2CDevice.c

Lines changed: 32 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,8 @@
6363
//| device.readinto(bytes_read)
6464
//| # A second transaction
6565
//| with device:
66-
//| device.write(bytes_read)"""
66+
//| device.write(bytes_read)
67+
//| """
6768
//| ...
6869
//|
6970
STATIC mp_obj_t adafruit_bus_device_i2cdevice_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -111,15 +112,16 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(adafruit_bus_device_i2cdevice___exit_
111112

112113
//| import sys
113114
//| def readinto(self, buffer: WriteableBuffer, *, start: int = 0, end: int = sys.maxsize) -> None:
114-
//| """Read into ``buffer`` from the device. The number of bytes read will be the
115-
//| length of ``buffer``.
115+
//| """Read into ``buffer`` from the device.
116+
//|
116117
//| If ``start`` or ``end`` is provided, then the buffer will be sliced
117-
//| as if ``buffer[start:end]``. This will not cause an allocation like
118-
//| ``buffer[start:end]`` will so it saves memory.
118+
//| as if ``buffer[start:end]`` were passed.
119+
//| The number of bytes read will be the length of ``buffer[start:end]``
119120
//|
120-
//| :param bytearray buffer: buffer to write into
121-
//| :param int start: Index to start writing at
122-
//| :param int end: Index to write up to but not include; if None, use ``len(buffer)``"""
121+
//| :param WriteableBuffer buffer: read bytes into this buffer
122+
//| :param int start: beginning of buffer slice
123+
//| :param int end: end of buffer slice; if not specified, use ``len(buffer)``
124+
//| """
123125
//| ...
124126
//|
125127
STATIC mp_obj_t adafruit_bus_device_i2cdevice_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -158,13 +160,14 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(adafruit_bus_device_i2cdevice_readinto_obj, 1,
158160
//| import sys
159161
//| def write(self, buffer: ReadableBuffer, *, start: int = 0, end: int = sys.maxsize) -> None:
160162
//| """Write the bytes from ``buffer`` to the device, then transmit a stop bit.
163+
//|
161164
//| If ``start`` or ``end`` is provided, then the buffer will be sliced
162-
//| as if ``buffer[start:end]``. This will not cause an allocation like
163-
//| ``buffer[start:end]`` will so it saves memory.
165+
//| as if ``buffer[start:end]`` were passed, but without copying the data.
166+
//| The number of bytes written will be the length of ``buffer[start:end]``
164167
//|
165-
//| :param bytearray buffer: buffer containing the bytes to write
166-
//| :param int start: Index to start writing from
167-
//| :param int end: Index to read up to but not include; if None, use ``len(buffer)``
168+
//| :param ReadableBuffer buffer: write out bytes from this buffer
169+
//| :param int start: beginning of buffer slice
170+
//| :param int end: end of buffer slice; if not specified, use ``len(buffer)``
168171
//| """
169172
//| ...
170173
//|
@@ -202,25 +205,24 @@ MP_DEFINE_CONST_FUN_OBJ_KW(adafruit_bus_device_i2cdevice_write_obj, 1, adafruit_
202205

203206

204207
//| import sys
205-
//| def write_then_readinto(self, out_buffer: WriteableBuffer, in_buffer: ReadableBuffer, *, out_start: int = 0, out_end: int = sys.maxsize, in_start: int = 0, in_end: int = sys.maxsize) -> None:
208+
//| def write_then_readinto(self, out_buffer: ReadableBuffer, in_buffer: WriteableBuffer, *, out_start: int = 0, out_end: int = sys.maxsize, in_start: int = 0, in_end: int = sys.maxsize) -> None:
206209
//| """Write the bytes from ``out_buffer`` to the device, then immediately
207-
//| reads into ``in_buffer`` from the device. The number of bytes read
208-
//| will be the length of ``in_buffer``.
209-
//| If ``out_start`` or ``out_end`` is provided, then the output buffer
210-
//| will be sliced as if ``out_buffer[out_start:out_end]``. This will
211-
//| not cause an allocation like ``buffer[out_start:out_end]`` will so
212-
//| it saves memory.
213-
//| If ``in_start`` or ``in_end`` is provided, then the input buffer
214-
//| will be sliced as if ``in_buffer[in_start:in_end]``. This will not
215-
//| cause an allocation like ``in_buffer[in_start:in_end]`` will so
216-
//| it saves memory.
210+
//| reads into ``in_buffer`` from the device.
211+
//|
212+
//| If ``out_start`` or ``out_end`` is provided, then the buffer will be sliced
213+
//| as if ``out_buffer[out_start:out_end]`` were passed, but without copying the data.
214+
//| The number of bytes written will be the length of ``out_buffer[out_start:out_end]``
215+
//|
216+
//| If ``in_start`` or ``in_end`` is provided, then the input buffer will be sliced
217+
//| as if ``in_buffer[in_start:in_end]`` were passed,
218+
//| The number of bytes read will be the length of ``out_buffer[in_start:in_end]``
217219
//|
218-
//| :param bytearray out_buffer: buffer containing the bytes to write
219-
//| :param bytearray in_buffer: buffer containing the bytes to read into
220-
//| :param int out_start: Index to start writing from
221-
//| :param int out_end: Index to read up to but not include; if not specified, use ``len(out_buffer)``
222-
//| :param int in_start: Index to start writing at
223-
//| :param int in_end: Index to write up to but not include; if not specified, use ``len(in_buffer)``
220+
//| :param ReadableBuffer out_buffer: write out bytes from this buffer
221+
//| :param WriteableBuffer in_buffer: read bytes into this buffer
222+
//| :param int out_start: beginning of ``out_buffer`` slice
223+
//| :param int out_end: end of ``out_buffer`` slice; if not specified, use ``len(out_buffer)``
224+
//| :param int in_start: beginning of ``in_buffer`` slice
225+
//| :param int in_end: end of ``in_buffer slice``; if not specified, use ``len(in_buffer)``
224226
//| """
225227
//| ...
226228
//|

‎shared-bindings/bitbangio/I2C.c

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -176,7 +176,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_unlock_obj, bitbangio_i2c_obj_unlock);
176176
//| ``buf[start:end]`` will so it saves memory.
177177
//|
178178
//| :param int address: 7-bit device address
179-
//| :param ~_typing.WriteableBuffer buffer: buffer to write into
179+
//| :param WriteableBuffer buffer: buffer to write into
180180
//| :param int start: Index to start writing at
181181
//| :param int end: Index to write up to but not include"""
182182
//| ...
@@ -225,16 +225,17 @@ MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_i2c_readfrom_into_obj, 1, bitbangio_i2c_rea
225225
//| before a read.
226226
//|
227227
//| If ``start`` or ``end`` is provided, then the buffer will be sliced
228-
//| as if ``buffer[start:end]``. This will not cause an allocation like
229-
//| ``buffer[start:end]`` will so it saves memory.
228+
//| as if ``buffer[start:end]`` were passed, but without copying the data.
229+
//| The number of bytes written will be the length of ``buffer[start:end]``
230230
//|
231231
//| Writing a buffer or slice of length zero is permitted, as it can be used
232232
//| to poll for the existence of a device.
233233
//|
234234
//| :param int address: 7-bit device address
235-
//| :param ~_typing.ReadableBuffer buffer: buffer containing the bytes to write
236-
//| :param int start: Index to start writing from
237-
//| :param int end: Index to read up to but not include. If not specified, use ``len(buffer)``"""
235+
//| :param ReadableBuffer buffer: buffer containing the bytes to write
236+
//| :param int start: beginning of buffer slice
237+
//| :param int end: end of buffer slice; if not specified, use ``len(buffer)``
238+
//| """
238239
//| ...
239240
//|
240241
// Shared arg parsing for writeto and writeto_then_readfrom.
@@ -282,17 +283,23 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_i2c_writeto_obj, 1, bitbangio_i2c_wr
282283
//| bit, generate a repeated start and read into ``in_buffer``. ``out_buffer`` and
283284
//| ``in_buffer`` can be the same buffer because they are used sequentially.
284285
//|
285-
//| If ``start`` or ``end`` is provided, then the corresponding buffer will be sliced
286-
//| as if ``buffer[start:end]``. This will not cause an allocation like ``buf[start:end]``
287-
//| will so it saves memory.
286+
//| If ``out_start`` or ``out_end`` is provided, then the buffer will be sliced
287+
//| as if ``out_buffer[out_start:out_end]`` were passed, but without copying the data.
288+
//| The number of bytes written will be the length of ``out_buffer[start:end]``
288289
//|
290+
//| If ``in_start`` or ``in_end`` is provided, then the input buffer will be sliced
291+
//| as if ``in_buffer[in_start:in_end]`` were passed,
292+
//| The number of bytes read will be the length of ``out_buffer[in_start:in_end]``
293+
289294
//| :param int address: 7-bit device address
290295
//| :param ~_typing.ReadableBuffer out_buffer: buffer containing the bytes to write
291296
//| :param ~_typing.WriteableBuffer in_buffer: buffer to write into
292-
//| :param int out_start: Index to start writing from
293-
//| :param int out_end: Index to read up to but not include. If not specified, use ``len(buffer)``
294-
//| :param int in_start: Index to start writing at
295-
//| :param int in_end: Index to write up to but not include. If not specified, use ``len(buffer)``"""
297+
//| :param int out_start: beginning of ``out_buffer`` slice
298+
//| :param int out_end: end of ``out_buffer`` slice; if not specified, use ``len(out_buffer)``
299+
//| :param int in_start: beginning of ``in_buffer`` slice
300+
//| :param int in_end: end of ``in_buffer slice``; if not specified, use ``len(in_buffer)``
301+
//| """
302+
//| ...
296303
//|
297304
STATIC mp_obj_t bitbangio_i2c_writeto_then_readfrom(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
298305
enum { ARG_address, ARG_out_buffer, ARG_in_buffer, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end };

‎shared-bindings/bitbangio/SPI.c

Lines changed: 34 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -230,13 +230,17 @@ MP_DEFINE_CONST_FUN_OBJ_2(bitbangio_spi_write_obj, bitbangio_spi_write);
230230
//| The SPI object must be locked.
231231
//| If the number of bytes to read is 0, nothing happens.
232232
//|
233-
//| :param bytearray buffer: Read data into this buffer
234-
//| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]``
235-
//| :param int end: End of the slice; this index is not included. If not specified, use ``len(buffer)``
236-
//| :param int write_value: Value to write while reading."""
233+
//| If ``start`` or ``end`` is provided, then the buffer will be sliced
234+
//| as if ``buffer[start:end]`` were passed.
235+
//| The number of bytes read will be the length of ``buffer[start:end]``
236+
//|
237+
//| :param WriteableBuffer buffer: read bytes into this buffer
238+
//| :param int start: beginning of buffer slice
239+
//| :param int end: end of buffer slice; if not specified, use ``len(buffer)``
240+
//| :param int write_value: value to write while reading
241+
//| """
237242
//| ...
238243
//|
239-
240244
STATIC mp_obj_t bitbangio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
241245
enum { ARG_buffer, ARG_start, ARG_end, ARG_write_value };
242246
static const mp_arg_t allowed_args[] = {
@@ -270,26 +274,36 @@ STATIC mp_obj_t bitbangio_spi_readinto(size_t n_args, const mp_obj_t *pos_args,
270274
MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_spi_readinto_obj, 1, bitbangio_spi_readinto);
271275

272276
//| import sys
273-
//| def write_readinto(self, buffer_out: ReadableBuffer, buffer_in: ReadableBuffer, *, out_start: int = 0, out_end: int = sys.maxsize, in_start: int = 0, in_end: int = sys.maxsize) -> None:
274-
//| """Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``.
277+
//| def write_readinto(self, out_buffer: ReadableBuffer, in_buffer: WriteableBuffer, *, out_start: int = 0, out_end: int = sys.maxsize, in_start: int = 0, in_end: int = sys.maxsize) -> None:
278+
//| """Write out the data in ``out_buffer`` while simultaneously reading data into ``in_buffer``.
275279
//| The SPI object must be locked.
276-
//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]``
277-
//| must be equal.
280+
//|
281+
//| If ``out_start`` or ``out_end`` is provided, then the buffer will be sliced
282+
//| as if ``out_buffer[out_start:out_end]`` were passed, but without copying the data.
283+
//| The number of bytes written will be the length of ``out_buffer[out_start:out_end]``
284+
//|
285+
//| If ``in_start`` or ``in_end`` is provided, then the input buffer will be sliced
286+
//| as if ``in_buffer[in_start:in_end]`` were passed,
287+
//| The number of bytes read will be the length of ``out_buffer[in_start:in_end]``
288+
//|
289+
//| The lengths of the slices defined by ``out_buffer[out_start:out_end]``
290+
//| and ``in_buffer[in_start:in_end]`` must be equal.
278291
//| If buffer slice lengths are both 0, nothing happens.
279292
//|
280-
//| :param ~_typing.ReadableBuffer buffer_out: Write out the data in this buffer
281-
//| :param ~_typing.WriteableBuffer buffer_in: Read data into this buffer
282-
//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]``
283-
//| :param int out_end: End of the slice; this index is not included. If not specified, use ``len(buffer_out)``
284-
//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]``
285-
//| :param int in_end: End of the slice; this index is not included. If not specified, use ``len(buffer_in)``"""
293+
//| :param ReadableBuffer out_buffer: write out bytes from this buffer
294+
//| :param WriteableBuffer in_buffer: read bytes into this buffer
295+
//| :param int out_start: beginning of ``out_buffer`` slice
296+
//| :param int out_end: end of ``out_buffer`` slice; if not specified, use ``len(out_buffer)``
297+
//| :param int in_start: beginning of ``in_buffer`` slice
298+
//| :param int in_end: end of ``in_buffer slice``; if not specified, use ``len(in_buffer)``
299+
//| """
286300
//| ...
287301
//|
288302
STATIC mp_obj_t bitbangio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
289-
enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end };
303+
enum { ARG_out_buffer, ARG_in_buffer, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end };
290304
static const mp_arg_t allowed_args[] = {
291-
{ MP_QSTR_buffer_out, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} },
292-
{ MP_QSTR_buffer_in, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} },
305+
{ MP_QSTR_out_buffer, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} },
306+
{ MP_QSTR_in_buffer, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} },
293307
{ MP_QSTR_out_start, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 0} },
294308
{ MP_QSTR_out_end, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = INT_MAX} },
295309
{ MP_QSTR_in_start, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 0} },
@@ -303,13 +317,13 @@ STATIC mp_obj_t bitbangio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_
303317
mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
304318

305319
mp_buffer_info_t buf_out_info;
306-
mp_get_buffer_raise(args[ARG_buffer_out].u_obj, &buf_out_info, MP_BUFFER_READ);
320+
mp_get_buffer_raise(args[ARG_out_buffer].u_obj, &buf_out_info, MP_BUFFER_READ);
307321
int32_t out_start = args[ARG_out_start].u_int;
308322
size_t out_length = buf_out_info.len;
309323
normalize_buffer_bounds(&out_start, args[ARG_out_end].u_int, &out_length);
310324

311325
mp_buffer_info_t buf_in_info;
312-
mp_get_buffer_raise(args[ARG_buffer_in].u_obj, &buf_in_info, MP_BUFFER_WRITE);
326+
mp_get_buffer_raise(args[ARG_in_buffer].u_obj, &buf_in_info, MP_BUFFER_WRITE);
313327
int32_t in_start = args[ARG_in_start].u_int;
314328
size_t in_length = buf_in_info.len;
315329
normalize_buffer_bounds(&in_start, args[ARG_in_end].u_int, &in_length);

0 commit comments

Comments
 (0)