From 15db02664dedf0f2241a922fb1b756052710d80e Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Wed, 7 Feb 2018 13:08:42 -0800 Subject: Clarify style of attribute comments in the Design Guide. And update the core attributes to match the style. --- docs/design_guide.rst | 129 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 98 insertions(+), 31 deletions(-) (limited to 'docs') 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 -------------------------------------------------------------------------------- -- cgit v1.2.3