Clarify style of attribute comments in the Design Guide.

And update the core attributes to match the style.

1 files changed, 98 insertions, 31 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
 --------------------------------------------------------------------------------