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. --- shared-bindings/analogio/AnalogIn.c | 15 +++++---------- shared-bindings/analogio/AnalogOut.c | 9 +++------ shared-bindings/audioio/AudioOut.c | 2 +- shared-bindings/digitalio/DigitalInOut.c | 14 ++++++++++---- shared-bindings/microcontroller/Processor.c | 20 ++++++++++---------- shared-bindings/pulseio/PulseIn.c | 2 +- shared-bindings/touchio/TouchIn.c | 19 ++++++------------- shared-bindings/usb_hid/Device.c | 13 ++++--------- 8 files changed, 40 insertions(+), 54 deletions(-) (limited to 'shared-bindings') 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); -- cgit v1.2.3