From 6524b0a8413da26f490619fbcb380186c7c217ca Mon Sep 17 00:00:00 2001
From: Galen Nickel <v-ganick@microsoft.com>
Date: Thu, 22 Feb 2018 14:56:15 -0800
Subject: [PATCH 1/3] Add 'timer' api docs (#339)

---
 docs/SUMMARY.md                             |  6 +++
 docs/reference.md                           |  6 +--
 docs/reference/control.md                   | 33 ++++++++++++++
 docs/reference/control/timer.md             |  8 ++++
 docs/reference/control/timer/millis.md      | 25 +++++++++++
 docs/reference/control/timer/pause-until.md | 32 ++++++++++++++
 docs/reference/control/timer/reset.md       | 49 +++++++++++++++++++++
 docs/reference/control/timer/seconds.md     | 25 +++++++++++
 libs/core/timer.ts                          | 14 +++---
 9 files changed, 190 insertions(+), 8 deletions(-)
 create mode 100644 docs/reference/control.md
 create mode 100644 docs/reference/control/timer.md
 create mode 100644 docs/reference/control/timer/millis.md
 create mode 100644 docs/reference/control/timer/pause-until.md
 create mode 100644 docs/reference/control/timer/reset.md
 create mode 100644 docs/reference/control/timer/seconds.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 645a9292..e8ffade5 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -111,3 +111,9 @@
             * [pause for light](/reference/sensors/color-sensor/pause-for-light)
             * [color](/reference/sensors/color-sensor/color)
             * [light](/reference/sensors/color-sensor/ambient-light)
+    * [Control](/reference/control)
+        * [Timer](/reference/control/timer)
+            * [seconds](/reference/control/timer/seconds)
+            * [millis](/reference/control/timer/millis)
+            * [reset](/reference/control/timer/reset)
+            * [pause until](/reference/control/timer/pause-until)
diff --git a/docs/reference.md b/docs/reference.md
index 92cbabc2..d3183aa6 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -1,9 +1,10 @@
 # Reference
 
 ```namespaces
-brick.showMood(moods.sleeping);
+control.runInParallel(function(){});
 sensors.color(null);
 motors.stopAll();
+brick.showMood(moods.sleeping);
 ```
 
 ## See Also
@@ -11,5 +12,4 @@ motors.stopAll();
 [brick](/reference/brick),
 [sensors](/reference/sensors),
 [motors](/reference/motors),
-[touch sensor](/reference/sensors/touch-sensor),
-[color sensor](/reference/sensors/color-sensor)
\ No newline at end of file
+[control](/reference/control)
diff --git a/docs/reference/control.md b/docs/reference/control.md
new file mode 100644
index 00000000..9c780657
--- /dev/null
+++ b/docs/reference/control.md
@@ -0,0 +1,33 @@
+# Control
+
+Program controls and events.
+
+```cards
+control.millis();
+control.runInParallel(() => {
+    
+});
+control.reset();
+control.waitMicros(4);
+control.deviceSerialNumber();
+```
+
+## Timer
+
+```cards
+control.timer1.reset()
+control.timer1.pauseUntil(5)
+control.timer1.millis()
+control.timer1.seconds()
+```
+
+## Advanced #advanced
+
+```cards
+control.raiseEvent(0, 0);
+control.onEvent(0, 0, () => {
+    
+});
+control.assert(false, 0);
+control.panic(0);
+```
\ No newline at end of file
diff --git a/docs/reference/control/timer.md b/docs/reference/control/timer.md
new file mode 100644
index 00000000..c97c4c39
--- /dev/null
+++ b/docs/reference/control/timer.md
@@ -0,0 +1,8 @@
+# Timer
+
+```cards
+control.timer1.reset()
+control.timer1.pauseUntil(5)
+control.timer1.millis()
+control.timer1.seconds()
+```
diff --git a/docs/reference/control/timer/millis.md b/docs/reference/control/timer/millis.md
new file mode 100644
index 00000000..90d4d2b2
--- /dev/null
+++ b/docs/reference/control/timer/millis.md
@@ -0,0 +1,25 @@
+# millis
+
+Get the amount of time counted by the timer in milliseconds.
+
+The timer count begins from `0` when you program starts or is [reset](/reference/control/timer/reset). 
+
+## Returns
+
+* a [number](/types/number) that is the amount of time elapsed, in milliseconds, since the timer was started or reset.
+
+## Example
+
+Find out how many milliseconds go by between presses of the `down` button on the brick.
+
+```blocks
+brick.buttonDown.onEvent(ButtonEvent.Pressed, function () {
+    brick.showValue("DownButtonTime", control.timer1.millis(), 1)
+    control.timer1.reset()
+})
+```
+
+## See also
+
+[seconds](/reference/control/timer/seconds), [reset](/reference/control/timer/reset)
+
diff --git a/docs/reference/control/timer/pause-until.md b/docs/reference/control/timer/pause-until.md
new file mode 100644
index 00000000..47c1c897
--- /dev/null
+++ b/docs/reference/control/timer/pause-until.md
@@ -0,0 +1,32 @@
+# pauseUntil
+
+Pause until the timer counts up to a number of milliseconds.
+
+```sig
+control.timer1.pauseUntil(0)
+```
+
+When code in a block comes to a **pauseUntil**, it will wait until the timer count reaches the number of milliseconds you say. Code in blocks like **forever** and **runInParallel** will keep running while the current code is paused.
+
+The time number you give is the number of milliseconds past the running timer count. If the timer is currently at `25000` milliseconds and you want to pause for `10` seconds, then use a pause time of `35000`. If you want your pause time number to match the actual wait time, then [reset](/reference/control/timer/reset) the timer first.
+
+## Parameters
+
+* **ms**: the [number](/types/number) of milliseconds that you want the timer to count up to. For seconds, convert to milliseconds: 100 milliseconds = 1/10 second and 1000 milliseconds = 1 second.
+
+## Example
+
+Pause between messages on the screen by `5` seconds.
+
+```blocks
+brick.clearScreen()
+brick.showString("Testing my pause...", 1)
+let startTime = control.timer1.millis()
+brick.showValue("StartTime", startTime, 3)
+control.timer1.pauseUntil(startTime + 5000)
+brick.showValue("EndTime", control.timer1.millis() - startTime, 4)
+```
+
+## See also
+
+[millis](/reference/control/timer/millis), [reset](/reference/control/timer/reset)
diff --git a/docs/reference/control/timer/reset.md b/docs/reference/control/timer/reset.md
new file mode 100644
index 00000000..1031f9ce
--- /dev/null
+++ b/docs/reference/control/timer/reset.md
@@ -0,0 +1,49 @@
+# reset
+
+Reset the elapsed time of the timer back to `0`.
+
+```sig
+control.timer1.reset()
+```
+
+A timer starts counting from `0` when your program starts. It's time value always gets larger as your program runs. Maybe you want to meausure how long some task takes to finish or you want to do some action  only for a little while. A timer can keep track of the time it takes to do it.
+
+Resetting the timer sets the time value to `0` so the next time you check the time it's exactly the amount of time that has _elapsed_. Otherwise, you need to remember a start time value and then subtract it from the current time. 
+
+## Examples
+
+### Press time
+
+Find out how much time goes by between presses of the `enter` button on the brick.
+
+```blocks
+brick.buttonEnter.onEvent(ButtonEvent.Pressed, function () {
+    brick.showValue("PressTime", control.timer1.seconds(), 1)
+    control.timer1.reset()
+})
+```
+
+### Difference timer
+
+Use a difference timer and compare it to a timer that resets. Use the ``left`` button to start timing and the ``right`` button to stop.
+
+```blocks
+let startTime = 0
+let timing = false
+brick.buttonLeft.onEvent(ButtonEvent.Pressed, function () {
+    brick.clearScreen()
+    brick.showString("Starting timers...", 1)
+    startTime = control.timer1.seconds()
+    control.timer2.reset()
+    timing = true
+})
+brick.buttonRight.onEvent(ButtonEvent.Pressed, function () {
+    if (timing) {
+        brick.clearScreen()
+        brick.showString("Timer results...", 1)
+        brick.showValue("timer 1", control.timer1.seconds() - startTime, 3)
+        brick.showValue("timer 2", control.timer2.seconds(), 4)
+        timing = false;
+    }
+})
+```
\ No newline at end of file
diff --git a/docs/reference/control/timer/seconds.md b/docs/reference/control/timer/seconds.md
new file mode 100644
index 00000000..21c0d85c
--- /dev/null
+++ b/docs/reference/control/timer/seconds.md
@@ -0,0 +1,25 @@
+# seconds
+
+Get the amount of time counted by the timer in seconds.
+
+The timer count begins from `0` when you program starts or is [reset](/reference/control/timer/reset). The number of seconds returned also includes milliseconds if there is a fractional part of a second too.
+
+## Returns
+
+* a [number](/types/number) that is the amount of time elapsed, in seconds, since the timer was started or reset.
+
+## Example
+
+Find out how many seconds go by between presses of the `down` button on the brick.
+
+```blocks
+brick.buttonDown.onEvent(ButtonEvent.Pressed, function () {
+    brick.showValue("DownButtonTime", control.timer1.seconds(), 1)
+    control.timer1.reset()
+})
+```
+
+## See also
+
+[millis](/reference/control/timer/millis), [reset](/reference/control/timer/reset)
+
diff --git a/libs/core/timer.ts b/libs/core/timer.ts
index 3fe0e16d..2db3bfdc 100644
--- a/libs/core/timer.ts
+++ b/libs/core/timer.ts
@@ -11,36 +11,40 @@ namespace control {
         }
 
         /**
-         * Gets the elapsed time in millis since the last reset
+         * Get the elapsed time in millis since the last reset
          */
         //% blockId=timerMillis block="%timer|millis"
+        //% help=control/timer/millis
         millis(): number {
             return control.millis() - this.start;
         }
         
         /**
-         * Gets the elapsed time in seconds since the last reset
+         * Get the elapsed time in seconds since the last reset
          */
         //% blockId=timerSeconds block="%timer|seconds"
+        //% help=control/timer/seconds
         seconds(): number {
             return this.millis() / 1000;
         }
 
         /**
-         * Resets the timer
+         * Reset the timer
          */
         //% blockId=timerRest block="%timer|reset"
+        //% help=control/timer/reset
         reset() {
             this.start = control.millis();
         }
 
         /**
-         * Pauses until the timer reaches the given amount of milliseconds
+         * Pause until the timer reaches the given amount of milliseconds
          * @param ms how long to pause for, eg: 5, 100, 200, 500, 1000, 2000
          */
         //% blockId=timerPauseUntil block="%timer|pause until (ms) %ms"
+        //% help=control/timer/pause-until
         pauseUntil(ms: number) {
-            const remaining = this.millis() - ms;
+            const remaining = ms - this.millis();
             pause(Math.max(0, remaining));
         }
     }

