docs: Audio also inside microbit module & AudioFrame.copyfrom() info. (…

…#740)

* docs: Docstring notation to audio & add it's also in microbit module.

Also adds docs for AudioFrame.copyfrom().

And backports the tweaks in the Technical Details section from
the V2 docs commit
38403c0#diff-1eb5832ad8abd778154545f6342a1327ba414d6f61c082d12352b56c511757e1R90

* Update docs/audio.rst

docs/audio.rst

@@ -3,7 +3,11 @@ Audio
 
 .. py:module:: audio
 
-This module allows you play sounds from a speaker attached to the Microbit.
+This module allows you play sounds from a speaker attached to the micro:bit.
+
+The ``audio`` module can be imported as ``import audio`` or accessed via
+the ``microbit`` module as ``microbit.audio``.
+
 In order to use the audio module you will need to provide a sound source.
 
 A sound source is an iterable (sequence, like list or tuple, or a generator) of
@@ -18,14 +22,13 @@ Functions
 
     Play the source to completion.
 
-    ``source`` is an iterable, each element of which must be an ``AudioFrame``.
-
-    If ``wait`` is ``True``, this function will block until the source is exhausted.
-
-    ``pin`` specifies which pin the speaker is connected to.
-
-    ``return_pin`` specifies a differential pin to connect to the speaker
-    instead of ground.
+    :param source: An iterable sound source, each element of which must be
+        an ``AudioFrame``.
+    :param wait: If ``wait`` is ``True``, this function will block until the
+        source is exhausted.
+    :param pin: Specifies which pin the speaker is connected to.
+    :param return_pin: Specifies a differential pin to connect to the speaker
+        instead of ground.
 
 Classes
 =======
@@ -38,6 +41,14 @@ Classes
 
     It takes just over 4 ms to play a single frame.
 
+    .. py:function:: copyfrom(other)
+
+        Overwrite the data in this ``AudioFrame`` with the data from another
+        ``AudioFrame`` instance.
+
+        :param other: ``AudioFrame`` instance from which to copy the data.
+
+
 Using audio
 ===========
 
@@ -52,18 +63,20 @@ Technical Details
     You don't need to understand this section to use the ``audio`` module.
     It is just here in case you wanted to know how it works.
 
-The ``audio`` module consumes samples at 7812.5 Hz, and uses linear interpolation to
-output a PWM signal at 32.5 kHz, which gives tolerable sound quality.
+The ``audio`` module consumes ``AudioFrame`` samples at 7812.5 Hz, and uses
+linear interpolation to output a PWM signal at 32.5 kHz, which gives tolerable
+sound quality.
 
 The function ``play`` fully copies all data from each ``AudioFrame`` before it
-calls ``next()`` for the next frame, so a sound source can use the same ``AudioFrame``
-repeatedly.
-
-The ``audio`` module has an internal 64 sample buffer from which it reads samples.
-When reading reaches the start or the mid-point of the buffer, it triggers a callback to
-fetch the next ``AudioFrame`` which is then copied into the buffer.
-This means that a sound source has under 4ms to compute the next ``AudioFrame``,
-and for reliable operation needs to take less 2ms (which is 32000 cycles, so should be plenty).
+calls ``next()`` for the next frame, so a sound source can use the same
+``AudioFrame`` repeatedly.
+
+The ``audio`` module has an internal 64 sample buffer from which it reads
+samples. When reading reaches the start or the mid-point of the buffer, it
+triggers a callback to fetch the next ``AudioFrame`` which is then copied into
+the buffer. This means that a sound source has under 4ms to compute the next
+``AudioFrame``, and for reliable operation needs to take less 2ms (which is
+32000 cycles, so should be plenty).
 
 
 Example