Clarify style of attribute comments in the Design Guide.

And update the core attributes to match the style.

1 files changed, 6 insertions, 13 deletions

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