Use main/selected terminology in docstrings

Also copy some notes from busio docstrings to bitbangio docstrings

6 files changed, 46 insertions, 27 deletions

diff --git a/shared-bindings/bitbangio/I2C.c b/shared-bindings/bitbangio/I2C.c
index 2043fc903..43fe11e62 100644
--- a/shared-bindings/bitbangio/I2C.c
+++ b/shared-bindings/bitbangio/I2C.c
@@ -45,6 +45,14 @@
 //|         physical level it consists of 2 wires: SCL and SDA, the clock and data
 //|         lines respectively.
 //|
+//|         .. seealso:: Using this class directly requires careful lock management.
+//|             Instead, use :class:`~adafruit_bus_device.i2c_device.I2CDevice` to
+//|             manage locks.
+//|
+//|         .. seealso:: Using this class to directly read registers requires manual
+//|             bit unpacking. Instead, use an existing driver or make one with
+//|             :ref:`Register <register-module-reference>` data descriptors.
+//|
 //|         :param ~microcontroller.Pin scl: The clock pin
 //|         :param ~microcontroller.Pin sda: The data pin
 //|         :param int frequency: The clock frequency of the bus
@@ -158,7 +166,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);
 
 //|     def readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None) -> Any:
-//|         """Read into ``buffer`` from the slave specified by ``address``.
+//|         """Read into ``buffer`` from the device selected by ``address``.
 //|         The number of bytes read will be the length of ``buffer``.
 //|         At least one byte must be read.
 //|
@@ -210,7 +218,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);
 
 //|     def writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) -> Any:
-//|         """Write the bytes from ``buffer`` to the slave specified by ``address`` and then transmits a
+//|         """Write the bytes from ``buffer`` to the device selected by ``address`` and then transmits a
 //|         stop bit. Use `writeto_then_readfrom` when needing a write, no stop and repeated start
 //|         before a read.
 //|
@@ -270,7 +278,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_i2c_writeto_obj, 1, bitbangio_i2c_wr
 
 
 //|     def writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: int = None) -> Any:
-//|         """Write the bytes from ``out_buffer`` to the slave specified by ``address``, generate no stop
+//|         """Write the bytes from ``out_buffer`` to the device selected by ``address``, generate no stop
 //|         bit, generate a repeated start and read into ``in_buffer``. ``out_buffer`` and
 //|         ``in_buffer`` can be the same buffer because they are used sequentially.
 //|
diff --git a/shared-bindings/bitbangio/SPI.c b/shared-bindings/bitbangio/SPI.c
index 08bbf1257..6d31037c7 100644
--- a/shared-bindings/bitbangio/SPI.c
+++ b/shared-bindings/bitbangio/SPI.c
@@ -43,19 +43,29 @@
 //|     """A 3-4 wire serial protocol
 //|
 //|     SPI is a serial protocol that has exclusive pins for data in and out of the
-//|     master.  It is typically faster than :py:class:`~bitbangio.I2C` because a
-//|     separate pin is used to control the active slave rather than a transmitted
+//|     main device.  It is typically faster than :py:class:`~bitbangio.I2C` because a
+//|     separate pin is used to select a device rather than a transmitted
 //|     address. This class only manages three of the four SPI lines: `!clock`,
-//|     `!MOSI`, `!MISO`. Its up to the client to manage the appropriate slave
-//|     select line. (This is common because multiple slaves can share the `!clock`,
-//|     `!MOSI` and `!MISO` lines and therefore the hardware.)"""
+//|     `!MOSI`, `!MISO`. Its up to the client to manage the appropriate
+//|     select line, often abbreviated `!CS` or `!SS`. (This is common because
+//|     multiple secondaries can share the `!clock`, `!MOSI` and `!MISO` lines
+//|     and therefore the hardware.)"""
 //|
 //|     def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None):
 //|         """Construct an SPI object on the given pins.
 //|
