docs: Improve microphone description, add more info for `set_threshol…

…d()`. (#804)

* docs: Improve descriptions for microphone module.

* docs: Add more info to `microphone.set_threshold()`.

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 *