From 5650f7dc35c2c54e07a1eff10f01faac1ca480a1 Mon Sep 17 00:00:00 2001
From: Ron Hale-Evans <rwhe@ludism.org>
Date: Tue, 31 May 2016 17:02:22 -0700
Subject: [PATCH] Finishing pass on send/receive number. Examples distributed
 more sensibly.

---
 docs/reference/radio/receive-number.md | 46 +++++++++++++++++++++++---
 docs/reference/radio/send-number.md    | 46 +++++---------------------
 2 files changed, 50 insertions(+), 42 deletions(-)

diff --git a/docs/reference/radio/receive-number.md b/docs/reference/radio/receive-number.md
index 85b45230..8b25e601 100644
--- a/docs/reference/radio/receive-number.md
+++ b/docs/reference/radio/receive-number.md
@@ -1,14 +1,15 @@
 # Receive Number
 
-Reads the next radio packet if any and returns the first number.
+Receives the next number sent by a micro:bit in the same ``radio`` group.
 
 ### Return value
 
-* the first number [number](/reference/types/number) of the packet if any. `0` otherwise.
+* the first  [number](/reference/types/number) that the micro:bit received. If it did not receive any numbers, this function will return `0`.
 
-### Examples
+### Example: Simple number receiver
 
-Read the number broadcasted by other micro:bits.
+This example receives the number broadcasted another micro:bit and shows it
+as a bar graph.
 
 ```blocks
 radio.onDataReceived(() => {
@@ -16,7 +17,42 @@ radio.onDataReceived(() => {
 })
 ```
 
+### Example: Light level receiver 
+
+This example shows the light level from the [light level sender example](/reference/input/send-number)
+as a number.
+
+```blocks
+radio.setGroup(99)
+basic.forever(() => {
+    let level = radio.receiveNumber()
+    basic.showNumber(level)
+})
+```
+
+### Example: Mailbot
+
+This example receives the light level from the [light level sender example](/reference/input/send-number)
+and shows a text string like **ALERT** if the light level becomes much brighter.
+To find when the mail arrives, you can put the light level sender in your mailbox and it will
+tell you when someone opens the box. You can try this with a normal
+box too, like a present for a friend.
+
+```blocks
+radio.setGroup(99)
+let max = 0
+basic.forever(() => {
+    let level = radio.receiveNumber()
+    if (level > max) {
+        max = level
+    }
+    if (max > 10) {
+        basic.showString("ALERT")
+    }
+})
+```
+
 ### See also
 
-[receive number](/reference/input/receive-number), [on data received](/reference/radio/on-data-received)
+[send number](/reference/input/send-number), [on data received](/reference/radio/on-data-received)
 
diff --git a/docs/reference/radio/send-number.md b/docs/reference/radio/send-number.md
index 9b0686cb..45f70cf5 100644
--- a/docs/reference/radio/send-number.md
+++ b/docs/reference/radio/send-number.md
@@ -1,14 +1,16 @@
 # Send Number
 
-Broadcasts a number data packet to other micro:bits connected via ``radio``.
+Broadcast a number to other micro:bits connected via ``radio``.
 
 ### Parameters
 
-* packet - a number to be transmitted.
+* num - a number to send.
 
-### Examples
+### Example: Broadcasting acceleration
 
-Broadcasts the value of ``acceleration`` x to other micro:bits.
+This example broadcasts the value of your micro:bit's ``acceleration`` in the `x` direction 
+(left and right) to other micro:bits.
+This kind of program might be useful in a model car or model rocket.
 
 ```blocks
 input.onButtonPressed(Button.A, () => {
@@ -18,7 +20,9 @@ input.onButtonPressed(Button.A, () => {
 
 ### Light level sender
 
-This example broadcasts the level of the light around it:
+This example broadcasts the level of the light around it.
+You can do some interesting things with it if you use it along with the
+[Mailbot](/reference/radio/receive-number) example.
 
 ```blocks
 radio.setGroup(99)
@@ -28,38 +32,6 @@ basic.forever(() => {
 })
 ```
 
-This example shows the light level from the sender (above):
-
-```blocks
-radio.setGroup(99)
-basic.forever(() => {
-    let level = radio.receiveNumber()
-    basic.showNumber(level)
-})
-```
-
-### Mailbot
-
-This example takes the signal from the light level sender (above)
-and shows a text string if the light level becomes much brighter.
-You can put the light level sender in your mailbox and it will
-tell you when someone opens the box. You can try this with a normal
-box too, like a present.
-
-```blocks
-radio.setGroup(99)
-let max = 0
-basic.forever(() => {
-    let level = radio.receiveNumber()
-    if (level > max) {
-        max = level
-    }
-    if (max > 10) {
-        basic.showString("ALERT")
-    }
-})
-```
-
 ### See also
 
 [receive number](/reference/radio/receive-number), [on data received](/reference/radio/on-data-received)