Add some 'infrared' api docs (#326)

* Add some 'infrared' api docs

* Fix display messages

* Change discussion of distance to relative

* Include motor speed note

libs/infrared-sensor/docs/reference/sensors/infrared.md

@@ -0,0 +1,13 @@
+# Infrared sensor
+
+```cards
+sensors.infraredSensor1.onEvent(null, function () {});
+sensors.infraredSensor1.pauseUntil(null);
+sensors.infraredSensor1.proximity();
+```
+
+## See Also
+
+[on event](/reference/sensors/infrared/on-event),
+[pause until](/reference/sensors/infrared/pause-until),
+[proximity](/reference/sensors/infrared/proximity)

libs/infrared-sensor/docs/reference/sensors/infrared/on-event.md

@@ -0,0 +1,35 @@
+# on Event
+
+Run some code when an object is detected by the infrared sensor.
+
+```sig
+sensors.infraredSensor4.onEvent(InfraredSensorEvent.ObjectNear, function () {});
+```
+
+How an object is detected depends on the light _thresholds_ set for the sensor. A threshold is a number for relative distance of the a return of reflected infrared light. The brighter the light, the nearer the object is. The value for what _near_ means is determined by this threshold. A certain minimum amount of light returned is also set to determine that an object is detected. The two thresholds you can set are:
+
+* **near**: a distance to set to detect objects coming close
+* **detected**: the brightness of infrared light to needed to detect presence of another infrared transmitter.
+
+## Parameters
+
+* **event**: the object detection action to wait for. The detection types (events) are:
+> * ``detected``: some other object is sending out infrared light
+> * ``near``: the sensor detected something within the distance of the near threshold
+* **body**: the code you want to run when something is detected by infrared sensor.
+
+## Example
+
+When the ultrasonic sensor on port 4 detects a near object, display its distance on the screen.
+
+```blocks
+sensors.infraredSensor4.onEvent(InfraredSensorEvent.ObjectNear, function () {
+    brick.showString("Object detected at:", 1)
+    brick.showNumber(sensors.infraredSensor4.proximity(), 2)
+    brick.showString("percent of range", 3)
+})
+```
+
+## See also
+
+[pause until](/reference/sensors/infrared/pause-until)

libs/infrared-sensor/docs/reference/sensors/infrared/pause-until.md

@@ -0,0 +1,34 @@
+# pause Until
+
+Make your program wait until an some object is detected in proximity of the infrared sensor.
+
+```sig
+sensors.infraredSensor1.pauseUntil(InfraredSensorEvent.ObjectDetected);
+```
+
+How an object is detected depends on the light _thresholds_ set for the sensor. A threshold is a number for relative distance of the a return of reflected infrared light. The brighter the light, the nearer the object is. The value for what _near_ means is determined by this threshold. A certain minimum amount of light returned is also set to determine that an object is detected. The two thresholds you can set are:
+
+* **near**: a distance to set to detect objects coming close
+* **detected**: the brightness of infrared light to needed to detect presence of another infrared transmitter.
+
+## Parameters
+
+* **event**: the object detection action to wait for. The detection types (events) are:
+> * ``detected``: some other object is sending out infrared light
+> * ``near``: the sensor detected something within the distance of the near threshold
+
+## Example
+
+Wait for another object sending out infrared light. Show a message on the screen when it's dectected.
+
+```blocks
+brick.showString("Waiting for another", 1);
+brick.showString("robot to appear...", 2);
+sensors.infraredSensor1.pauseUntil(InfraredSensorEvent.ObjectDetected);
+brick.showString("Hey, I just saw", 1)
+brick.showString("Something!", 2);
+```
+
+## See also
+
+[on event](/reference/sensors/ultrasonic/on-event)

libs/infrared-sensor/docs/reference/sensors/infrared/proximity.md

@@ -0,0 +1,30 @@
+# proximity
+
+Get the promixity of an object measured by the infrared sensor.
+
+```sig
+sensors.infraredSensor1.proximity();
+```
+
+The proximity value returned is a number between `0` and `100` which is a _relative_ measurment of  distance to an object. A value of `0` means something is very close and `100` means something is far away. The proximity is determined by the amount of infrared light reflected back by an object. The proximity value for an object that has a lighter color and smooth surface will be less than an object at the same distance with a darker color and a rough surface.
+
+Proximity isn't an actual measurement units of distance, like in centimeters or meters, but it gives you an idea whether something is close or not so close.
+
+## Returns
+
+* a [number](/types/number) that is `0` for (very near) to `100` (far). The value is relative to the range of the infrared sensor.
+
+## Example
+
+When the infrared sensor on port 4 detects a near object, display its proximity value on the screen.
+
+```blocks
+sensors.infraredSensor4.onEvent(InfraredSensorEvent.ObjectNear, function () {
+    brick.clearScreen()
+    brick.showValue("proximity", sensors.infraredSensor4.proximity(), 1)
+})
+```
+
+## See also
+
+[on event](/reference/sensors/infrared/on-event), [pause until](/reference/sensors/infrared/pause-until)

libs/infrared-sensor/ir.ts

@@ -184,7 +184,7 @@ namespace sensors {
          * Registers code to run when an object is getting near.
          * @param handler the code to run when detected
          */
-        //% help=input/infrared/on
+        //% help=sensors/infrared/on-event
         //% block="on %sensor|%event"
         //% blockId=infraredOn
         //% parts="infraredsensor"
@@ -199,7 +199,7 @@ namespace sensors {
         /**
          * Waits for the event to occur
          */
-        //% help=input/ultrasonic/wait
+        //% help=sensors/infrared/pause-until
         //% block="pause until %sensor| %event"
         //% blockId=infraredwait
         //% parts="infraredsensor"
@@ -215,7 +215,7 @@ namespace sensors {
          * Get the promixity measured by the infrared sensor, from ``0`` (close) to ``100`` (far)
          * @param sensor the infrared sensor
          */
-        //% help=input/infrared/proximity
+        //% help=sensors/infrared/proximity
         //% block="%sensor|proximity"
         //% blockId=infraredGetProximity
         //% parts="infrared"

libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/on-event.md

@@ -20,7 +20,7 @@ Both **near** and **far** have distance thresholds set in centimeters. The **det
 > * ``object detected``: some other object is sending out an ultrasonic sound
 > * ``object near``: the sensor detected something within the distance of the near threshold
 > * ``object far``: the sensor detected somethin within the distance of the far threshold
-* **body**: the code you want to run when something happens to the touch sensor.
+* **body**: the code you want to run when something is dectected by the ultrasonic sensor.
 
 ## Example
 

libs/ultrasonic-sensor/docs/reference/sensors/ultrasonic/pause-until.md

@@ -17,9 +17,9 @@ Both **near** and **far** have distance thresholds set in centimeters. The **det
 ## Parameters
 
 * **event**: the object detection action to wait for. The detection types (events) are:
-> * ``object detected``: some other object is sending out an ultrasonic sound
-> * ``object near``: the sensor detected something within the distance of the near threshold
-> * ``object far``: the sensor detected somethin within the distance of the far threshold
+> * ``detected``: some other object is sending out an ultrasonic sound
+> * ``near``: the sensor detected something within the distance of the near threshold
+> * ``far``: the sensor detected somethin within the distance of the far threshold
 
 ## Example