Clarify style of attribute comments in the Design Guide.

And update the core attributes to match the style.

9 files changed, 138 insertions, 85 deletions

diff --git a/docs/design_guide.rst b/docs/design_guide.rst
index 30c926d62..6abb12684 100644
--- a/docs/design_guide.rst
+++ b/docs/design_guide.rst
@@ -1,9 +1,7 @@
 Design Guide
 ============
 
-MicroPython has created a great foundation to build upon and to make it even
-better for beginners we've created CircuitPython. This guide covers a number of
-ways the core and libraries are geared towards beginners.
+This guide covers a variety of development practices for CircuitPython core and library APIs. Consistency with these practices ensures that beginners can learn a pattern once and apply it throughout the CircuitPython ecosystem.
 
 Start libraries with the cookiecutter
 -------------------------------------
@@ -164,61 +162,74 @@ After the license comment::
 Class description
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Documenting what the object does::
+At the class level document what class does and how to initialize it::
 
     class DS3231:
-        """Interface to the DS3231 RTC."""
+        """DS3231 real-time clock.
 
-Renders as:
+           :param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to.
+           :param int address: The I2C address of the device.
+        """
 
-.. py:class:: DS3231
-  :noindex:
+        def __init__(self, i2c_bus, address=0x40):
+            self._i2c = i2c_bus
 
-  Interface to the DS3231 RTC.
 
-Data descriptor description
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Renders as:
 
-Comment is after even though its weird::
+.. py:class:: DS3231(i2c_bus, address=64)
+    :noindex:
 
-    lost_power = i2c_bit.RWBit(0x0f, 7)
-    """True if the device has lost power since the time was set."""
+    DS3231 real-time clock.
 
-Renders as:
+    :param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to.
+    :param int address: The I2C address of the device.
 
-.. py:attribute:: lost_power
-  :noindex:
+Attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  True if the device has lost power since the time was set.
+Attributes are state on objects. (See `Getters/Setters` above for more discussion
+about when to use them.) They can be defined internally in a number of different
+ways. Each approach is enumerated below with an explanation of where the comment
+goes.
 
-Method description
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Regardless of how the attribute is implemented, it should have a short
+description of what state it represents including the type, possible values and/or
+units. It should be marked as ``(read-only)`` or ``(write-only)`` at the end of
+the first line for attributes that are not both readable and writeable.
 
