Add 'playSound' api docs (#340)

* Add 'playSound' api docs

* Linkup summary

docs/SUMMARY.md

@@ -111,6 +111,18 @@
             * [pause for light](/reference/sensors/color-sensor/pause-for-light)
             * [color](/reference/sensors/color-sensor/color)
             * [light](/reference/sensors/color-sensor/ambient-light)
+    * [Music](/reference/music)
+        * [play sound effect](/reference/music/play-sound-effect)
+        * [play sound effect until done](/reference/music/play-sound-effect-until-done)
+        * [play tone](/reference/music/play-tone)
+        * [ring tone](/reference/music/ring-tone)
+        * [stop all sounds](/reference/music/stop-all-sounds)
+        * [rest](/reference/music/rest)
+        * [change tempo by](/reference/music/change-tempo-by)
+        * [set tempo](/reference/music/set-tempo)
+        * [note frequency](/reference/music/note-frequency)
+        * [beat](/reference/music/beat)
+        * [set volume](/reference/music/set-volume)
     * [Control](/reference/control)
         * [Timer](/reference/control/timer)
             * [seconds](/reference/control/timer/seconds)

libs/music/docs/reference/music.md

@@ -0,0 +1,15 @@
+# Music
+
+```cards
+music.playSoundEffect(null)
+music.playSoundEffectUntilDone(null)
+music.stopAllSounds()
+music.playTone(0, 0)
+music.ringTone(Note.C)
+music.rest(100)
+music.changeTempoBy(20)
+music.setTempo(120)
+music.noteFrequency(Note.C)
+music.beat()
+music.setVolume(50)
+```

libs/music/docs/reference/music/play-sound-effect-until-done.md

@@ -0,0 +1,54 @@
+# play Sound Effect Until Done
+
+Play a sound from one of the built-in sound effect until it completes.
+
+```sig
+music.playSoundEffectUntilDone(null)
+```
+
+There are several sound effects you can play. Use the sounds list in the block to pick the sound you want to play. The sound plays and this part of your program waits until the sound finishes. Other parts of your program, like code in **forever** loops and **runInParallel** blocks will continue to run though.
+
+Many of the built-in sound effects make sounds match to the actions that your @boardname@ is doing. For example, you can add the ``mechanical motor start`` sound your program to indicate that your motors are running.
+
+## Parameters
+
+* **sound**: a built-in sound effect from the list of available sounds.
+
+## Example
+
+Make a game where the buttons on the brick are used to guess a number from `1` to `4` that your program randomly chooses. On the correct guess, flash a ``green`` status light and play a cheering sound. The ``enter`` button resets the game to play again.
+
+```blocks
+let pick = 0
+brick.buttonEnter.onEvent(ButtonEvent.Pressed, function () {
+    pick = 0
+    music.stopAllSounds()
+    brick.setStatusLight(StatusLight.Off)
+})
+brick.buttonDown.onEvent(ButtonEvent.Pressed, function () {
+    pick = 1
+})
+brick.buttonLeft.onEvent(ButtonEvent.Pressed, function () {
+    pick = 2
+})
+brick.buttonRight.onEvent(ButtonEvent.Pressed, function () {
+    pick = 3
+})
+brick.buttonUp.onEvent(ButtonEvent.Pressed, function () {
+    pick = 4
+})
+forever(function () {
+    if (pick > 0) {
+        if (Math.randomRange(0, 3) + 1 == pick) {
+            brick.setStatusLight(StatusLight.GreenFlash)
+            music.playSoundEffectUntilDone(sounds.expressionsCheering)
+        }
+        pick = 0
+    }
+    pause(300)
+})
+```
+
+## See also
+
+[play sound effect](/reference/music/play-sound-effect), [stop all sounds](/reference/music/stop-all-sounds)

libs/music/docs/reference/music/play-sound-effect.md

@@ -0,0 +1,29 @@
+# play Sound Effect
+
+Play a sound from one of the built-in sound effects.
+
+```sig
+music.playSoundEffect(null)
+```
+
+There are several sound effects you can play. Use the sounds list in the block to pick the sound you want to play. When the sounds starts, your program continues on and doesn't wait for the sound to finish. This lets your program do other things while your sound plays in the _background_.
+
+Many of the built-in sound effects make sounds match to the actions that your @boardname@ is doing. For example, you can add the ``mechanical motor start`` sound to your program to indicate that your motors are running.
+
+## Parameters
+
+* **sound**: a built-in sound effect from the list of available sounds.
+
+## Example
+
+Drive the brick backwards and play a backup alert sound.
+
+```blocks
+music.playSoundEffect(sounds.mechanicalBackingAlert);
+motors.largeBC.tank(-50, -50, 15, MoveUnit.Rotations);
+music.stopAllSounds();
+```
+
+## See also
+
+[play sound effect until done](/reference/music/play-sound-effect-until-done), [stop all sounds](/reference/music/stop-all-sounds)

libs/music/sounds.ts

@@ -260,11 +260,12 @@ namespace music {
     const soundsLimit = 1;
 
     /**
-     * Plays a sound
+     * Play a sound and wait until it finishes
      * @param sound the sound to play
      */
     //% blockId=music_play_sound_effect_until_done block="play sound effect %sound|until done"
     //% weight=98 blockGap=8
+    //% help=music/play-sound-effect-until-done
     export function playSoundEffectUntilDone(sound: Sound) {
         if (!sound || numSoundsPlaying >= soundsLimit) return;
         numSoundsPlaying++;
@@ -288,6 +289,7 @@ namespace music {
      */
     //% blockId=music_play_sound_effect block="play sound effect %sound"
     //% weight=99 blockGap=8
+    //% help=music/play-sound-effect
     export function playSoundEffect(sound: Sound) {
         if (!sound || numSoundsPlaying >= soundsLimit) return;
         numSoundsPlaying++;