From efca68672a092a99c4232a7ce01529b23d6f0251 Mon Sep 17 00:00:00 2001
From: Sam El-Husseini <samelh@microsoft.com>
Date: Tue, 6 Dec 2016 00:34:42 -0800
Subject: [PATCH 1/7] Support for monaco toolbox

---
 theme/style.less | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/theme/style.less b/theme/style.less
index 3fa6d9a2..fafb388a 100644
--- a/theme/style.less
+++ b/theme/style.less
@@ -73,12 +73,12 @@
 }
 
 /* Blockly Toolbox Buttons */
-#blocklyToolboxButtons .blocklyAddPackageButton {
+.blocklyToolboxButtons .blocklyAddPackageButton {
     &:extend(.ui.inverted.pink.button all);
     &:extend(.circular all);
 }
 
-#blocklyToolboxButtons .blocklyUndoButton {
+.blocklyToolboxButtons .blocklyUndoButton {
     &:extend(.ui.inverted.blue.button all);
     &:extend(.circular all);
 }

From cfc3eae77c4d137fa09ea8c445c706389fbed4f2 Mon Sep 17 00:00:00 2001
From: Sam El-Husseini <samelh@microsoft.com>
Date: Wed, 7 Dec 2016 17:03:28 -0800
Subject: [PATCH 2/7] adding monacotoolboxbuttons margin

---
 theme/style.less | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/theme/style.less b/theme/style.less
index f9342769..6aac8106 100644
--- a/theme/style.less
+++ b/theme/style.less
@@ -117,7 +117,7 @@
         top: auto;
     }
     /* Blockly Toolbox buttons */
-    #blocklyToolboxButtons {
+    #blocklyToolboxButtons, #monacoToolboxButtons {
         margin-right: 0.5rem;
         margin-left: 0.5rem;
     }
@@ -129,7 +129,7 @@
         top: auto;
     }
     /* Blockly Toolbox buttons */
-    #blocklyToolboxButtons {
+    #blocklyToolboxButtons, #monacoToolboxButtons {
         margin-right: 1rem;
         margin-left: 1rem;
     }
@@ -142,7 +142,7 @@
         padding-left: 1rem;
     }
     /* Blockly Toolbox buttons */
-    #blocklyToolboxButtons {
+    #blocklyToolboxButtons, #monacoToolboxButtons {
         margin-right: 2rem;
         margin-left: 2rem;
     }

From fe5c8e520a057bdb46b5725b9f23bd9a46b0f08a Mon Sep 17 00:00:00 2001
From: Sam El-Husseini <samelh@microsoft.com>
Date: Sun, 11 Dec 2016 06:34:11 +1300
Subject: [PATCH 3/7] monaco draggable block

---
 theme/style.less   | 9 +++++++--
 theme/theme.config | 2 +-
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/theme/style.less b/theme/style.less
index 6aac8106..708e4567 100644
--- a/theme/style.less
+++ b/theme/style.less
@@ -60,8 +60,8 @@
 }
 
 .blocklyFlyoutBackground {
-    fill: #525A67 !important;
-    fill-opacity: 0.5 !important;
+    fill: #fff !important;
+    fill-opacity: 0.8 !important;
 }
 
 /* Remove shadow around blockly blocks */
@@ -92,6 +92,11 @@
     background: #ecf0f1;
 }
 
+.monacoDraggableBlock {
+    background: #ecf0f1;
+    border: solid 3px #ecf0f1;
+}
+
 .monaco-editor-background {
     background: #ecf0f1;
 }
diff --git a/theme/theme.config b/theme/theme.config
index 9ce10fd1..1c4ee909 100644
--- a/theme/theme.config
+++ b/theme/theme.config
@@ -52,7 +52,7 @@
 @dimmer     : 'default';
 @dropdown   : 'default';
 @embed      : 'default';
-@modal      : 'default';
+@modal      : 'pxt';
 @nag        : 'default';
 @popup      : 'default';
 @progress   : 'default';

From 7a5228a5d0056e5415f232ebd55b0a30c81db4fe Mon Sep 17 00:00:00 2001
From: Sam El-Husseini <samelh@microsoft.com>
Date: Sun, 11 Dec 2016 06:52:08 +1300
Subject: [PATCH 4/7] Reverting toolbox color

