Clarify style of attribute comments in the Design Guide.

And update the core attributes to match the style.

docs/design_guide.rst

@@ -1,9 +1,7 @@
 Design Guide
 ============
 
-MicroPython has created a great foundation to build upon and to make it even
+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.
-better for beginners we've created CircuitPython. This guide covers a number of
-ways the core and libraries are geared towards beginners.
 
 Start libraries with the cookiecutter
 -------------------------------------
@@ -164,20 +162,110 @@ 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.
+
+           :param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to.
+           :param int address: The I2C address of the device.
+        """
+
+        def __init__(self, i2c_bus, address=0x40):
+            self._i2c = i2c_bus
+
 
 Renders as:
 
-.. py:class:: DS3231
+.. py:class:: DS3231(i2c_bus, address=64)
-  :noindex:
+    :noindex:
 
-  Interface to the DS3231 RTC.
+    DS3231 real-time clock.
+
+    :param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to.
+    :param int address: The I2C address of the device.
+
+Attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+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.
+
+Instance attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Comment comes from after the assignment::
+
+    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:attribute:: drive_mode
+    :noindex:
+
+    The pin drive mode. One of:
+
+    - `digitalio.DriveMode.PUSH_PULL`
+    - `digitalio.DriveMode.OPEN_DRAIN`
+
+Property description
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Comment comes from the getter::
+
+    @property
+    def datetime(self):
+        """The current date and time as a `time.struct_time`."""
+        return self.datetime_register
+
+    @datetime.setter
+    def datetime(self, value):
+        pass
+
+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::
 
@@ -187,9 +275,9 @@ Comment is after even though its weird::
 Renders as:
 
 .. py:attribute:: lost_power
-  :noindex:
+    :noindex:
 
-  True if the device has lost power since the time was set.
+    True if the device has lost power since the time was set.
 
 Method description
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -211,27 +299,6 @@ Renders as:
 
   :param float degrees: Degrees to turn right
 
-Property description
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Comment comes from the getter::
-
-    @property
-    def datetime(self):
-        """The current date and time"""
-        return self.datetime_register
-
-    @datetime.setter
-    def datetime(self, value):
-        pass
-
-Renders as:
-
-.. py:attribute:: datetime
-  :noindex:
-
-  The current date and time
-
 Use BusDevice
 --------------------------------------------------------------------------------
 

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
+//|     The value on the analog pin between 0 and 65535 inclusive (16-bit). (read-only)
-//|     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.
 //|
-//|     :return: the data read
+//|     Even if the underlying analog to digital converter (ADC) is lower
-//|     :rtype: int
+//|     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.
+//|     The maximum voltage measurable (also known as the reference voltage) as a
-//|
+//|     `float` in Volts.
-//|     :return: the reference voltage
-//|     :rtype: float
 //|
 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);

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
+//|     The value on the analog pin between 0 and 65535 inclusive (16-bit). (write-only)
-//|     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
 //|
+//|     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));

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);

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`,
+//|     The pin pull direction. One of:
-//|     `digitalio.Pull.DOWN` or ``None``.
 //|
-//|     :raises AttributeError: if the direction is ~`digitalio.Direction.OUTPUT`.
+//|     - `digitalio.Pull.UP`
+//|     - `digitalio.Pull.DOWN`
+//|     - `None`
+//|
+//|     :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);

shared-bindings/microcontroller/Processor.c

@@ -50,13 +50,13 @@
 
 //| .. class:: Processor()
 //|
-//| You cannot create an instance of `microcontroller.Processor`.
+//|     You cannot create an instance of `microcontroller.Processor`.
-//| Use `microcontroller.cpu` to access the sole instance available.
+//|     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.
+//|       The on-chip temperature, in Celsius, as a float. (read-only)
-//|   If the temperature is not available, return `None`.
+//|
+//|       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.
+//|       The unique id (aka serial number) of the chip as a `bytearray`. (read-only)
-//|   Returns a bytearray object. 
 //|
 STATIC mp_obj_t mcu_processor_get_uid(mp_obj_t self) {
     uint8_t raw_id[COMMON_HAL_MCU_PROCESSOR_UID_LENGTH];

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) {

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.
+//|     Whether the touch pad is being touched or not. (read-only)
-//|     True if `raw_value` > `threshold`.
 //|
-//|     :return: True when touched, False otherwise.
+//|     True when `raw_value` > `threshold`.
-//|     :rtype: bool
 //|
 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.
+//|     The raw touch measurement as an `int`. (read-only)
-//|
-//|     :return: an integer >= 0
-//|     :rtype: int
 //|
 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.
+//|     You can adjust `threshold` to make the pin more or less sensitive.
-//|
-//|     :return: an integer >= 0
-//|     :rtype: int
 //|
 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);

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.
+//|     The usage page of the device as an `int`. Can be thought of a category. (read-only)
-//|
-//|     :return: the device's usage page
-//|     :rtype: int
 //|
 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
+//|     The functionality of the device as an int. (read-only)
-//|     generic desktop usage page 0x01. Mouse is 0x02 within the same usage
-//|     page.
 //|
-//|     :return: the usage within the usage page
+//|     For example, Keyboard is 0x06 within the generic desktop usage page 0x01.
-//|     :rtype: int
+//|     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);