Start on the 'brick' api topics (#280)

* Start on the 'brick' api topics

* Add the delay to clear screen example

* Better output for clearsceen example

docs/SUMMARY.md

@@ -41,3 +41,11 @@
 ## Reference #reference
 
 * [Reference](/reference)
+    * [Brick](/reference/brick)
+        * [show string](/reference/brick/show-string)
+        * [show number](/reference/brick/show-number)
+        * [show value](/reference/brick/show-value)
+        * [show mood](/reference/brick/show-mood)
+        * [show image](/reference/brick/show-image)
+        * [clear screen](/reference/brick/clear-screen)
+        * [print ports](/reference/brick/print-ports)

docs/reference.md

@@ -1,8 +1,11 @@
 # Reference
 
-
+```namespaces
+brick.showMood(moods.sleeping);
+```
 
 ## See Also
 
+[brick](/reference/brick),
 [touch sensor](/reference/sensors/touch-sensor),
 [color sensor](/reference/sensors/color-sensor)

docs/reference/brick.md

@@ -0,0 +1,13 @@
+# Brick
+
+## Screen
+
+```cards
+brick.showMood(moods.sleeping);
+brick.showImage(images.expressionsBigSmile);
+brick.showString("Hello world!", 1);
+brick.showNumber(0, 1);
+brick.showValue("item", 0, 1);
+brick.clearScreen();
+brick.printPorts();
+```

docs/reference/brick/clear-screen.md

@@ -0,0 +1,22 @@
+# clear Screen
+
+Clear any text or numbers displayed on the screen. The screen will be blank.
+
+```sig
+brick.clearScreen();
+```
+
+## Example
+
+Clear the screen after displaying the message.
+
+```blocks
+brick.showString("This message will", 1);
+brick.showString("self-destruct in:", 2);
+brick.showString("seconds", 5);
+for (let i = 0; i < 10; i++) {
+    brick.showNumber(10 - i, 4);
+    loops.pause(1000);
+}
+brick.clearScreen();
+```

docs/reference/brick/print-ports.md

@@ -0,0 +1,19 @@
+# print Ports
+
+Print the status of the ports on the screen.
+
+```sig
+brick.printPorts();
+```
+
+## Example
+
+Show the port status.
+
+```blocks
+brick.printPorts();
+```
+
+## See also
+
+[show string](/reference/brick/show-string), [show value](/reference/brick/show-value)

docs/reference/brick/show-image.md

@@ -0,0 +1,24 @@
+# show Image
+
+Show an image on the brick's display.
+
+```sig
+brick.showImage(images.expressionsBigSmile);
+```
+You can choose one of several images to show on the display. 
+
+## Parameters
+
+**image**: A image to show on the brick's display. Use the image picker to choose the image you want to show.
+
+## Example
+
+Show a sleeping image on the brick's display.
+
+```blocks
+brick.showImage(image.expressionsZzz)
+```
+
+## See also
+
+[show image](/reference/brick/show-mood)

docs/reference/brick/show-mood.md

@@ -0,0 +1,37 @@
+# show Mood
+
+Show a mood on the brick. A mood will have a image on the display along with a sound and solid or flashing light.
+
+```sig
+brick.showMood(moods.sleeping)
+```
+You can choose one of several moods to show on the display. Use a mood to help show what your @boardname@ is doing at the moment.
+
+## Parameters
+
+**mood**: A mood to show on the brick. Choose one of these moods:
+>* ``sleeping``
+* ``awake``
+* ``tired``
+* ``angry``
+* ``sad``
+* ``dizzy``
+* ``knockedOut``
+* ``middleLeft``
+* ``middleRight``
+* ``love``
+* ``winking``
+* ``neutral``
+
+
+## Example
+
+Show a ``winking`` mood on the brick.
+
+```blocks
+brick.showMood(moods.winking)
+```
+
+## See also
+
+[show image](/reference/brick/show-image)

docs/reference/brick/show-number.md

@@ -0,0 +1,24 @@
+# show Number
+
+Show a number on the screen at the line you select.
+
+```sig
+brick.showNumber(0, 1);
+```
+
+## Parameters
+
+**value**: a [number](/types/number) to show on the brick's screen.
+**line**: The line number on the screen where the value is displayed. The line numbers for the screen start with line `1`.
+
+## Example
+
+Show the number `1000` on the screen.
+
+```blocks
+brick.showNumber(1000, 1);
+```
+
+## See also
+
+[show string](/reference/brick/show-string), [show value](/reference/brick/show-value)

docs/reference/brick/show-string.md

@@ -0,0 +1,27 @@
+# show String
+
+Show some text on a the screen at the line you select.
+
+```sig
+brick.showString("Hello world", 1)
+```
+
+## Parameters
+
+* **text**: a [string](/types/string) to show on the brick's screen.
+* **line**: the line [number](/types/number) on the screen where the text is displayed. The line numbers for the screen start with line `1`.
+
+## Example
+
+Show a greeting on the screen. Then, respond with another message when ENTER is pressed.
+
+```blocks
+brick.showString("Hello, I dare you to press ENTER...", 1);
+brick.buttonEnter.onEvent(ButtonEvent.Click, function () {
+	brick.showString("Hey! Don't push my buttons.", 3);
+});
+```
+
+## See also
+
+[show number](/reference/brick/show-number)

docs/reference/brick/show-value.md

@@ -0,0 +1,29 @@
+# show Value
+
+Show a name-value-pair on the screen at the line you select.
+
+```sig
+brick.showNumber("item", 0, 1);
+```
+
+Name-value-pairs are used to report data values to the screen. If you want to show the current temperature on the screen, you might use `"temp"` as the data name for the the value.
+
+## Parameters
+
+* **name**: a [string](/types/string) which is the name of the data value.
+**value**: a [number](/types/number) to show on the brick's screen.
+**line**: The line number on the screen where the value is displayed. The line numbers for the screen start with line `1`.
+
+## Example
+
+Show the current amount of ambient light detected by sensor 2.
+
+```blocks
+brick.buttonEnter.onEvent(ButtonEvent.Click, function () {
+    brick.showValue("color", sensors.color2.light(LightIntensityMode.Ambient), 1)
+})
+```
+
+## See also
+
+[show number](/reference/brick/show-number)

libs/core/_locales/core-jsdoc-strings.json

@@ -29,11 +29,11 @@
   "brick.buttonLeft": "Left button on the EV3 Brick.",
   "brick.buttonRight": "Right button on the EV3 Brick.",
   "brick.buttonUp": "Up button on the EV3 Brick.",
-  "brick.clearScreen": "Clears the screen",
-  "brick.printPorts": "Prints the port states on the screen",
+  "brick.clearScreen": "Clear the screen",
+  "brick.printPorts": "Print the port states on the screen",
   "brick.setLight": "Set lights.",
   "brick.setLight|param|pattern": "the lights pattern to use. eg: BrickLight.Orange",
-  "brick.showImage": "Shows an image on screen",
+  "brick.showImage": "Show an image on the screen",
   "brick.showImage|param|image": "image to draw",
   "brick.showNumber": "Shows a number on the screen",
   "brick.showNumber|param|line": "the line number to print the text at, eg: 1",

libs/core/screen.ts

@@ -72,6 +72,7 @@ namespace brick {
      */
     //% blockId=screen_print block="show string %text|at line %line"
     //% weight=98 group="Screen" inlineInputMode="inline" blockGap=8
+    //% help=brick/show-string
     //% line.min=1 line.max=10
     export function showString(text: string, line: number) {
         const NUM_LINES = 9;
@@ -87,6 +88,7 @@ namespace brick {
      */
     //% blockId=screenShowNumber block="show number %name|at line %line"
     //% weight=96 group="Screen" inlineInputMode="inline" blockGap=8
+    //% help=brick/show-number
     //% line.min=1 line.max=10
     export function showNumber(value: number, line: number) {
         showString("" + value, line);
@@ -99,6 +101,7 @@ namespace brick {
      */
     //% blockId=screenShowValue block="show value %name|= %text|at line %line"
     //% weight=96 group="Screen" inlineInputMode="inline" blockGap=8
+    //% help=brick/show-value
     //% line.min=1 line.max=10
     export function showValue(name: string, value: number, line: number) {
         value = Math.round(value * 1000) / 1000;
@@ -136,11 +139,12 @@ namespace brick {
     }
 
     /**
-     * Shows an image on screen
+     * Show an image on the screen
      * @param image image to draw
      */
     //% blockId=screen_show_image block="show image %image=screen_image_picker"
     //% weight=100 group="Screen" blockGap=8
+    //% help=brick/show-image
     export function showImage(image: Image) {
         if (!image) return;
         image.draw(0, 0, Draw.Normal);
@@ -160,10 +164,11 @@ namespace brick {
     }
 
     /**
-     * Clears the screen
+     * Clear the screen
      */
     //% blockId=screen_clear_screen block="clear screen"
     //% weight=90 group="Screen"
+    //% help=brick/clear-screen
     export function clearScreen() {
         screen.clear();
     }
@@ -208,9 +213,10 @@ namespace brick {
     }
 
     /**
-     * Prints the port states on the screen
+     * Print the port states on the screen
      */
     //% blockId=brickPrintPorts block="print ports"
+    //% help=brick/print-ports
     //% weight=1 group="Screen"
     export function printPorts() {
         const col = 44;

libs/mood/_locales/mood-jsdoc-strings.json

@@ -1,7 +1,7 @@
 {
   "brick.Mood": "A mood",
   "brick.Mood.show": "Shows the mood on the EV3",
-  "brick.showMood": "Shows a mood",
+  "brick.showMood": "Show a mood on the brick's screen",
   "moods.angry": "An angry mood",
   "moods.awake": "A awake mood",
   "moods.dizzy": "A dizzy mood",

libs/mood/mood.ts

@@ -1,9 +1,10 @@
 namespace brick {
     /**
-     * Shows a mood
+     * Show a mood on the brick's screen
      */
     //% weight=90
     //% blockId=moodShow block="show mood %mood=mood_image_picker"
+    //% help=brick/show-mood
     //% weight=101 group="Screen" blockGap=8
     export function showMood(mood: Mood) {
         if(mood)