---
 theme/style.less | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/theme/style.less b/theme/style.less
index 708e4567..65cc1bf6 100644
--- a/theme/style.less
+++ b/theme/style.less
@@ -60,8 +60,8 @@
 }
 
 .blocklyFlyoutBackground {
-    fill: #fff !important;
-    fill-opacity: 0.8 !important;
+    fill: #525A67 !important;
+    fill-opacity: 0.5 !important;
 }
 
 /* Remove shadow around blockly blocks */

From e5a7a811983033dfd527cbcf7efa8683e5714657 Mon Sep 17 00:00:00 2001
From: Sam El-Husseini <samelh@microsoft.com>
Date: Sun, 11 Dec 2016 08:52:02 +1300
Subject: [PATCH 5/7] Better monaco flyout contrast

---
 theme/style.less | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/theme/style.less b/theme/style.less
index 65cc1bf6..251472ae 100644
--- a/theme/style.less
+++ b/theme/style.less
@@ -102,7 +102,7 @@
 }
 
 .monacoFlyout {
-    background: rgba(82, 90, 103, 0.8);
+    background: rgba(82, 90, 103, 0.5);
 }
 
 

From dd591af224a6f8b330a8303327cc866d73767346 Mon Sep 17 00:00:00 2001
From: Sam El-Husseini <samelh@microsoft.com>
Date: Sun, 11 Dec 2016 09:01:08 +1300
Subject: [PATCH 6/7] Turning flag for monaco toolbox on

---
 pxtarget.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/pxtarget.json b/pxtarget.json
index 1ad4ad50..d0bd4800 100644
--- a/pxtarget.json
+++ b/pxtarget.json
@@ -315,6 +315,7 @@
         ],
         "invertedMenu": true,
         "coloredToolbox": true,
