From 7a4cfb53ce1e44ea5c8d8a56dc7a172f7dcbdb1c Mon Sep 17 00:00:00 2001
From: Carlos Pereira Atencio <carlos@microbit.org>
Date: Fri, 12 Apr 2024 11:56:41 +0100
Subject: [PATCH] docs: Improve microphone description, add more info for
 `set_threshold()`. (#804)

* docs: Improve descriptions for microphone module.

* docs: Add more info to `microphone.set_threshold()`.
---
 docs/microphone.rst | 67 +++++++++++++++++++++++++++++----------------
 1 file changed, 44 insertions(+), 23 deletions(-)

diff --git a/docs/microphone.rst b/docs/microphone.rst
index 3cc74c8e9..88a847031 100644
--- a/docs/microphone.rst
+++ b/docs/microphone.rst
@@ -17,7 +17,7 @@ which is lit when the microphone is in use.
 Sound events
 ============
 The microphone can respond to a pre-defined set of sound events that are
-based on the amplitude and wavelength of the sound. 
+based on the amplitude and wavelength of the sound.
 
 These sound events are represented by instances of the ``SoundEvent`` class,
 accessible via variables in ``microbit.SoundEvent``:
@@ -33,42 +33,63 @@ Functions
 
 .. py:function:: current_event()
 
-    * **return**: the name of the last recorded sound event,
-      ``SoundEvent('loud')`` or ``SoundEvent('quiet')``.
+    Get the last recorded sound event.
+
+    :return: The event, ``SoundEvent('loud')`` or ``SoundEvent('quiet')``.
 
 .. py:function:: was_event(event)
 
-    * **event**: a sound event,  such as ``SoundEvent.LOUD`` or
-      ``SoundEvent.QUIET``.
-    * **return**: ``true`` if sound was heard at least once since the last
-      call, otherwise ``false``. ``was_event()`` also clears the sound
-      event history before returning.
+    Check if a sound was heard at least once since the last call.
+
+    This call clears the sound history before returning.
+
+    :param event: The event to check for,  such as ``SoundEvent.LOUD`` or
+        ``SoundEvent.QUIET``.
+    :return: ``True`` if sound was heard at least once since the last call,
+        otherwise ``False``.
 
 .. py:function:: is_event(event)
 
-    * **event**: a sound event,  such as ``SoundEvent.LOUD`` or
-      ``SoundEvent.QUIET``.
-    * **return**: ``true`` if sound event is the most recent since the last
-      call, otherwise ``false``. It does not clear the sound event history.
+    Check the most recent sound event detected.
+
+    This call does not clear the sound event history.
+
+    :param event: The event to check for,  such as ``SoundEvent.LOUD`` or
+        ``SoundEvent.QUIET``
+    :return: ``True`` if sound was the most recent heard, ``False`` otherwise.
 
 .. py:function:: get_events()
 
-    * **return**: a tuple of the event history. The most recent is listed last.
-      ``get_events()`` also clears the sound event history before returning.
+    Get the sound event history as a tuple.
+
+    This call clears the sound history before returning.
+
+    :return: A tuple of the event history with the most recent event last.
 
 .. py:function:: set_threshold(event, value)
 
-    * **event**: a sound event, such as ``SoundEvent.LOUD`` or
-      ``SoundEvent.QUIET``.
-    
-    * **value**: The threshold level in the range 0-255. For example,
-      ``set_threshold(SoundEvent.LOUD, 250)`` will only trigger if the sound is
-      very loud (>= 250).
+    Set the threshold for a sound event.
+
+    The ``SoundEvent.LOUD`` event will be triggered when the sound level
+    crosses this threshold upwards (from "quiet" to "loud"),
+    and ``SoundEvent.QUIET`` event is triggered when crossing the threshold
+    downwards (from "loud" to "quiet").
+
+    If the ``SoundEvent.LOUD`` value set is lower than ``SoundEvent.QUIET``,
+    then "quiet" threshold will be decreased to one unit below the "loud"
+    threshold. If the ``SoundEvent.QUIET`` value is set higher than
+    ``SoundEvent.LOUD``, then the "loud" threshold will be set one unit above.
+
+    :param event: A sound event, such as ``SoundEvent.LOUD`` or
+        ``SoundEvent.QUIET``.
+    :param value: The threshold level in the range 0-255. Values outside this
+        range will be clamped.
 
 .. py:function:: sound_level()
 
-    * **return**: a representation of the sound pressure level in the range 0 to
-      255.
+    Get the sound pressure level.
+
+    :return: A representation of the sound pressure level in the range 0 to 255.
 
 
 Example
@@ -80,7 +101,7 @@ An example that runs through some of the functions of the microphone API::
     # Button A is pressed and a loud or quiet sound *is* heard, printing the
     # results. On Button B this test should update the display when a loud or
     # quiet sound *was* heard, printing the results. On shake this should print
-    # the last sounds heard, you should try this test whilst making a loud sound 
+    # the last sounds heard, you should try this test whilst making a loud sound
     # and a quiet one before you shake.
 
     from microbit import *