-First line after the method definition::
+Instance attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    def turn_right(self, degrees):
-        """Turns the bot ``degrees`` right.
+Comment comes from after the assignment::
 
-           :param float degrees: Degrees to turn right
+    def __init__(self, drive_mode):
+        self.drive_mode = drive_mode
+        """
+        The pin drive mode. One of:
+
+        - `digitalio.DriveMode.PUSH_PULL`
+        - `digitalio.DriveMode.OPEN_DRAIN`
         """
 
 Renders as:
 
-.. py:method:: turn_right(degrees)
-  :noindex:
+.. py:attribute:: drive_mode
+    :noindex:
 
-  Turns the bot ``degrees`` right.
+    The pin drive mode. One of:
 
-  :param float degrees: Degrees to turn right
+    - `digitalio.DriveMode.PUSH_PULL`
+    - `digitalio.DriveMode.OPEN_DRAIN`
 
 Property description
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Comment comes from the getter::
 
     @property
     def datetime(self):
-        """The current date and time"""
+        """The current date and time as a `time.struct_time`."""
         return self.datetime_register
 
     @datetime.setter
@@ -228,9 +239,65 @@ Comment comes from the getter::
 Renders as:
 
 .. py:attribute:: datetime
+    :noindex:
+
+    The current date and time as a `time.struct_time`.
+
+Read-only example::
+
+    @property
+    def temperature(self):
+        """
+        The current temperature in degrees Celcius. (read-only)
+
+        The device may require calibration to get accurate readings.
+        """
+        return self._read(TEMPERATURE)
+
+
+Renders as:
+
+.. py:attribute:: temperature
+    :noindex:
+
+    The current temperature in degrees Celcius. (read-only)
+
+    The device may require calibration to get accurate readings.
+
+Data descriptor description
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Comment is after even though its weird::
+
+    lost_power = i2c_bit.RWBit(0x0f, 7)
+    """True if the device has lost power since the time was set."""
+
+Renders as:
+
+.. py:attribute:: lost_power
+    :noindex:
+
+    True if the device has lost power since the time was set.
+
+Method description
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+First line after the method definition::
+
+    def turn_right(self, degrees):
+        """Turns the bot ``degrees`` right.
+
+           :param float degrees: Degrees to turn right
+        """
+
+Renders as:
+
+.. py:method:: turn_right(degrees)
   :noindex:
 
-  The current date and time
+  Turns the bot ``degrees`` right.
+
+  :param float degrees: Degrees to turn right
 
 Use BusDevice
 --------------------------------------------------------------------------------
diff --git a/shared-bindings/analogio/AnalogIn.c b/shared-bindings/analogio/AnalogIn.c
index 14b788295..b5f9d7a4e 100644
--- a/shared-bindings/analogio/AnalogIn.c
+++ b/shared-bindings/analogio/AnalogIn.c
@@ -106,13 +106,10 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(analogio_analogin___exit___obj, 4, 4,
 
 //|   .. attribute:: value
 //|
-//|     Read the value on the analog pin and return it.  The returned value
-//|     will be between 0 and 65535 inclusive (16-bit). Even if the underlying
-//|     analog to digital converter (ADC) is lower resolution, the result will
-//|     be scaled to be 16-bit.
+//|     The value on the analog pin between 0 and 65535 inclusive (16-bit). (read-only)
 //|
-//|     :return: the data read
-//|     :rtype: int
+//|     Even if the underlying analog to digital converter (ADC) is lower
+//|     resolution, the value is 16-bit.
 //|
 STATIC mp_obj_t analogio_analogin_obj_get_value(mp_obj_t self_in) {
     analogio_analogin_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -130,10 +127,8 @@ const mp_obj_property_t analogio_analogin_value_obj = {
 
 //|   .. attribute:: reference_voltage
 //|
-//|     The maximum voltage measurable. Also known as the reference voltage.
-//|
-//|     :return: the reference voltage
-//|     :rtype: float
+//|     The maximum voltage measurable (also known as the reference voltage) as a
+//|     `float` in Volts.
 //|
 STATIC mp_obj_t analogio_analogin_obj_get_reference_voltage(mp_obj_t self_in) {
     analogio_analogin_obj_t *self = MP_OBJ_TO_PTR(self_in);
diff --git a/shared-bindings/analogio/AnalogOut.c b/shared-bindings/analogio/AnalogOut.c
index 0c7a59db8..721448fa4 100644
--- a/shared-bindings/analogio/AnalogOut.c
+++ b/shared-bindings/analogio/AnalogOut.c
@@ -105,13 +105,10 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(analogio_analogout___exit___obj, 4, 4
 
 //|   .. attribute:: value
 //|
-//|     The value on the analog pin.  The value must be between 0 and 65535
-//|     inclusive (16-bit). Even if the underlying digital to analog converter
-//|     is lower resolution, the input must be scaled to be 16-bit.
-//|
-//|     :return: the last value written
-//|     :rtype: int
+//|     The value on the analog pin between 0 and 65535 inclusive (16-bit). (write-only)
 //|
+//|     Even if the underlying digital to analog converter (DAC) is lower
+//|     resolution, the value is 16-bit.
 STATIC mp_obj_t analogio_analogout_obj_set_value(mp_obj_t self_in, mp_obj_t value) {
    analogio_analogout_obj_t *self = MP_OBJ_TO_PTR(self_in);
    raise_error_if_deinited(common_hal_analogio_analogout_deinited(self));
diff --git a/shared-bindings/audioio/AudioOut.c b/shared-bindings/audioio/AudioOut.c
index 4e76565e9..c932dda4a 100644
--- a/shared-bindings/audioio/AudioOut.c
+++ b/shared-bindings/audioio/AudioOut.c
@@ -187,7 +187,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_stop_obj, audioio_audioout_obj_stop);
 
 //|   .. attribute:: playing
 //|
-//|     True when the audio sample is being output.
+//|     True when the audio sample is being output. (read-only)
 //|
 STATIC mp_obj_t audioio_audioout_obj_get_playing(mp_obj_t self_in) {
     audioio_audioout_obj_t *self = MP_OBJ_TO_PTR(self_in);
diff --git a/shared-bindings/digitalio/DigitalInOut.c b/shared-bindings/digitalio/DigitalInOut.c
index 008883b8b..1270f84e4 100644
--- a/shared-bindings/digitalio/DigitalInOut.c
+++ b/shared-bindings/digitalio/DigitalInOut.c
@@ -253,7 +253,10 @@ const mp_obj_property_t digitalio_digitalinout_value_obj = {
 
 //|   .. attribute:: drive_mode
 //|
-//|     Get or set the pin drive mode.
+//|     The pin drive mode. One of:
+//|
+//|     - `digitalio.DriveMode.PUSH_PULL`
+//|     - `digitalio.DriveMode.OPEN_DRAIN`
 //|
 STATIC mp_obj_t digitalio_digitalinout_obj_get_drive_mode(mp_obj_t self_in) {
     digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -295,10 +298,13 @@ const mp_obj_property_t digitalio_digitalio_drive_mode_obj = {
 
 //|   .. attribute:: pull
 //|
-//|     Get or set the pin pull. Values may be `digitalio.Pull.UP`,
-//|     `digitalio.Pull.DOWN` or ``None``.
+//|     The pin pull direction. One of:
+//|
+//|     - `digitalio.Pull.UP`
+//|     - `digitalio.Pull.DOWN`
+//|     - `None`
 //|
-//|     :raises AttributeError: if the direction is ~`digitalio.Direction.OUTPUT`.
+//|     :raises AttributeError: if `direction` is :py:data:`~digitalio.Direction.OUTPUT`.
 //|
 STATIC mp_obj_t digitalio_digitalinout_obj_get_pull(mp_obj_t self_in) {
     digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in);
diff --git a/shared-bindings/microcontroller/Processor.c b/shared-bindings/microcontroller/Processor.c
index 7cc0d6016..a311f1866 100644
--- a/shared-bindings/microcontroller/Processor.c
+++ b/shared-bindings/microcontroller/Processor.c
@@ -50,13 +50,13 @@
 
 //| .. class:: Processor()
 //|
-//| You cannot create an instance of `microcontroller.Processor`.
-//| Use `microcontroller.cpu` to access the sole instance available.
+//|     You cannot create an instance of `microcontroller.Processor`.
+//|     Use `microcontroller.cpu` to access the sole instance available.
 //|
 
-//| .. attribute:: frequency
+//|     .. attribute:: frequency
 //|
-//|   Return the CPU operating frequency as an int, in Hz.
+//|       The CPU operating frequency as an `int`, in Hertz. (read-only)
 //|
 STATIC mp_obj_t mcu_processor_get_frequency(mp_obj_t self) {
     return mp_obj_new_int_from_uint(common_hal_mcu_processor_get_frequency());
@@ -72,10 +72,11 @@ const mp_obj_property_t mcu_processor_frequency_obj = {
     },
 };
 
-//| .. attribute:: temperature
+//|     .. attribute:: temperature
 //|
-//|   Return the on-chip temperature, in Celsius, as a float.
-//|   If the temperature is not available, return `None`.
+//|       The on-chip temperature, in Celsius, as a float. (read-only)
+//|
+//|       Is `None` if the temperature is not available.
 //|
 STATIC mp_obj_t mcu_processor_get_temperature(mp_obj_t self) {
     float temperature = common_hal_mcu_processor_get_temperature();
@@ -92,10 +93,9 @@ const mp_obj_property_t mcu_processor_temperature_obj = {
     },
 };
 
-//| .. attribute:: uid
+//|     .. attribute:: uid
 //|
-//|   Return the unique id (aka serial number) of the chip.
-//|   Returns a bytearray object. 
+//|       The unique id (aka serial number) of the chip as a `bytearray`. (read-only)
 //|
 STATIC mp_obj_t mcu_processor_get_uid(mp_obj_t self) {
     uint8_t raw_id[COMMON_HAL_MCU_PROCESSOR_UID_LENGTH];
diff --git a/shared-bindings/pulseio/PulseIn.c b/shared-bindings/pulseio/PulseIn.c
index 8be62f4bf..736441c74 100644
--- a/shared-bindings/pulseio/PulseIn.c
+++ b/shared-bindings/pulseio/PulseIn.c
@@ -201,7 +201,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(pulseio_pulsein_popleft_obj, pulseio_pulsein_obj_pople
 
 //|   .. attribute:: maxlen
 //|
-//|     Returns the maximum length of the PulseIn. When len() is equal to maxlen,
+//|     The maximum length of the PulseIn. When len() is equal to maxlen,
 //|     it is unclear which pulses are active and which are idle.
 //|
 STATIC mp_obj_t pulseio_pulsein_obj_get_maxlen(mp_obj_t self_in) {
diff --git a/shared-bindings/touchio/TouchIn.c b/shared-bindings/touchio/TouchIn.c
index 1d9123312..710260faf 100644
--- a/shared-bindings/touchio/TouchIn.c
+++ b/shared-bindings/touchio/TouchIn.c
@@ -107,11 +107,9 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(touchio_touchin___exit___obj, 4, 4, t
 
 //|   .. attribute:: value
 //|
-//|     Whether the touch pad is being touched or not.
-//|     True if `raw_value` > `threshold`.
+//|     Whether the touch pad is being touched or not. (read-only)
 //|
-//|     :return: True when touched, False otherwise.
-//|     :rtype: bool
+//|     True when `raw_value` > `threshold`.
 //|
 STATIC mp_obj_t touchio_touchin_obj_get_value(mp_obj_t self_in) {
     touchio_touchin_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -130,10 +128,7 @@ const mp_obj_property_t touchio_touchin_value_obj = {
 
 //|   .. attribute:: raw_value
 //|
-//|     The raw touch measurement. Not settable.
-//|
-//|     :return: an integer >= 0
-//|     :rtype: int
+//|     The raw touch measurement as an `int`. (read-only)
 //|
 STATIC mp_obj_t touchio_touchin_obj_get_raw_value(mp_obj_t self_in) {
     touchio_touchin_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -153,14 +148,12 @@ const mp_obj_property_t touchio_touchin_raw_value_obj = {
 
 //|   .. attribute:: threshold
 //|
-//|     `value` will return True if `raw_value` is greater than than this threshold.
+//|     Minimum `raw_value` needed to detect a touch (and for `value` to be `True`).
+//|
 //|     When the **TouchIn** object is created, an initial `raw_value` is read from the pin,
 //|     and then `threshold` is set to be 100 + that value.
 //|
-//|     You can set the threshold to a different value to make the pin more or less sensitive.
-//|
-//|     :return: an integer >= 0
-//|     :rtype: int
+//|     You can adjust `threshold` to make the pin more or less sensitive.
 //|
 STATIC mp_obj_t touchio_touchin_obj_get_threshold(mp_obj_t self_in) {
     touchio_touchin_obj_t *self = MP_OBJ_TO_PTR(self_in);
diff --git a/shared-bindings/usb_hid/Device.c b/shared-bindings/usb_hid/Device.c
index 7e5d3d9e8..21dbc7a2c 100644
--- a/shared-bindings/usb_hid/Device.c
+++ b/shared-bindings/usb_hid/Device.c
@@ -67,10 +67,7 @@ MP_DEFINE_CONST_FUN_OBJ_2(usb_hid_device_send_report_obj, usb_hid_device_send_re
 
 //|   .. attribute:: usage_page
 //|
-//|     The usage page of the device. Can be thought of a category.
-//|
-//|     :return: the device's usage page
-//|     :rtype: int
+//|     The usage page of the device as an `int`. Can be thought of a category. (read-only)
 //|
 STATIC mp_obj_t usb_hid_device_obj_get_usage_page(mp_obj_t self_in) {
     usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -87,12 +84,10 @@ const mp_obj_property_t usb_hid_device_usage_page_obj = {
 
 //|   .. attribute:: usage
 //|
-//|     The functionality of the device. For example Keyboard is 0x06 within the
-//|     generic desktop usage page 0x01. Mouse is 0x02 within the same usage
-//|     page.
+//|     The functionality of the device as an int. (read-only)
 //|
-//|     :return: the usage within the usage page
-//|     :rtype: int
+//|     For example, Keyboard is 0x06 within the generic desktop usage page 0x01.
+//|     Mouse is 0x02 within the same usage page.
 //|
 STATIC mp_obj_t usb_hid_device_obj_get_usage(mp_obj_t self_in) {
     usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in);