+//|         .. seealso:: Using this class directly requires careful lock management.
+//|             Instead, use :class:`~adafruit_bus_device.spi_device.SPIDevice` to
+//|             manage locks.
+//|
+//|         .. seealso:: Using this class to directly read registers requires manual
+//|             bit unpacking. Instead, use an existing driver or make one with
+//|             :ref:`Register <register-module-reference>` data descriptors.
+//|
+//|
 //|         :param ~microcontroller.Pin clock: the pin to use for the clock.
-//|         :param ~microcontroller.Pin MOSI: the Master Out Slave In pin.
-//|         :param ~microcontroller.Pin MISO: the Master In Slave Out pin."""
+//|         :param ~microcontroller.Pin MOSI: the Main Out Selected In pin.
+//|         :param ~microcontroller.Pin MISO: the Main In Selected Out pin."""
 //|         ...
 //|
 
diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c
index 7e8af765f..b61dd93f3 100644
--- a/shared-bindings/busio/I2C.c
+++ b/shared-bindings/busio/I2C.c
@@ -177,7 +177,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);
 
 //|     def readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None) -> Any:
-//|          """Read into ``buffer`` from the slave specified by ``address``.
+//|          """Read into ``buffer`` from the device selected by ``address``.
 //|          The number of bytes read will be the length of ``buffer``.
 //|          At least one byte must be read.
 //|
@@ -229,7 +229,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);
 
 //|     def writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) -> Any:
-//|          """Write the bytes from ``buffer`` to the slave specified by ``address``.
+//|          """Write the bytes from ``buffer`` to the device selected by ``address``.
 //|          Transmits a stop bit when stop is True. Setting stop=False is deprecated and stop will be
 //|          removed in CircuitPython 6.x. Use `writeto_then_readfrom` when needing a write, no stop and
 //|          repeated start before a read.
@@ -288,7 +288,7 @@ STATIC mp_obj_t busio_i2c_writeto(size_t n_args, const mp_obj_t *pos_args, mp_ma
 STATIC MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_writeto_obj, 1, busio_i2c_writeto);
 
 //|     def writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: int = None) -> Any:
-//|          """Write the bytes from ``out_buffer`` to the slave specified by ``address``, generate no stop
+//|          """Write the bytes from ``out_buffer`` to the device selected by ``address``, generate no stop
 //|          bit, generate a repeated start and read into ``in_buffer``. ``out_buffer`` and
 //|          ``in_buffer`` can be the same buffer because they are used sequentially.
 //|
diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c
index 2ba9a4c22..22f001d2d 100644
--- a/shared-bindings/busio/SPI.c
+++ b/shared-bindings/busio/SPI.c
@@ -45,12 +45,13 @@
 //|     """A 3-4 wire serial protocol
 //|
 //|     SPI is a serial protocol that has exclusive pins for data in and out of the
-//|     master.  It is typically faster than :py:class:`~busio.I2C` because a
-//|     separate pin is used to control the active slave rather than a transitted
+//|     main device.  It is typically faster than :py:class:`~bitbangio.I2C` because a
+//|     separate pin is used to select a device rather than a transmitted
 //|     address. This class only manages three of the four SPI lines: `!clock`,
-//|     `!MOSI`, `!MISO`. Its up to the client to manage the appropriate slave
-//|     select line. (This is common because multiple slaves can share the `!clock`,
-//|     `!MOSI` and `!MISO` lines and therefore the hardware.)"""
+//|     `!MOSI`, `!MISO`. Its up to the client to manage the appropriate
+//|     select line, often abbreviated `!CS` or `!SS`. (This is common because
+//|     multiple secondaries can share the `!clock`, `!MOSI` and `!MISO` lines
+//|     and therefore the hardware.)"""
 //|
 //|     def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None):
 //|
@@ -72,8 +73,8 @@
 //|             :ref:`Register <register-module-reference>` data descriptors.
 //|
 //|         :param ~microcontroller.Pin clock: the pin to use for the clock.