From 60ec3f1c99636095baabed189d8f5fdf1e7be1eb Mon Sep 17 00:00:00 2001
From: Galen Nickel <v-ganick@microsoft.com>
Date: Thu, 22 Feb 2018 16:23:07 -0800
Subject: [PATCH 2/3] Add 'playSound' api docs (#340)

* Add 'playSound' api docs

* Linkup summary
---
 docs/SUMMARY.md                               | 12 +++++
 libs/music/docs/reference/music.md            | 15 ++++++
 .../music/play-sound-effect-until-done.md     | 54 +++++++++++++++++++
 .../docs/reference/music/play-sound-effect.md | 29 ++++++++++
 libs/music/sounds.ts                          |  4 +-
 5 files changed, 113 insertions(+), 1 deletion(-)
 create mode 100644 libs/music/docs/reference/music.md
 create mode 100644 libs/music/docs/reference/music/play-sound-effect-until-done.md
 create mode 100644 libs/music/docs/reference/music/play-sound-effect.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index e8ffade5..880e1b33 100644
--- a/docs/SUMMARY.md
+++ b/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)
diff --git a/libs/music/docs/reference/music.md b/libs/music/docs/reference/music.md
new file mode 100644
index 00000000..b722fe1c
--- /dev/null
+++ b/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)
+```
\ No newline at end of file
diff --git a/libs/music/docs/reference/music/play-sound-effect-until-done.md b/libs/music/docs/reference/music/play-sound-effect-until-done.md
new file mode 100644
index 00000000..55981e8a
--- /dev/null
+++ b/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)
\ No newline at end of file
diff --git a/libs/music/docs/reference/music/play-sound-effect.md b/libs/music/docs/reference/music/play-sound-effect.md
new file mode 100644
index 00000000..af9e7937
--- /dev/null
+++ b/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)
\ No newline at end of file
diff --git a/libs/music/sounds.ts b/libs/music/sounds.ts
index b073970f..6d2f35a1 100644
--- a/libs/music/sounds.ts
+++ b/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++;

From 8ee63df325b80cabea66c6cc127e7f32e9775963 Mon Sep 17 00:00:00 2001
From: Galen Nickel <v-ganick@microsoft.com>
Date: Fri, 23 Feb 2018 14:13:08 -0800
Subject: [PATCH 3/3] Add in 'console' doc stuff  (#342)

* Add 'playSound' api docs

* Add in 'console' doc stuff

* Add 'send to screen' in summary\
---
 docs/SUMMARY.md                          |  4 ++++
 docs/reference.md                        | 11 ++++++++--
 docs/reference/console.md                | 15 ++++++++++++++
 docs/reference/console/send-to-screen.md | 26 ++++++++++++++++++++++++
 libs/core/console.ts                     |  1 +
 libs/core/control.cpp                    |  1 +
 6 files changed, 56 insertions(+), 2 deletions(-)
 create mode 100644 docs/reference/console.md
 create mode 100644 docs/reference/console/send-to-screen.md

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 880e1b33..73de5498 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -129,3 +129,7 @@
             * [millis](/reference/control/timer/millis)
             * [reset](/reference/control/timer/reset)
             * [pause until](/reference/control/timer/pause-until)
+    * [Console](/reference/console)
+        * [log](/reference/console/log)
+        * [log value](/reference/console/log-value)
+        * [send to screen](/reference/console/send-to-screen)
diff --git a/docs/reference.md b/docs/reference.md
index d3183aa6..f0f57d82 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -1,15 +1,22 @@
 # Reference
 
 ```namespaces