+        "monacoToolbox": true,
         "blocklyOptions": { 
             "grid": {
                 "spacing": 45,

From bbd21a84d611abf86b000290d35c5d4b327d0c8f Mon Sep 17 00:00:00 2001
From: Peli de Halleux <jhalleux@microsoft.com>
Date: Tue, 13 Dec 2016 12:14:32 -0800
Subject: [PATCH 7/7] annotating apis to support toolbox

---
 libs/core/_locales/core-jsdoc-strings.json | 43 +++++++++++----------
 libs/core/_locales/core-strings.json       |  2 +-
 libs/core/input.cpp                        | 16 ++++----
 libs/core/music.ts                         |  2 +-
 libs/core/pins.cpp                         | 22 ++++++-----
 libs/core/serial.cpp                       |  6 +--
 libs/core/shims.d.ts                       | 44 ++++++++++++----------
 7 files changed, 74 insertions(+), 61 deletions(-)

diff --git a/libs/core/_locales/core-jsdoc-strings.json b/libs/core/_locales/core-jsdoc-strings.json
index 44b19763..a40d5297 100644
--- a/libs/core/_locales/core-jsdoc-strings.json
+++ b/libs/core/_locales/core-jsdoc-strings.json
@@ -97,26 +97,28 @@
   "input.acceleration": "Get the acceleration value in milli-gravitys (when the board is laying flat with the screen up, x=0, y=0 and z=-1024)",
   "input.acceleration|param|dimension": "TODO",
   "input.buttonIsPressed": "Get the button state (pressed or not) for ``A`` and ``B``.",
+  "input.buttonIsPressed|param|button": "the button to query the request, eg: Button.A",
   "input.calibrate": "Obsolete, compass calibration is automatic.",
   "input.compassHeading": "Get the current compass heading in degrees.",
   "input.lightLevel": "Reads the light level applied to the LED screen in a range from ``0`` (dark) to ``255`` bright.",
   "input.magneticForce": "Get the magnetic force value in ``micro-Teslas`` (``µT``). This function is not supported in the simulator.",
   "input.magneticForce|param|dimension": "TODO",
   "input.onButtonPressed": "Do something when a button (``A``, ``B`` or both ``A+B``) is pressed",
-  "input.onButtonPressed|param|body": "TODO",
-  "input.onButtonPressed|param|button": "TODO",
+  "input.onButtonPressed|param|body": "code to run when event is raised",
+  "input.onButtonPressed|param|button": "the button that needs to be pressed",
   "input.onGesture": "Do something when when a gesture is done (like shaking the micro:bit).",
-  "input.onGesture|param|body": "TODO",
+  "input.onGesture|param|body": "code to run when gesture is raised",
+  "input.onGesture|param|gesture": "the type of gesture to track, eg: Gesture.Shake",
   "input.onLogoDown": "Attaches code to run when the logo is oriented downwards and the board is vertical.",
   "input.onLogoDown|param|body": "TODO",
   "input.onLogoUp": "Attaches code to run when the logo is oriented upwards and the board is vertical.",
   "input.onLogoUp|param|body": "TODO",
   "input.onPinPressed": "Do something when a pin is pressed.",
   "input.onPinPressed|param|body": "the code to run when the pin is pressed",
-  "input.onPinPressed|param|name": "the pin that needs to be pressed",
+  "input.onPinPressed|param|name": "the pin that needs to be pressed, eg: TouchPin.P0",
   "input.onPinReleased": "Do something when a pin is released.",
   "input.onPinReleased|param|body": "the code to run when the pin is released",
-  "input.onPinReleased|param|name": "the pin that needs to be released",
+  "input.onPinReleased|param|name": "the pin that needs to be released, eg: TouchPin.P0",
   "input.onScreenDown": "Attaches code to run when the screen is facing down.",
   "input.onScreenDown|param|body": "TODO",
   "input.onScreenUp": "Attaches code to run when the screen is facing up.",
@@ -124,7 +126,7 @@
   "input.onShake": "Attaches code to run when the device is shaken.",
   "input.onShake|param|body": "TODO",
   "input.pinIsPressed": "Get the pin state (pressed or not). Requires to hold the ground to close the circuit.",
-  "input.pinIsPressed|param|name": "pin used to detect the touch",
+  "input.pinIsPressed|param|name": "pin used to detect the touch, eg: TouchPin.P0",
   "input.rotation": "The pitch or roll of the device, rotation along the ``x-axis`` or ``y-axis``, in degrees.",
   "input.rotation|param|kind": "TODO",
   "input.runningTime": "Gets the number of milliseconds elapsed since power on.",
@@ -166,7 +168,7 @@
   "music.changeTempoBy": "Change the tempo by the specified amount",
   "music.changeTempoBy|param|bpm": "The change in beats per minute to the tempo, eg: 20",
   "music.noteFrequency": "Gets the frequency of a note.",
-  "music.noteFrequency|param|name": "the note name",
+  "music.noteFrequency|param|name": "the note name, eg: Note.C",
   "music.playTone": "Plays a tone through pin ``P0`` for the given duration.",
   "music.playTone|param|frequency": "pitch of the tone to play in Hertz (Hz)",
   "music.playTone|param|ms": "tone duration in milliseconds (ms)",
@@ -182,21 +184,21 @@
   "pins.analogPitch|param|frequency": "frequency to modulate in Hz.",
   "pins.analogPitch|param|ms": "duration of the pitch in milli seconds.",
   "pins.analogReadPin": "Read the connector value as analog, that is, as a value comprised between 0 and 1023.",
-  "pins.analogReadPin|param|name": "pin to write to",
+  "pins.analogReadPin|param|name": "pin to write to, eg: AnalogPin.P0",
   "pins.analogSetPeriod": "Configures the Pulse-width modulation (PWM) of the analog output to the given value in **microseconds** or `1/1000` milliseconds.\nIf this pin is not configured as an analog output (using `analog write pin`), the operation has no effect.",
   "pins.analogSetPeriod|param|micros": "period in micro seconds. eg:20000",
-  "pins.analogSetPeriod|param|name": "analog pin to set period to",
+  "pins.analogSetPeriod|param|name": "analog pin to set period to, eg: AnalogPin.P0",
   "pins.analogSetPitchPin": "Sets the pin used when using `analog pitch` or music.",
   "pins.analogSetPitchPin|param|name": "pin to modulate pitch from",
   "pins.analogWritePin": "Set the connector value as analog. Value must be comprised between 0 and 1023.",
-  "pins.analogWritePin|param|name": "pin name to write to",
+  "pins.analogWritePin|param|name": "pin name to write to, eg: AnalogPin.P0",
   "pins.analogWritePin|param|value": "value to write to the pin between ``0`` and ``1023``. eg:1023,0",
   "pins.createBuffer": "Create a new zero-initialized buffer.",
   "pins.createBuffer|param|size": "number of bytes in the buffer",
   "pins.digitalReadPin": "Read the specified pin or connector as either 0 or 1",
-  "pins.digitalReadPin|param|name": "pin to read from",
+  "pins.digitalReadPin|param|name": "pin to read from, eg: DigitalPin.P0",
   "pins.digitalWritePin": "Set a pin or connector value to either 0 or 1.",
-  "pins.digitalWritePin|param|name": "pin to write to",
+  "pins.digitalWritePin|param|name": "pin to write to, eg: DigitalPin.P0",
   "pins.digitalWritePin|param|value": "value to set on the pin, 1 eg,0",
   "pins.i2cReadBuffer": "Read `size` bytes from a 7-bit I2C `address`.",
   "pins.i2cReadNumber": "Read one number from 7-bit I2C address.",
@@ -209,19 +211,21 @@
   "pins.map|param|toLow": "the lower bound of the value's target range",
   "pins.map|param|value": "value to map in ranges",
   "pins.onPulsed": "Configures this pin to a digital input, and generates events where the timestamp is the duration that this pin was either ``high`` or ``low``.",
+  "pins.onPulsed|param|name": "digital pin to register to, eg: DigitalPin.P0",
+  "pins.onPulsed|param|pulse": "the value of the pulse, eg: PulseValue.High",
   "pins.pulseDuration": "Gets the duration of the last pulse in micro-seconds. This function should be called from a ``onPulsed`` handler.",
   "pins.pulseIn": "Returns the duration of a pulse in microseconds",
-  "pins.pulseIn|param|name": "the pin which measures the pulse",
-  "pins.pulseIn|param|value": "the value of the pulse (default high)",
+  "pins.pulseIn|param|name": "the pin which measures the pulse, eg: DigitalPin.P0",
+  "pins.pulseIn|param|value": "the value of the pulse, eg: PulseValue.High",
   "pins.servoSetPulse": "Configures this IO pin as an analog/pwm output, configures the period to be 20 ms, and sets the pulse width, based on the value it is given **microseconds** or `1/1000` milliseconds.",
   "pins.servoSetPulse|param|micros": "pulse duration in micro seconds, eg:1500",
   "pins.servoSetPulse|param|name": "pin name",
   "pins.servoWritePin": "Writes a value to the servo, controlling the shaft accordingly. On a standard servo, this will set the angle of the shaft (in degrees), moving the shaft to that orientation. On a continuous rotation servo, this will set the speed of the servo (with ``0`` being full-speed in one direction, ``180`` being full speed in the other, and a value near ``90`` being no movement).",
-  "pins.servoWritePin|param|name": "pin to write to",
+  "pins.servoWritePin|param|name": "pin to write to, eg: AnalogPin.P0",
   "pins.servoWritePin|param|value": "angle or rotation speed, eg:180,90,0",
   "pins.setPull": "Configures the pull of this pin.",
-  "pins.setPull|param|name": "pin to set the pull mode on",
-  "pins.setPull|param|pull": "one of the mbed pull configurations: PullUp, PullDown, PullNone ",
+  "pins.setPull|param|name": "pin to set the pull mode on, eg: DigitalPin.P0",
+  "pins.setPull|param|pull": "one of the mbed pull configurations, eg: PinPullMode.PullUp",
   "pins.sizeOf": "Get the size in bytes of specified number format.",
   "pins.spiWrite": "Write to the SPI slave and return the response",
   "pins.spiWrite|param|value": "Data to be sent to the SPI slave",
@@ -232,8 +236,9 @@
   "serial.readUntil": "Reads a line of text from the serial port and returns the buffer when the delimiter is met.",
   "serial.readUntil|param|delimiter": "text delimiter that separates each text chunk",
   "serial.redirect": "Dynamically configuring the serial instance to use pins other than USBTX and USBRX.",
-  "serial.redirect|param|rx": "the new reception pin",
-  "serial.redirect|param|tx": "the new transmission pins",
+  "serial.redirect|param|rate": "the new baud rate. eg: 115200",
+  "serial.redirect|param|rx": "the new reception pin, eg: SerialPin.P1",
+  "serial.redirect|param|tx": "the new transmission pins, eg: SerialPin.P0",
   "serial.writeLine": "Prints a line of text to the serial",
   "serial.writeNumber": "Prints a numeric value to the serial",
   "serial.writeString": "Sends a piece of text through Serial connection.",
diff --git a/libs/core/_locales/core-strings.json b/libs/core/_locales/core-strings.json
index 080f1221..51feee2a 100644
--- a/libs/core/_locales/core-strings.json
+++ b/libs/core/_locales/core-strings.json
@@ -123,7 +123,7 @@
   "input.magneticForce|block": "magnetic force (µT)|%NAME",
   "input.onButtonPressed|block": "on button|%NAME|pressed",
   "input.onGesture|block": "on |%NAME",
-  "input.onPinPressed|block": "on pin %NAME|pressed",
+  "input.onPinPressed|block": "on pin %name|pressed",
   "input.onPinReleased|block": "on pin %NAME|released",
   "input.pinIsPressed|block": "pin %NAME|is pressed",
   "input.rotation|block": "rotation (°)|%NAME",
diff --git a/libs/core/input.cpp b/libs/core/input.cpp
index e1d366aa..198b2ede 100644
--- a/libs/core/input.cpp
+++ b/libs/core/input.cpp
@@ -111,8 +111,8 @@ enum class Gesture {
 namespace input {
     /**
      * Do something when a button (``A``, ``B`` or both ``A+B``) is pressed
-     * @param button TODO
-     * @param body TODO
+     * @param button the button that needs to be pressed
+     * @param body code to run when event is raised
      */
     //% help=input/on-button-pressed weight=85 blockGap=8
     //% blockId=device_button_event block="on button|%NAME|pressed" icon="\uf192"
@@ -123,7 +123,8 @@ namespace input {
 
     /**
      * Do something when when a gesture is done (like shaking the micro:bit).
-     * @param body TODO
+     * @param gesture the type of gesture to track, eg: Gesture.Shake
+     * @param body code to run when gesture is raised
      */
     //% help=input/on-gesture weight=84 blockGap=8
     //% blockId=device_gesture_event block="on |%NAME" icon="\uf135"
@@ -138,11 +139,11 @@ namespace input {
 
      /**
      * Do something when a pin is pressed.
-     * @param name the pin that needs to be pressed
+     * @param name the pin that needs to be pressed, eg: TouchPin.P0
      * @param body the code to run when the pin is pressed
      */
     //% help=input/on-pin-pressed weight=83
-    //% blockId=device_pin_event block="on pin %NAME|pressed" icon="\uf094"
+    //% blockId=device_pin_event block="on pin %name|pressed" icon="\uf094"
     void onPinPressed(TouchPin name, Action body) {
         auto pin = getPin((int)name);
         if (!pin) return;
@@ -154,7 +155,7 @@ namespace input {
 
     /**
      * Do something when a pin is released.
-     * @param name the pin that needs to be released
+     * @param name the pin that needs to be released, eg: TouchPin.P0
      * @param body the code to run when the pin is released
      */
     //% help=input/on-pin-released weight=6 blockGap=8
@@ -171,6 +172,7 @@ namespace input {
 
     /**
      * Get the button state (pressed or not) for ``A`` and ``B``.
+     * @param button the button to query the request, eg: Button.A
      */
     //% help=input/button-is-pressed weight=60
     //% block="button|%NAME|is pressed"
@@ -189,7 +191,7 @@ namespace input {
 
     /**
      * Get the pin state (pressed or not). Requires to hold the ground to close the circuit.
-     * @param name pin used to detect the touch
+     * @param name pin used to detect the touch, eg: TouchPin.P0
      */
     //% help=input/pin-is-pressed weight=58
     //% blockId="device_pin_is_pressed" block="pin %NAME|is pressed" icon="\uf094"
diff --git a/libs/core/music.ts b/libs/core/music.ts
index 964a62ea..df9ec561 100644
--- a/libs/core/music.ts
+++ b/libs/core/music.ts
@@ -170,7 +170,7 @@ namespace music {
 
     /**
      * Gets the frequency of a note.
-     * @param name the note name
+     * @param name the note name, eg: Note.C
      */
     //% weight=50 help=music/note-frequency
     //% blockId=device_note block="%note"
diff --git a/libs/core/pins.cpp b/libs/core/pins.cpp
index c5c2aa94..d7aaa224 100644
--- a/libs/core/pins.cpp
+++ b/libs/core/pins.cpp
@@ -92,7 +92,7 @@ namespace pins {
 
     /**
      * Read the specified pin or connector as either 0 or 1
-     * @param name pin to read from
+     * @param name pin to read from, eg: DigitalPin.P0
      */
     //% help=pins/digital-read-pin weight=30
     //% blockId=device_get_digital_pin block="digital read|pin %name" blockGap=8
@@ -102,7 +102,7 @@ namespace pins {
 
     /**
       * Set a pin or connector value to either 0 or 1.
-      * @param name pin to write to
+      * @param name pin to write to, eg: DigitalPin.P0
       * @param value value to set on the pin, 1 eg,0
       */
     //% help=pins/digital-write-pin weight=29
@@ -113,7 +113,7 @@ namespace pins {
 
     /**
      * Read the connector value as analog, that is, as a value comprised between 0 and 1023.
-     * @param name pin to write to
+     * @param name pin to write to, eg: AnalogPin.P0
      */
     //% help=pins/analog-read-pin weight=25
     //% blockId=device_get_analog_pin block="analog read|pin %name" blockGap="8" 
@@ -123,7 +123,7 @@ namespace pins {
 
     /**
      * Set the connector value as analog. Value must be comprised between 0 and 1023.
-     * @param name pin name to write to
+     * @param name pin name to write to, eg: AnalogPin.P0
      * @param value value to write to the pin between ``0`` and ``1023``. eg:1023,0
      */
     //% help=pins/analog-write-pin weight=24
@@ -135,7 +135,7 @@ namespace pins {
     /**
      * Configures the Pulse-width modulation (PWM) of the analog output to the given value in **microseconds** or `1/1000` milliseconds.
      * If this pin is not configured as an analog output (using `analog write pin`), the operation has no effect.
-     * @param name analog pin to set period to
+     * @param name analog pin to set period to, eg: AnalogPin.P0
      * @param micros period in micro seconds. eg:20000
      */
     //% help=pins/analog-set-period weight=23 blockGap=8
@@ -146,6 +146,8 @@ namespace pins {
     
     /**
     * Configures this pin to a digital input, and generates events where the timestamp is the duration that this pin was either ``high`` or ``low``.
+    * @param name digital pin to register to, eg: DigitalPin.P0
+    * @param pulse the value of the pulse, eg: PulseValue.High
     */
     //% help=pins/on-pulsed weight=22 blockGap=8 advanced=true
     //% blockId=pins_on_pulsed block="on|pin %pin|pulsed %pulse"
@@ -169,8 +171,8 @@ namespace pins {
 
     /**
     * Returns the duration of a pulse in microseconds
-    * @param name the pin which measures the pulse
-    * @param value the value of the pulse (default high)
+    * @param name the pin which measures the pulse, eg: DigitalPin.P0
+    * @param value the value of the pulse, eg: PulseValue.High
     * @param maximum duration in micro-seconds
     */    
     //% blockId="pins_pulse_in" block="pulse in (µs)|pin %name|pulsed %value"
@@ -198,7 +200,7 @@ namespace pins {
 
     /**
      * Writes a value to the servo, controlling the shaft accordingly. On a standard servo, this will set the angle of the shaft (in degrees), moving the shaft to that orientation. On a continuous rotation servo, this will set the speed of the servo (with ``0`` being full-speed in one direction, ``180`` being full speed in the other, and a value near ``90`` being no movement).
-     * @param name pin to write to
+     * @param name pin to write to, eg: AnalogPin.P0
      * @param value angle or rotation speed, eg:180,90,0
      */
     //% help=pins/servo-write-pin weight=20
@@ -260,8 +262,8 @@ namespace pins {
     
     /**
     * Configures the pull of this pin.
-    * @param name pin to set the pull mode on
-    * @param pull one of the mbed pull configurations: PullUp, PullDown, PullNone 
+    * @param name pin to set the pull mode on, eg: DigitalPin.P0
+    * @param pull one of the mbed pull configurations, eg: PinPullMode.PullUp
     */
     //% help=pins/set-pull weight=3 advanced=true
     //% blockId=device_set_pull block="set pull|pin %pin|to %pull"
diff --git a/libs/core/serial.cpp b/libs/core/serial.cpp
index cd89aa8b..6c387f4f 100644
--- a/libs/core/serial.cpp
+++ b/libs/core/serial.cpp
@@ -83,9 +83,9 @@ namespace serial {
 
     /**
     * Dynamically configuring the serial instance to use pins other than USBTX and USBRX.
-    * @param tx the new transmission pins
-    * @param rx the new reception pin
-    * @param baud the new baud rate. eg: 115200
+    * @param tx the new transmission pins, eg: SerialPin.P0
+    * @param rx the new reception pin, eg: SerialPin.P1
+    * @param rate the new baud rate. eg: 115200
     */
     //% weight=10
     //% help=serial/redirect-to
diff --git a/libs/core/shims.d.ts b/libs/core/shims.d.ts
index ea74ac63..2b5a9120 100644
--- a/libs/core/shims.d.ts
+++ b/libs/core/shims.d.ts
@@ -216,8 +216,8 @@ declare namespace input {
 
     /**
      * Do something when a button (``A``, ``B`` or both ``A+B``) is pressed
-     * @param button TODO
-     * @param body TODO
+     * @param button the button that needs to be pressed
+     * @param body code to run when event is raised
      */
     //% help=input/on-button-pressed weight=85 blockGap=8
     //% blockId=device_button_event block="on button|%NAME|pressed" icon="\uf192"
@@ -226,7 +226,8 @@ declare namespace input {
 
     /**
      * Do something when when a gesture is done (like shaking the micro:bit).
-     * @param body TODO
+     * @param gesture the type of gesture to track, eg: Gesture.Shake
+     * @param body code to run when gesture is raised
      */
     //% help=input/on-gesture weight=84 blockGap=8
     //% blockId=device_gesture_event block="on |%NAME" icon="\uf135"
@@ -235,16 +236,16 @@ declare namespace input {
 
     /**
      * Do something when a pin is pressed.
-     * @param name the pin that needs to be pressed
+     * @param name the pin that needs to be pressed, eg: TouchPin.P0
      * @param body the code to run when the pin is pressed
      */
     //% help=input/on-pin-pressed weight=83
-    //% blockId=device_pin_event block="on pin %NAME|pressed" icon="\uf094" shim=input::onPinPressed
+    //% blockId=device_pin_event block="on pin %name|pressed" icon="\uf094" shim=input::onPinPressed
     function onPinPressed(name: TouchPin, body: () => void): void;
 
     /**
      * Do something when a pin is released.
-     * @param name the pin that needs to be released
+     * @param name the pin that needs to be released, eg: TouchPin.P0
      * @param body the code to run when the pin is released
      */
     //% help=input/on-pin-released weight=6 blockGap=8
@@ -254,6 +255,7 @@ declare namespace input {
 
     /**
      * Get the button state (pressed or not) for ``A`` and ``B``.
+     * @param button the button to query the request, eg: Button.A
      */
     //% help=input/button-is-pressed weight=60
     //% block="button|%NAME|is pressed"
@@ -264,7 +266,7 @@ declare namespace input {
 
     /**
      * Get the pin state (pressed or not). Requires to hold the ground to close the circuit.
-     * @param name pin used to detect the touch
+     * @param name pin used to detect the touch, eg: TouchPin.P0
      */
     //% help=input/pin-is-pressed weight=58
     //% blockId="device_pin_is_pressed" block="pin %NAME|is pressed" icon="\uf094"
@@ -512,7 +514,7 @@ declare namespace pins {
 
     /**
      * Read the specified pin or connector as either 0 or 1
-     * @param name pin to read from
+     * @param name pin to read from, eg: DigitalPin.P0
      */
     //% help=pins/digital-read-pin weight=30
     //% blockId=device_get_digital_pin block="digital read|pin %name" blockGap=8 shim=pins::digitalReadPin
@@ -520,7 +522,7 @@ declare namespace pins {
 
     /**
      * Set a pin or connector value to either 0 or 1.
-     * @param name pin to write to
+     * @param name pin to write to, eg: DigitalPin.P0
      * @param value value to set on the pin, 1 eg,0
      */
     //% help=pins/digital-write-pin weight=29
@@ -529,7 +531,7 @@ declare namespace pins {
 
     /**
      * Read the connector value as analog, that is, as a value comprised between 0 and 1023.
-     * @param name pin to write to
+     * @param name pin to write to, eg: AnalogPin.P0
      */
     //% help=pins/analog-read-pin weight=25
     //% blockId=device_get_analog_pin block="analog read|pin %name" blockGap="8" shim=pins::analogReadPin
@@ -537,7 +539,7 @@ declare namespace pins {
 
     /**
      * Set the connector value as analog. Value must be comprised between 0 and 1023.
-     * @param name pin name to write to
+     * @param name pin name to write to, eg: AnalogPin.P0
      * @param value value to write to the pin between ``0`` and ``1023``. eg:1023,0
      */
     //% help=pins/analog-write-pin weight=24
@@ -547,7 +549,7 @@ declare namespace pins {
     /**
      * Configures the Pulse-width modulation (PWM) of the analog output to the given value in **microseconds** or `1/1000` milliseconds.
      * If this pin is not configured as an analog output (using `analog write pin`), the operation has no effect.
-     * @param name analog pin to set period to
+     * @param name analog pin to set period to, eg: AnalogPin.P0
      * @param micros period in micro seconds. eg:20000
      */
     //% help=pins/analog-set-period weight=23 blockGap=8
@@ -556,6 +558,8 @@ declare namespace pins {
 
     /**
      * Configures this pin to a digital input, and generates events where the timestamp is the duration that this pin was either ``high`` or ``low``.
+     * @param name digital pin to register to, eg: DigitalPin.P0
+     * @param pulse the value of the pulse, eg: PulseValue.High
      */
     //% help=pins/on-pulsed weight=22 blockGap=8 advanced=true
     //% blockId=pins_on_pulsed block="on|pin %pin|pulsed %pulse" shim=pins::onPulsed
@@ -571,8 +575,8 @@ declare namespace pins {
 
     /**
      * Returns the duration of a pulse in microseconds
-     * @param name the pin which measures the pulse
-     * @param value the value of the pulse (default high)
+     * @param name the pin which measures the pulse, eg: DigitalPin.P0
+     * @param value the value of the pulse, eg: PulseValue.High
      * @param maximum duration in micro-seconds
      */
     //% blockId="pins_pulse_in" block="pulse in (µs)|pin %name|pulsed %value"
@@ -581,7 +585,7 @@ declare namespace pins {
 
     /**
      * Writes a value to the servo, controlling the shaft accordingly. On a standard servo, this will set the angle of the shaft (in degrees), moving the shaft to that orientation. On a continuous rotation servo, this will set the speed of the servo (with ``0`` being full-speed in one direction, ``180`` being full speed in the other, and a value near ``90`` being no movement).
-     * @param name pin to write to
+     * @param name pin to write to, eg: AnalogPin.P0
      * @param value angle or rotation speed, eg:180,90,0
      */
     //% help=pins/servo-write-pin weight=20
@@ -617,8 +621,8 @@ declare namespace pins {
 
     /**
      * Configures the pull of this pin.
-     * @param name pin to set the pull mode on
-     * @param pull one of the mbed pull configurations: PullUp, PullDown, PullNone 
+     * @param name pin to set the pull mode on, eg: DigitalPin.P0
+     * @param pull one of the mbed pull configurations, eg: PinPullMode.PullUp
      */
     //% help=pins/set-pull weight=3 advanced=true
     //% blockId=device_set_pull block="set pull|pin %pin|to %pull" shim=pins::setPull
@@ -685,9 +689,9 @@ declare namespace serial {
 
     /**
      * Dynamically configuring the serial instance to use pins other than USBTX and USBRX.
-     * @param tx the new transmission pins
-     * @param rx the new reception pin
-     * @param baud the new baud rate. eg: 115200
+     * @param tx the new transmission pins, eg: SerialPin.P0
+     * @param rx the new reception pin, eg: SerialPin.P1
+     * @param rate the new baud rate. eg: 115200
      */
     //% weight=10
     //% help=serial/redirect-to