-//|         :param ~microcontroller.Pin MOSI: the Master Out Slave In pin.
-//|         :param ~microcontroller.Pin MISO: the Master In Slave Out pin."""
+//|         :param ~microcontroller.Pin MOSI: the Main Out Selected In pin.
+//|         :param ~microcontroller.Pin MISO: the Main In Selected Out pin."""
 //|         ...
 //|
 
diff --git a/shared-bindings/i2cslave/I2CSlave.c b/shared-bindings/i2cslave/I2CSlave.c
index 80875ce75..9f051a125 100644
--- a/shared-bindings/i2cslave/I2CSlave.c
+++ b/shared-bindings/i2cslave/I2CSlave.c
@@ -134,7 +134,7 @@ STATIC mp_obj_t i2cslave_i2c_slave_obj___exit__(size_t n_args, const mp_obj_t *a
 STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(i2cslave_i2c_slave___exit___obj, 4, 4, i2cslave_i2c_slave_obj___exit__);
 
 //|     def request(self, timeout: float = -1) -> Any:
-//|         """Wait for an I2C request from a master.
+//|         """Wait for an I2C request.
 //|
 //|         :param float timeout: Timeout in seconds. Zero means wait forever, a negative value means check once
 //|         :return: I2C Slave Request or None if timeout=-1 and there's no request
@@ -228,12 +228,12 @@ const mp_obj_type_t i2cslave_i2c_slave_type = {
 //| class I2CSlaveRequest:
 //|
 //|     def __init__(self, slave: i2cslave.I2CSlave, address: int, is_read: bool, is_restart: bool):
-//|         """I2C transfer request from a master.
+//|         """Information about an I2C transfer request
 //|         This cannot be instantiated directly, but is returned by :py:meth:`I2CSlave.request`.
 //|
 //|         :param slave: The I2C Slave receiving this request
 //|         :param address: I2C address
-//|         :param is_read: I2C Master read request
+//|         :param is_read: True if the main device is requesting data
 //|         :param is_restart: Repeated Start Condition"""
 //|
 STATIC mp_obj_t i2cslave_i2c_slave_request_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) {
@@ -270,7 +270,7 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_get_address(mp_obj_t self_in) {
 MP_DEFINE_CONST_PROP_GET(i2cslave_i2c_slave_request_address_obj, i2cslave_i2c_slave_request_get_address);
 
 //|     is_read: bool = ...
-//|     """The I2C master is reading from the device."""
+//|     """The I2C main controller is reading from this device."""
 //|
 STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_read(mp_obj_t self_in) {
     mp_check_self(MP_OBJ_IS_TYPE(self_in, &i2cslave_i2c_slave_request_type));
diff --git a/shared-bindings/i2cslave/__init__.c b/shared-bindings/i2cslave/__init__.c
index 41b42fef8..59674d5cb 100644
--- a/shared-bindings/i2cslave/__init__.c
+++ b/shared-bindings/i2cslave/__init__.c
@@ -53,9 +53,9 @@
 //|           if not r:
 //|               # Maybe do some housekeeping
 //|               continue
-//|           with r:  # Closes the transfer if necessary by sending a NACK or feeding the master dummy bytes
+//|           with r:  # Closes the transfer if necessary by sending a NACK or feeding dummy bytes
 //|               if r.address == 0x40:
-//|                   if not r.is_read:  # Master write which is Slave read
+//|                   if not r.is_read:  # Main write which is Selected read
 //|                       b = r.read(1)
 //|                       if not b or b[0] > 15:
 //|                           break
@@ -63,7 +63,7 @@
 //|                       b = r.read(1)
 //|                       if b:
 //|                           regs[index] = b[0]
-//|                   elif r.is_restart:  # Combined transfer: This is the Master read message
+//|                   elif r.is_restart:  # Combined transfer: This is the Main read message
 //|                       n = r.write(bytes([regs[index]]))
 //|                   #else:
 //|                       # A read transfer is not supported in this example