-control.runInParallel(function(){});
 sensors.color(null);
 motors.stopAll();
 brick.showMood(moods.sleeping);
 ```
 
+## Advanced
+
+```namespaces
+console.log("");
+control.runInParallel(function(){});
+```
+
 ## See Also
 
 [brick](/reference/brick),
 [sensors](/reference/sensors),
 [motors](/reference/motors),
-[control](/reference/control)
+[control](/reference/control),
+[console](/reference/console)
diff --git a/docs/reference/console.md b/docs/reference/console.md
new file mode 100644
index 00000000..2f6a086d
--- /dev/null
+++ b/docs/reference/console.md
@@ -0,0 +1,15 @@
+# Console
+
+Output text and data values to the console.
+
+```cards
+console.log("");
+console.logValue("x", 0);
+console.sendToScreen();
+```
+
+## See also
+
+[log](/reference/console/log),
+[log value](/reference/console/log-value),
+[send to screen](/reference/console/send-to-screen)
diff --git a/docs/reference/console/send-to-screen.md b/docs/reference/console/send-to-screen.md
new file mode 100644
index 00000000..2e63bf6a
--- /dev/null
+++ b/docs/reference/console/send-to-screen.md
@@ -0,0 +1,26 @@
+# send To Screen
+
+Direct the console output to go to the @boardname@ screen.
+
+```sig
+console.sendToScreen();
+```
+
+A "console" is a place for a user to see special messages from a device. It could be  something connected to a serial port, a display that shows text, or even a text file. A console is typically used as a place to send information that is added to a message _log_ (a record of messages that are sent from a device). Your program can send log messages using the [console](/reference/console) functions. The MakeCode editor has a console view that lets you see the console output when your program runs in the simulator.
+
+On the @boardname@, the screen can serve as a console too and you can make your console output go there. Before using the console log functions, set the screen as the console output location.
+
+## Example
+
+Direct the console output to go to the screen. Show 20 values on the screen. Use the up and down buttons to scroll through the values.
+
+```blocks
+console.sendToScreen()
+for (let index = 0; index <= 20; index++) {
+    console.logValue("index", index)
+}
+```
+
+## See also
+
+[log](reference/console/log), [log value](/reference/console/log-value)
\ No newline at end of file
diff --git a/libs/core/console.ts b/libs/core/console.ts
index 5f0a6afe..3e065fbe 100644
--- a/libs/core/console.ts
+++ b/libs/core/console.ts
@@ -51,6 +51,7 @@ namespace console {
      */
     //% blockId=logsendtostreen block="send console to screen"
     //% weight=1
+    //% help=console/send-to-screen
     export function sendToScreen(): void {
         console.screen.attach();
     }
diff --git a/libs/core/control.cpp b/libs/core/control.cpp
index 5005089d..2b53bada 100644
--- a/libs/core/control.cpp
+++ b/libs/core/control.cpp
@@ -10,6 +10,7 @@ namespace control {
  */
 //% weight=21 blockGap=12 blockId="control_raise_event"
 //% block="raise event|from %src|with value %value" blockExternalInputs=1
+//% help=control/raise-event
 void raiseEvent(int src, int value) {
     pxt::raiseEvent(src, value);
 }