From 3f106307ff681644e4887691933948f462c40a91 Mon Sep 17 00:00:00 2001
From: Galen Nickel <v-gani@microsoft.com>
Date: Wed, 5 Jun 2019 16:28:56 -0700
Subject: [PATCH] Fix some titles, sigs in ref docs (#2128)

* Fix some title and sigs in ref docs

* better buffer source
---
 docs/SUMMARY.md                          |  2 +-
 docs/reference/game/change.md            | 18 ++++++++----------
 docs/reference/game/create-sprite.md     |  4 ++++
 docs/reference/game/delete.md            | 11 +++--------
 docs/reference/game/get.md               | 20 +++++++++-----------
 docs/reference/game/if-on-edge-bounce.md |  3 +--
 docs/reference/game/is-touching-edge.md  |  7 +++----
 docs/reference/game/is-touching.md       |  8 +++-----
 docs/reference/game/move.md              |  5 ++---
 docs/reference/game/set.md               | 18 ++++++++----------
 docs/reference/game/turn.md              |  9 ++++-----
 docs/reference/serial.md                 |  2 +-
 docs/reference/serial/read-buffer.md     |  2 +-
 docs/reference/serial/write-buffer.md    |  2 +-
 libs/core/serial.cpp                     |  4 ++--
 libs/core/shims.d.ts                     |  4 ++--
 16 files changed, 53 insertions(+), 66 deletions(-)

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 9f43a35c..3a2accb0 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -233,7 +233,7 @@
         * [delete](/reference/game/delete)
         * [move](/reference/game/move)
         * [turn](/reference/game/turn)
-        * [in on edge bounce](/reference/game/if-on-edge-bounce)
+        * [if on edge bounce](/reference/game/if-on-edge-bounce)
         * [get](/reference/game/get)
         * [set](/reference/game/set)
         * [change](/reference/game/change)
diff --git a/docs/reference/game/change.md b/docs/reference/game/change.md
index c7f60886..00d9a231 100644
--- a/docs/reference/game/change.md
+++ b/docs/reference/game/change.md
@@ -1,21 +1,19 @@
-# change Sprite Property
+# change (Sprite Property)
 
 Change the kind of [number](/types/number) you say for a [sprite](/reference/game/create-sprite).
 
 ```sig
-let item: game.LedSprite = null;
-item.change(LedSpriteProperty.X, 0);
+game.createSprite(0,0).change(LedSpriteProperty.X, 0);
 ```
 
 ## Parameters
 
-* the **sprite** you want to change
-* the kind of [number](/types/number) you want to change for the sprite, like
-    * ``x``, how far up or down the sprite is on the screen (`0`-`4`)
-    * ``y``, how far left or right the sprite is on the screen (`0`-`4`)
-    * ``direction``, which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
-    * ``brightness``, how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
-    * ``blink``, how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
+* **property**: the property of the **Sprite** you want to change, like:
+>* ``x`` - how far up or down the sprite is on the screen (`0`-`4`)
+>* ``y`` - how far left or right the sprite is on the screen (`0`-`4`)
+>* ``direction`` - which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
+>* ``brightness`` - how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
+>* ``blink`` -  how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
 
 ## Example
 
diff --git a/docs/reference/game/create-sprite.md b/docs/reference/game/create-sprite.md
index e1c02b9a..01583333 100644
--- a/docs/reference/game/create-sprite.md
+++ b/docs/reference/game/create-sprite.md
@@ -17,6 +17,10 @@ game.createSprite(2, 2);
 
 `0` and `4` mean the edges of the screen, and `2` means in the middle.
 
+## Returns
+
+* a new **LedSprite** at the location you say.
+
 ## ~ hint
 
 Once the game engine is started, it will render the sprites to the screen and potentially override any kind of animation you are trying to show.
diff --git a/docs/reference/game/delete.md b/docs/reference/game/delete.md
index 5d93d646..0ab5130c 100644
--- a/docs/reference/game/delete.md
+++ b/docs/reference/game/delete.md
@@ -3,15 +3,10 @@
 Delete a sprite from the game.
 
 ```sig
-let item: game.LedSprite = null;
-item.delete();
+game.createSprite(0,0).delete()
 ```
 
-### Parameters
-
-* the **sprite** you want to delete from the game
-
-### Example
+## Example
 
 This program makes a sprite and shows the number of its brightness on the screen. Then, it deletes the sprite. 
 
@@ -21,6 +16,6 @@ basic.showNumber(ball.get(LedSpriteProperty.Brightness));
 ball.delete();
 ```
 
-### See also
+## See also
 
 [create sprite](/reference/game/create-sprite)
diff --git a/docs/reference/game/get.md b/docs/reference/game/get.md
index 5317a302..d2608e3e 100644
--- a/docs/reference/game/get.md
+++ b/docs/reference/game/get.md
@@ -1,25 +1,23 @@
-# Get Sprite Property
+# get (Sprite Property)
 
 Find something out about a [sprite](/reference/game/create-sprite).
 
 ```sig
-let item: game.LedSprite = null;
-item.get(LedSpriteProperty.X);
+game.createSprite(0,0).get(LedSpriteProperty.X);
 ```
 
 ## Parameters
 
-* the **sprite** you want to know something about
-* the kind of [number](/types/number) you want to know about the sprite, like
-    * ``x``, how far up or down the sprite is on the screen (`0`-`4`)
-    * ``y``, how far left or right the sprite is on the screen (`0`-`4`)
-    * ``direction``, which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
-    * ``brightness``, how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
-    * ``blink``, how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
+* **property**: the property of the **Sprite** you want to know about, like:
+>* ``x`` - how far up or down the sprite is on the screen (`0`-`4`)
+>* ``y`` - how far left or right the sprite is on the screen (`0`-`4`)
+>* ``direction`` - which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
+>* ``brightness`` - how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
+>* ``blink`` - how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
 
 ## Returns
 
-The [number](/types/number) you asked for.
+* a [number](/types/number) value of the property you asked for.
 
 ## Example
 
diff --git a/docs/reference/game/if-on-edge-bounce.md b/docs/reference/game/if-on-edge-bounce.md
index b0f9a5fa..841eaf5a 100644
--- a/docs/reference/game/if-on-edge-bounce.md
+++ b/docs/reference/game/if-on-edge-bounce.md
@@ -4,8 +4,7 @@ Make a [sprite](/reference/game/create-sprite) on the edge of the
 [LED screen](/device/screen) bounce away.
 
 ```sig
-let item = game.createSprite(0, 2);
-item.ifOnEdgeBounce();
+game.createSprite(0, 2).ifOnEdgeBounce();
 ```
 
 ## Parameters
diff --git a/docs/reference/game/is-touching-edge.md b/docs/reference/game/is-touching-edge.md
index 9590bc87..6016209e 100644
--- a/docs/reference/game/is-touching-edge.md
+++ b/docs/reference/game/is-touching-edge.md
@@ -6,17 +6,16 @@ Sprites are touching the edge if they overlap with an LED on the edge
 of the screen.
 
 ```sig
-let item: game.LedSprite = null;
-item.isTouchingEdge();
+game.createSprite(0, 2).isTouchingEdge();
 ```
 
 ## Parameters
 
-* a **sprite** that might be touching the edge of the screen
+* a **sprite** that might be touching the edge of the screen.
 
 ## Returns
 
-`true` if the sprite is touching the edge of the screen
+* `true` if the sprite is touching the edge of the screen.
 
 ## Example
 
diff --git a/docs/reference/game/is-touching.md b/docs/reference/game/is-touching.md
index 04fb02df..dfd1f386 100644
--- a/docs/reference/game/is-touching.md
+++ b/docs/reference/game/is-touching.md
@@ -5,18 +5,16 @@ Find whether the sprite is touching another sprite you say.
 Sprites are touching if they share the same LED.
 
 ```sig
-let item: game.LedSprite = null;
-item.isTouching(null);
+game.createSprite(0, 2).isTouching(null);
 ```
 
 ## Parameters
 
-* a **sprite** you are checking
-* another **sprite** that might be touching the one you are checking
+* another **sprite** that might be touching the one you are checking.
 
 ## Returns
 
-`true` if the two sprites are touching.
+* `true` if the two sprites are touching.
 
 ## Example
 
diff --git a/docs/reference/game/move.md b/docs/reference/game/move.md
index 1ce65348..b4989d95 100644
--- a/docs/reference/game/move.md
+++ b/docs/reference/game/move.md
@@ -3,13 +3,12 @@
 Move the sprite the number of LEDs you say.
 
 ```sig
-let item: game.LedSprite = null;
-item.move(1);
+game.createSprite(0, 2).move(1);
 ```
 
 ## Parameters
 
-* a [number](/types/number) that means how many LEDs the sprite should move
+* **leds**: a [number](/types/number) that means how many LEDs the sprite should move.
 
 ## Example
 
diff --git a/docs/reference/game/set.md b/docs/reference/game/set.md
index ee76ddc3..7a6ccb1b 100644
--- a/docs/reference/game/set.md
+++ b/docs/reference/game/set.md
@@ -1,21 +1,19 @@
-# Set Sprite Property
+# set (Sprite Property)
 
 Make a [sprite](/reference/game/create-sprite) store the kind of [number](/types/number) you say.
 
 ```sig
-let item: game.LedSprite = null;
-item.set(LedSpriteProperty.X, 0);
+game.createSprite(0,0).set(LedSpriteProperty.X, 0);
 ```
 
 ## Parameters
 
-* the **sprite** you want to make store the number you say
-* the kind of [number](/types/number) you want to store in the sprite, like
-    * ``x``, how far up or down the sprite is on the screen (`0`-`4`)
-    * ``y``, how far left or right the sprite is on the screen (`0`-`4`)
-    * ``direction``, which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
-    * ``brightness``, how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
-    * ``blink``, how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
+* **property**: the property of the **Sprite** you want to store a value for, like:
+>* ``x`` - how far up or down the sprite is on the screen (`0`-`4`)
+>* ``y`` - how far left or right the sprite is on the screen (`0`-`4`)
+>* ``direction`` - which way the sprite is pointing (this works the same way as the [turn](/reference/game/turn) function)
+>* ``brightness`` - how bright the LED sprite is (this works the same way as the [brightness](/reference/led/brightness) function)
+>* ``blink`` - how fast the sprite is blinking (the bigger the number is, the faster the sprite is blinking)
 
 ## Example
 
diff --git a/docs/reference/game/turn.md b/docs/reference/game/turn.md
index bca9d2a9..72e44d11 100644
--- a/docs/reference/game/turn.md
+++ b/docs/reference/game/turn.md
@@ -3,15 +3,14 @@
 Turn the sprite as much as you say in the direction you say.
 
 ```sig
-let item: game.LedSprite = null;
-item.turn(Direction.Right, 45);
+game.createSprite(0, 2).turn(Direction.Right, 45);
 ```
 
 ## Parameters
 
-* a choice whether the sprite should turn **left** or **right**
-* a [number](/types/number) that means how much the sprite should turn.
-  This number is in **degrees**, so a straight left or right turn is 90 degrees.
+* **direction**: a choice whether the sprite should turn **left** or **right**
+* **degrees**: a [number](/types/number) degrees of angle that the sprite should turn.
+A straight left or right turn is 90 degrees.
 
 ## Example
 
diff --git a/docs/reference/serial.md b/docs/reference/serial.md
index 4e66791d..a59ed0ac 100644
--- a/docs/reference/serial.md
+++ b/docs/reference/serial.md
@@ -19,7 +19,7 @@ serial.onDataReceived(",", () => {})
 ```cards
 serial.redirect(SerialPin.P0, SerialPin.P0, BaudRate.BaudRate115200);
 serial.redirectToUSB();
-serial.writeBuffer(pins.createBuffer(0));
+serial.writeBuffer(serial.readBuffer(64));
 serial.readBuffer(64);
 serial.setRxBufferSize(64);
 serial.setTxBufferSize(64);
diff --git a/docs/reference/serial/read-buffer.md b/docs/reference/serial/read-buffer.md
index 346d2966..7a31fe33 100644
--- a/docs/reference/serial/read-buffer.md
+++ b/docs/reference/serial/read-buffer.md
@@ -26,7 +26,7 @@ The need to pause for more data is set by the @boardname@ **[serial mode](https:
 
 Read character data from the serial port one row at a time. Write the rows to an LED display connected to the I2C pins.
 
-```blocks
+```typescript
 let rowData: Buffer = null;
 for (let i = 0; i < 24; i++) {
     rowData = serial.readBuffer(80);
diff --git a/docs/reference/serial/write-buffer.md b/docs/reference/serial/write-buffer.md
index 81b92f64..d9c3c6fb 100644
--- a/docs/reference/serial/write-buffer.md
+++ b/docs/reference/serial/write-buffer.md
@@ -16,7 +16,7 @@ You place your data characters into an existing buffer. All of the data, the len
 
 Read some characters of data from a device connected to the I2C pins. Write the data to the serial port.
 
-```blocks
+```typescript
 pins.i2cWriteNumber(132, NumberFormat.UInt8LE, 0);
 let i2cBuffer = pins.i2cReadBuffer(132, 16, false);
 serial.writeBuffer(i2cBuffer);
diff --git a/libs/core/serial.cpp b/libs/core/serial.cpp
index 6fe4ee3e..930c6387 100644
--- a/libs/core/serial.cpp
+++ b/libs/core/serial.cpp
@@ -196,7 +196,7 @@ namespace serial {
     * Sets the size of the RX buffer in bytes
     * @param size length of the rx buffer in bytes, eg: 32
     */
-    //% help=serial/set-rx-buffer-size
+    //% help=reference/serial/set-rx-buffer-size
     void setRxBufferSize(uint8_t size) {
       uBit.serial.setRxBufferSize(size);
     }
@@ -205,7 +205,7 @@ namespace serial {
     * Sets the size of the TX buffer in bytes
     * @param size length of the tx buffer in bytes, eg: 32
     */
-    //% help=serial/set-tx-buffer-size
+    //% help=reference/serial/set-tx-buffer-size
     void setTxBufferSize(uint8_t size) {
       uBit.serial.setTxBufferSize(size);
     }
diff --git a/libs/core/shims.d.ts b/libs/core/shims.d.ts
index d7726cef..5d882261 100644
--- a/libs/core/shims.d.ts
+++ b/libs/core/shims.d.ts
@@ -869,14 +869,14 @@ declare namespace serial {
      * Sets the size of the RX buffer in bytes
      * @param size length of the rx buffer in bytes, eg: 32
      */
-    //% help=serial/set-rx-buffer-size shim=serial::setRxBufferSize
+    //% help=reference/serial/set-rx-buffer-size shim=serial::setRxBufferSize
     function setRxBufferSize(size: uint8): void;
 
     /**
      * Sets the size of the TX buffer in bytes
      * @param size length of the tx buffer in bytes, eg: 32
      */
-    //% help=serial/set-tx-buffer-size shim=serial::setTxBufferSize
+    //% help=reference/serial/set-tx-buffer-size shim=serial::setTxBufferSize
     function setTxBufferSize(size: uint8): void;
 }