On start support (#324)

* annotating APIs to support onstart

* missed file

* updated templates

* adding new lines in main.ts

* fixing docs

* removing onstart

* updated docs

* updated various docs

* more docs

* adding upgrade policies for blocks

* updated pxt reference

* placing on start under "basic"

docs/blocks/logic/boolean.md

@@ -86,12 +86,14 @@ if (led.point(1,1) && led.point(2,2)) {
 When you compare two Numbers, you get a Boolean value, such as the comparison `x < 5` in the code below:
 
 ```blocks
-let x = Math.random(5)
-if(x < 5) {
-   basic.showString("low");
-} else { 
-   basic.showString("high");
-} 
+input.onButtonPressed(Button.A, () => {
+    let x = Math.random(5)
+    if(x < 5) {
+    basic.showString("low");
+    } else { 
+    basic.showString("high");
+    }
+})
 ```
 
 See the documentation on [Numbers](/reference/types/number) for more information on comparing two Numbers. You can also [compare strings](/reference/types/string-functions) using the `equals` function.

docs/blocks/logic/if.md

@@ -14,13 +14,15 @@ Click on the dark blue gear icon (see above) to add an *else* or *if* to the cur
 
 ### Example: adjusting screen brightness
 
-```blocks
-if(input.lightLevel()<100){
-    led.setBrightness(255);
-}
-```
+If the [light level](/reference/input/light-level) is `< 100`, this code sets the brightness to `255` when the button A is pressed:
 
-If the [light level](/reference/input/light-level) is `< 100`, this code sets the brightness to `255`:
+```blocks
+input.onButtonPressed(Button.A, () => {
+    if(input.lightLevel()<100){
+        led.setBrightness(255);
+    }
+})
+```
 
 ### See also
 

docs/blocks/loops/for.md

@@ -4,14 +4,21 @@
  
 Run part of the program the number of times you say.
 
+```block
+for(let i = 0; i <= 4; ++i) {
+}
+```
+
 ### Example: Count to 4
 
 This program will show the numbers 0, 1, 2, 3, and 4 one after another on the LED screen.
 
 ```blocks
-for(let i = 0; i < 5; ++i) {
-basic.showNumber(i)
-}
+input.onButtonPressed(Button.A, () => {
+    for(let i = 0; i < 5; ++i) {
+        basic.showNumber(i)
+    }
+})
 ```
 
 ### See also

docs/blocks/loops/while.md

@@ -2,7 +2,7 @@
 
 Repeat code while a [Boolean](/blocks/logic/boolean) `condition` is true.
 
-```blocks
+```block
 while(true) {
 }
 ```
@@ -16,11 +16,13 @@ The condition is tested before any code runs. Which means that if the condition
 The following example uses a while loop to make a diagonal line on the LED screen (points `0, 0`, `1, 1`, `2, 2`, `3, 3`, `4, 4`).
 
 ```blocks
-let index = 4;
-while(index >= 0) {
-    led.plot(index, index);
-    index--;
-}
+input.onButtonPressed(Button.A, () => {
+    let index = 4;
+    while(index >= 0) {
+        led.plot(index, index);
+        index--;
+    }
+})
 ```
 
 ### See also

docs/blocks/on-start.md

@@ -0,0 +1,22 @@
+# On Start
+
+An event that runs when the program starts.
+
+The ``on start`` is a special event that runs when the program starts, before any other event. 
+Use this event to initialize your program.
+
+## Example
+
+In this example, ``on start`` sets a dimmer brightness on the screen and the button handler shows a string.
+
+```blocks
+input.onButtonPressed(Button.A, () => {
+    basic.showString("Hello!")
+})
+led.setBrightness(50)
+```
+
+
+## What about JavaScript?
+
+``on-start`` only exists in the block editor. In JavaScript, all code executes sequentially from the first line.