Update 'pins' ref pages (#1733)

* Update 'pins' ref pages

* Some jsdoc touchups

docs/reference/pins/i2c-read-buffer.md

@@ -10,9 +10,7 @@ A device connected to the I2C pins on the @boardname@ at the address is selected
 
 ### ~ hint
 
-**Simulator**
+**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
-
-This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

docs/reference/pins/i2c-read-number.md

@@ -8,9 +8,7 @@ pins.i2cReadNumber(0, NumberFormat.Int8LE, false);
 
 ### ~ hint
 
-**Simulator**
+**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
-
-This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

docs/reference/pins/i2c-write-buffer.md

@@ -10,9 +10,7 @@ A device connected to the I2C pins on the @boardname@ at the address is selected
 
 ### ~ hint
 
-**Simulator**
+**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
-
-This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

docs/reference/pins/i2c-write-number.md

@@ -8,9 +8,7 @@ pins.i2cWriteNumber(0, 0, NumberFormat.Int8LE, true);
 
 ### ~ hint
 
-**Simulator**
+**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
-
-This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

docs/reference/pins/on-pulsed.md

@@ -1,22 +1,26 @@
-# On Pulsed
+# on Pulsed
 
-Configure the specified pin for digital input, and then
+Set a pin to use as a digital input and then run some code when the pin pulses either ``high`` or ``low``.
-execute the associated code block whenever the pin
-pulses **High** or **Low** (as specified).
 
 ```sig
 pins.onPulsed(DigitalPin.P0, PulseValue.High, () => { });
 ```
 
+### ~ hint
+
+**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+
+### ~
+
 ## Parameters
 
-* ``name``: The @boardname@ hardware pin to configure (``P0`` through ``P20``)
+* **name**: the @boardname@ hardware pin to set for digital input (``P0`` through ``P20``).
-* ``pulse``: Which state will cause the associated block to execute (**High** or **Low**)
+* **pulse**: the state that will cause the code inside the block to run, either ``high`` or ``low``.
+* **body**: the code to run when the pin in **name** is pulsed to the state set in **pulse**.
 
 ## Example
 
-The following example configures pin ``P2`` for digital input,
+Configure pin ``P2`` for digital input. Display the string `"LOW"` whenever ``P2`` pulses ``low``.
-and then displays the string `LOW` whenever ``P2`` pulses low.
 
 ```blocks
 pins.onPulsed(DigitalPin.P2, PulseValue.Low, () => {

docs/reference/pins/pulse-duration.md

@@ -1,21 +1,26 @@
-# Pulse Duration
+# pulse Duration
 
-Gets the duration of the last pulse in microseconds.
+Get the duration of the last pulse in microseconds.
-
-This function should be called from an **on pulsed** handler.
 
 ```sig
 pins.pulseDuration();
 ```
 
+A pin pulse is detected in the [onPulsed](/reference/pins/on-pulsed) event. You use **pulseDuration** inside that event to get the duration of the pulse that triggered the event.
+
+### ~ hint
+
+**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+
+### ~
+
 ## Returns
 
-The duration of the last pulse, measured in microseconds.
+* a [number](/types/number) that is the duration of the last pulse, measured in microseconds.
 
 ## Example
 
-The following example waits for pin ``P0`` to be pulsed high, and then
+Wait for pin ``P0`` to be pulsed high. Display the duration of the pulse in microseconds on the LED screen.
-displays the duration of the pulse in microseconds on the LED screen.
 
 ```blocks
 pins.onPulsed(DigitalPin.P0, PulseValue.High, () => {

docs/reference/pins/pulse-in.md

@@ -1,7 +1,6 @@
-# Pulse In
+# pulse In
 
-Returns the duration of a pulse (high or low) from a [pin](/device/pins) on
+Get the duration, in microseconds, of a pulse (high or low) from one of the pins.
-the @boardname@ board in microseconds.
 
 ```sig
 pins.pulseIn(DigitalPin.P0, PulseValue.High)
@@ -14,19 +13,25 @@ Please read the [page about pins](/device/pins) carefully.
 
 ## ~
 
+### ~ hint
+
+**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+
+### ~
+
 ## Parameters
 
-* ``name`` is a [string](/types/string) that stores the name of the pin (``P0``, ``P1``, or ``P2``, up through ``P20``)
+* ``name`` the name of the pin (``P0``, ``P1``, or ``P2``, up through ``P20``).
-* ``value`` is the value of the pulse, ``high`` or ``low``
+* ``value`` the value of the pulse, either ``high`` or ``low``.
-* ``maxDuration``, maximum duration in micro-seconds. If no pulse is received 
+* ``maxDuration``, maximum duration to wait for the pulse in microseconds. If no pulse is received, the duration returned is `0`.
 
 ## Returns
 
-* a [number](/types/number) that represents the pulse duration in micro-seconds
+* a [number](/types/number) that is the pulse duration in microseconds.
 
 ## Example: Measuring distance with a sonar
 
-The following script sends a pulse on ``P0`` and reads the pulse returned by a HC-SR04 sonar to determine the distance of the object in front of the sensor.
+Send a pulse on ``P0`` and read a pulse returned by a HC-SR04 sonar ultrasonic sensor. The sensor determines the distance of the object in front of it.
 
 ```blocks
 basic.forever(() => {
@@ -43,12 +48,6 @@ basic.forever(() => {
 })
 ```
 
-### ~hint
-
-This function is not supported in the simulator.
-
-### ~
-
 ## See also
 
-[digital write pin](/reference/pins/digital-write-pin),
+[digital write pin](/reference/pins/digital-write-pin)

docs/reference/pins/set-events.md

@@ -1,4 +1,4 @@
-# Set Events
+# set Events
 
 Configure the type of events emitted by a given pin.
 
@@ -6,6 +6,12 @@ Configure the type of events emitted by a given pin.
 pins.setEvents(DigitalPin.P0, PinEventType.Edge);
 ```
 
+### ~ hint
+
+**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+
+### ~
+
 ## Parameters
 
 * ``name``: The @boardname@ hardware pin to configure (``P0`` through ``P20``)
@@ -13,8 +19,7 @@ pins.setEvents(DigitalPin.P0, PinEventType.Edge);
 
 ## Example
 
-The following example configures pin ``P0`` and then
+The following example configures pin ``P0`` and then subscribes to the rise and fall events.
-subscribes to the rise and fall events.
 
 ```blocks
 control.onEvent(control.eventSourceId(EventBusSource.MICROBIT_ID_IO_P0),  control.eventValueId(EventBusValue.MICROBIT_PIN_EVT_RISE), () => {

docs/reference/pins/spi-format.md

@@ -1,16 +1,43 @@
-# SPI Format
+# spi Format
 
-Sets the SPI format
+Set the Serial Peripheral Interface (SPI) format.
 
 ```sig
 pins.spiFormat(8, 3);
 ```
 
+The data sent over a SPI connection has a number of _bits_ to represent each value. Also, position of the clock signal (SCK), ``high`` or ``low``, and the exact time when a data value is read is determined by the SPI _mode_. Both the bits and mode values together are called the _SPI format_.
+
+### ~ hint
+
+**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+
+### ~
+
+The default number of bits is `8` and the default mode value is `3`.
+
 ## Parameters
 
-* ``bits``, 
+* **bits**: the [number](types/number) of bits for each data value sent and received on the SPI connection. This value must be ``8`` since only 8 bits is currently supported for SPI data values. 
-* ``mode``,
+* **mode**: a [number](/types/number) that is the mode value for the SPI clock (**SCK**) signalling. The different modes are:
+>* `0`: the data line is active when **SCK** goes to ``high`` and the data values are read when **SCK** goes to ``high``
+>* `1`: the data line is active when **SCK** goes to ``high`` and the data values are read when **SCK** goes to ``low``
+>* `2`: the data line is active when **SCK** goes to ``low`` and the data values are read when **SCK** goes to ``high``
+>* `3`: the data line is active when **SCK** goes to ``low`` and the data values are read when **SCK** goes to ``low``
+
+## Example
+
+Set the pins and format for the SPI connection.
+
+```blocks
+pins.spiPins(DigitalPin.P15, DigitalPin.P14, DigitalPin.P13);
+pins.spiFormat(8, 3);
+```
 
 ## See also
 
-[SPI](https://developer.mbed.org/handbook/SPI)
+[spi write](/reference/pins/spi-write),
+[spi pins](/reference/pins/spi-pins),
+[spi frequency](/reference/pins/spi-frequency)
+
+[SPI Programming](https://developer.mbed.org/handbook/SPI)

docs/reference/pins/spi-frequency.md

@@ -1,18 +1,28 @@
-# SPI Frequency
+# spi Frequency
 
-Set the SPI clock frequency.
+Set the Serial Peripheral Interface (SPI) clock frequency.
 
 ```sig
 pins.spiFrequency(1000000);
 ```
 
+The @boardname@ sets the rate of data transfer and control timing for a SPI connection. This data rate and timing signal is controlled by the **SCK** pin. The signal on this pin is _clocked_ using the frequency set for it.
+
+### ~ hint
+
+**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+
+### ~
+
+The default clock frequency is 1 Mhz (10000000 Hz). You can set the frequency for the SPI connection to some other value if you need a different data rate.
+
 ## Parameters
 
 * **frequency**: a [number](/types/number) to set as the frequency for SPI bus clock. This value is the number of clock changes per second (Hz).
 
 ## Example
 
-Read the value of the _WHOAMI_ register from the device connected to the SPI bus. The chip select line is connected to pin **0** and the SPI signals use pins **13**, **14**, and **15**.
+Read the value of the _WHOAMI_ register from the device connected to the SPI bus. The chip select line is connected to pin **0** and the SPI signals use pins **P13**, **P14**, and **P15**.
 
 ```blocks
 pins.digitalWritePin(DigitalPin.P0, 1);
@@ -29,4 +39,8 @@ serial.writeLine("WHOAMI register value: " + whoami)
 
 ## See also
 
-[SPI](https://developer.mbed.org/handbook/SPI)
+[spi write](/reference/pins/spi-write),
+[spi pins](/reference/pins/spi-pins),
+[spi format](/reference/pins/spi-format)
+
+[SPI Programming](https://developer.mbed.org/handbook/SPI)

docs/reference/pins/spi-pins.md

@@ -1,17 +1,43 @@
-# SPI Pins
+# spi Pins
 
-Sets the SPI MOSI, MISO and SCK pins
+Set the Serial Peripheral Interface (SPI) signalling pins
 
 ```sig
 pins.spiPins(DigitalPin.P0, DigitalPin.P1, DigitalPin.P2);
 ```
 
+To configure the @boardname@ to write to an external device using a SPI connection, each SPI signal line is assigned to unique a pin. A SPI connection uses 3 signalling lines called **MOSI**, **MISO**, and **SCK**.
+
+### ~ hint
+
+**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+
+### ~
+
+If you don't set the pins for the SPI connection, the default pin assignments are used:
+
+* **P15** = **MOSI**, @boardname@ SPI data output pin
+* **P14** = **MISO**, @boardname@ SPI data input pin
+* **P13** = **SCK**, @boardname@ SPI serial clock output pin
+
 ## Parameters
 
-* ``MOSI``, the ``MOSI`` pin
+* **mosi**: the pin for SPI data output, the **MOSI** signal pin.
-* ``MISO``, the ``MISO`` pin
+* **miso**: the pin for SPI data input, the **MISO** signal pin.
-* ``SCK``, the ``SCK`` pin
+* **sck**: the pin for SPI serial clock output, the **SCK** signal pin.
+
+## Example
+
+Set the pin assignments for a SPI connection to the default pins.
+
+```blocks
+pins.spiPins(DigitalPin.P15, DigitalPin.P14, DigitalPin.P13);
+```
 
 ## See also
 
-[SPI](https://developer.mbed.org/handbook/SPI)
+[spi write](/reference/pins/spi-write),
+[spi frequency](/reference/pins/spi-frequency),
+[spi format](/reference/pins/spi-format)
+
+[SPI Programming](https://developer.mbed.org/handbook/SPI)

docs/reference/pins/spi-write.md

@@ -1,19 +1,48 @@
-# SPI Write
+# spi Write
 
-Write to the SPI Slave and return the response.
+Write a data value to the SPI slave device and return its response.
 
 ```sig
 pins.spiWrite(0);
 ```
 
+Data values are written to a SPI slave device connected to the @boardname@ by the [SPI pins](/reference/pins/spi-pins). The data value might be either a command for the connected device or some value for its use. If the write operation causes the connected device to send a value back to the @boardname@, this will be the return value for the **spiWrite** function.
+
+### ~ hint
+
+**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+
+### ~
+
 ## Parameters
 
-* ``value``: value	Data to be sent to the SPI slave
+* ``value``: a [number](/types/number) which is the data value to send to the SPI slave device.
 
 ## Returns
 
-* a [number](/types/number) Response from the SPI slave
+* a [number](/types/number) value which is the response from the SPI slave device.
+
+## Example
+
+Send the command to read the value of the _WHOAMI_ register from the device connected to the SPI bus. The chip select line is connected to pin **0** and the SPI signals use pins **P13**, **P14**, and **P15**.
+
+```blocks
+pins.digitalWritePin(DigitalPin.P0, 1);
+pins.spiPins(DigitalPin.P15, DigitalPin.P14, DigitalPin.P13);
+pins.spiFormat(8, 3);
+pins.spiFrequency(1000000);
+pins.digitalWritePin(DigitalPin.P0, 0);
+let command = pins.spiWrite(143);
+let whoami = pins.spiWrite(0);
+pins.digitalWritePin(DigitalPin.P0, 1);
+basic.showNumber(whoami);
+serial.writeLine("WHOAMI register value: " + whoami)
+```
 
 ## See also
 
-[SPI](https://developer.mbed.org/handbook/SPI)
+[spi pins](/reference/pins/spi-pins),
+[spi frequency](/reference/pins/spi-frequency),
+[spi format](/reference/pins/spi-format)
+
+[SPI Programming](https://developer.mbed.org/handbook/SPI)

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

@@ -443,15 +443,15 @@
   "pins.P7": "Pin P7",
   "pins.P8": "Pin P8",
   "pins.P9": "Pin P9",
-  "pins.analogPitch": "Emits a Pulse-width modulation (PWM) signal to the current pitch pin. Use `analog set pitch pin` to define the pitch pin.",
+  "pins.analogPitch": "Emit a plse-width modulation (PWM) signal to the current pitch pin. Use `analog set pitch pin` to define the pitch pin.",
   "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, 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": "Configure the pulse-width modulation (PWM) period of the analog output in microseconds.\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, eg: AnalogPin.P0",
-  "pins.analogSetPitchPin": "Sets the pin used when using `analog pitch` or music.",
+  "pins.analogSetPitchPin": "Set 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, eg: AnalogPin.P0",
@@ -469,38 +469,38 @@
   "pins.i2cReadNumber": "Read one number from 7-bit I2C address.",
   "pins.i2cWriteBuffer": "Write bytes to a 7-bit I2C `address`.",
   "pins.i2cWriteNumber": "Write one number to a 7-bit I2C address.",
-  "pins.map": "Re-maps a number from one range to another. That is, a value of ``from low`` would get mapped to ``to low``, a value of ``from high`` to ``to high``, values in-between to values in-between, etc.",
+  "pins.map": "Map a number from one range to another. That is, a value of ``from low`` would get mapped to ``to low``, a value of ``from high`` to ``to high``, values in-between to values in-between, etc.",
   "pins.map|param|fromHigh": "the upper bound of the value's current range, eg: 1023",
   "pins.map|param|fromLow": "the lower bound of the value's current range",
   "pins.map|param|toHigh": "the upper bound of the value's target range, eg: 4",
   "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": "Configure the pin as a digital input and generate an event when the pin is pulsed 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.pulseDuration": "Get the duration of the last pulse in microseconds. This function should be called from a ``onPulsed`` handler.",
-  "pins.pulseIn": "Returns the duration of a pulse in microseconds",
+  "pins.pulseIn": "Return the duration of a pulse at a pin in microseconds.",
   "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": "Configure the IO pin as an analog/pwm output and set a pulse width. The period is 20 ms period and the pulse width is set based on the value given in **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": "Write 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, eg: AnalogPin.P0",
   "pins.servoWritePin|param|value": "angle or rotation speed, eg:180,90,0",
-  "pins.setEvents": "Configures the events emitted by this pin. Events can be subscribed to\nusing ``control.onEvent()``.",
+  "pins.setEvents": "Configure the events emitted by this pin. Events can be subscribed to\nusing ``control.onEvent()``.",
   "pins.setEvents|param|name": "pin to set the event mode on, eg: DigitalPin.P0",
   "pins.setEvents|param|type": "the type of events for this pin to emit, eg: PinEventType.Edge",
-  "pins.setPull": "Configures the pull of this pin.",
+  "pins.setPull": "Configure the pull directiion of of a pin.",
   "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.spiFormat": "Sets the SPI bits and mode",
+  "pins.spiFormat": "Set the SPI bits and mode",
   "pins.spiFormat|param|bits": "the number of bits, eg: 8",
   "pins.spiFormat|param|mode": "the mode, eg: 3",
-  "pins.spiFrequency": "Sets the SPI frequency",
+  "pins.spiFrequency": "Set the SPI frequency",
   "pins.spiFrequency|param|frequency": "the clock frequency, eg: 1000000",
-  "pins.spiPins": "Sets the MOSI, MISO, SCK pins used by the SPI instance",
+  "pins.spiPins": "Set the MOSI, MISO, SCK pins used by the SPI connection",
   "pins.spiWrite": "Write to the SPI slave and return the response",
   "pins.spiWrite|param|value": "Data to be sent to the SPI slave",
   "serial": "Reading and writing data over a serial connection.",

libs/core/pins.cpp

@@ -184,7 +184,7 @@ namespace pins {
     }
 
     /**
-     * Configures the Pulse-width modulation (PWM) of the analog output to the given value in **microseconds** or `1/1000` milliseconds.
+     * Configure the pulse-width modulation (PWM) period of the analog output in microseconds.
      * 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, eg: AnalogPin.P0
      * @param micros period in micro seconds. eg:20000
@@ -198,7 +198,7 @@ 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``.
+    * Configure the pin as a digital input and generate an event when the pin is pulsed either high or low.
     * @param name digital pin to register to, eg: DigitalPin.P0
     * @param pulse the value of the pulse, eg: PulseValue.High
     */
@@ -215,7 +215,7 @@ namespace pins {
     }
 
     /**
-    * Gets the duration of the last pulse in micro-seconds. This function should be called from a ``onPulsed`` handler.
+    * Get the duration of the last pulse in microseconds. This function should be called from a ``onPulsed`` handler.
     */
     //% help=pins/pulse-duration advanced=true
     //% blockId=pins_pulse_duration block="pulse duration (µs)"
@@ -225,10 +225,10 @@ namespace pins {
     }
 
     /**
-    * Returns the duration of a pulse in microseconds
+    * Return the duration of a pulse at a pin in microseconds.
     * @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
+    * @param maximum duration in microseconds
     */
     //% blockId="pins_pulse_in" block="pulse in (µs)|pin %name|pulsed %value"
     //% weight=20 advanced=true
@@ -257,7 +257,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).
+     * Write 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, eg: AnalogPin.P0
      * @param value angle or rotation speed, eg:180,90,0
      */
@@ -272,7 +272,7 @@ namespace pins {
     }
 
     /**
-     * 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.
+     * Configure the IO pin as an analog/pwm output and set a pulse width. The period is 20 ms period and the pulse width is set based on the value given in **microseconds** or `1/1000` milliseconds.
      * @param name pin name
      * @param micros pulse duration in micro seconds, eg:1500
      */
@@ -288,7 +288,7 @@ namespace pins {
     MicroBitPin* pitchPin = NULL;
 
     /**
-     * Sets the pin used when using `analog pitch` or music.
+     * Set the pin used when using analog pitch or music.
      * @param name pin to modulate pitch from
      */
     //% blockId=device_analog_set_pitch_pin block="analog set pitch pin %name"
@@ -300,7 +300,7 @@ namespace pins {
     }
 
     /**
-     * Emits a Pulse-width modulation (PWM) signal to the current pitch pin. Use `analog set pitch pin` to define the pitch pin.
+     * Emit a plse-width modulation (PWM) signal to the current pitch pin. Use `analog set pitch pin` to define the pitch pin.
      * @param frequency frequency to modulate in Hz.
      * @param ms duration of the pitch in milli seconds.
      */
@@ -326,7 +326,7 @@ namespace pins {
 
 
     /**
-    * Configures the pull of this pin.
+    * Configure the pull directiion of of a pin.
     * @param name pin to set the pull mode on, eg: DigitalPin.P0
     * @param pull one of the mbed pull configurations, eg: PinPullMode.PullUp
     */
@@ -343,7 +343,7 @@ namespace pins {
     }
 
     /**
-    * Configures the events emitted by this pin. Events can be subscribed to
+    * Configure the events emitted by this pin. Events can be subscribed to
     * using ``control.onEvent()``.
     * @param name pin to set the event mode on, eg: DigitalPin.P0
     * @param type the type of events for this pin to emit, eg: PinEventType.Edge
@@ -405,7 +405,7 @@ namespace pins {
     }
 
     /**
-    * Sets the SPI frequency
+    * Set the SPI frequency
     * @param frequency the clock frequency, eg: 1000000
     */
     //% help=pins/spi-frequency weight=4 advanced=true
@@ -416,7 +416,7 @@ namespace pins {
     }
 
     /**
-    * Sets the SPI bits and mode
+    * Set the SPI bits and mode
     * @param bits the number of bits, eg: 8
     * @param mode the mode, eg: 3
     */
@@ -428,7 +428,7 @@ namespace pins {
     }
 
     /**
-    * Sets the MOSI, MISO, SCK pins used by the SPI instance
+    * Set the MOSI, MISO, SCK pins used by the SPI connection
     *
     */
     //% help=pins/spi-pins weight=2 advanced=true

libs/core/pins.ts

@@ -5,7 +5,7 @@
 //% advanced=true
 namespace pins {
     /**
-     * Re-maps a number from one range to another. That is, a value of ``from low`` would get mapped to ``to low``, a value of ``from high`` to ``to high``, values in-between to values in-between, etc.
+     * Map a number from one range to another. That is, a value of ``from low`` would get mapped to ``to low``, a value of ``from high`` to ``to high``, values in-between to values in-between, etc.
      * @param value value to map in ranges
      * @param fromLow the lower bound of the value's current range
      * @param fromHigh the upper bound of the value's current range, eg: 1023

libs/core/shims.d.ts

@@ -608,7 +608,7 @@ declare namespace pins {
     function analogWritePin(name: AnalogPin, value: int32): void;
 
     /**
-     * Configures the Pulse-width modulation (PWM) of the analog output to the given value in **microseconds** or `1/1000` milliseconds.
+     * Configure the pulse-width modulation (PWM) period of the analog output in microseconds.
      * 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, eg: AnalogPin.P0
      * @param micros period in micro seconds. eg:20000
@@ -620,7 +620,7 @@ declare namespace pins {
     function analogSetPeriod(name: AnalogPin, micros: int32): void;
 
     /**
-     * Configures this pin to a digital input, and generates events where the timestamp is the duration that this pin was either ``high`` or ``low``.
+     * Configure the pin as a digital input and generate an event when the pin is pulsed either high or low.
      * @param name digital pin to register to, eg: DigitalPin.P0
      * @param pulse the value of the pulse, eg: PulseValue.High
      */
@@ -631,7 +631,7 @@ declare namespace pins {
     function onPulsed(name: DigitalPin, pulse: PulseValue, body: () => void): void;
 
     /**
-     * Gets the duration of the last pulse in micro-seconds. This function should be called from a ``onPulsed`` handler.
+     * Get the duration of the last pulse in microseconds. This function should be called from a ``onPulsed`` handler.
      */
     //% help=pins/pulse-duration advanced=true
     //% blockId=pins_pulse_duration block="pulse duration (µs)"
@@ -639,10 +639,10 @@ declare namespace pins {
     function pulseDuration(): int32;
 
     /**
-     * Returns the duration of a pulse in microseconds
+     * Return the duration of a pulse at a pin in microseconds.
      * @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
+     * @param maximum duration in microseconds
      */
     //% blockId="pins_pulse_in" block="pulse in (µs)|pin %name|pulsed %value"
     //% weight=20 advanced=true
@@ -652,7 +652,7 @@ declare namespace pins {
     function pulseIn(name: DigitalPin, value: PulseValue, maxDuration?: int32): int32;
 
     /**
-     * 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).
+     * Write 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, eg: AnalogPin.P0
      * @param value angle or rotation speed, eg:180,90,0
      */
@@ -665,7 +665,7 @@ declare namespace pins {
     function servoWritePin(name: AnalogPin, value: int32): void;
 
     /**
-     * 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.
+     * Configure the IO pin as an analog/pwm output and set a pulse width. The period is 20 ms period and the pulse width is set based on the value given in **microseconds** or `1/1000` milliseconds.
      * @param name pin name
      * @param micros pulse duration in micro seconds, eg:1500
      */
@@ -676,7 +676,7 @@ declare namespace pins {
     function servoSetPulse(name: AnalogPin, micros: int32): void;
 
     /**
-     * Sets the pin used when using `analog pitch` or music.
+     * Set the pin used when using analog pitch or music.
      * @param name pin to modulate pitch from
      */
     //% blockId=device_analog_set_pitch_pin block="analog set pitch pin %name"
@@ -686,7 +686,7 @@ declare namespace pins {
     function analogSetPitchPin(name: AnalogPin): void;
 
     /**
-     * Emits a Pulse-width modulation (PWM) signal to the current pitch pin. Use `analog set pitch pin` to define the pitch pin.
+     * Emit a plse-width modulation (PWM) signal to the current pitch pin. Use `analog set pitch pin` to define the pitch pin.
      * @param frequency frequency to modulate in Hz.
      * @param ms duration of the pitch in milli seconds.
      */
@@ -695,7 +695,7 @@ declare namespace pins {
     function analogPitch(frequency: int32, ms: int32): void;
 
     /**
-     * Configures the pull of this pin.
+     * Configure the pull directiion of of a pin.
      * @param name pin to set the pull mode on, eg: DigitalPin.P0
      * @param pull one of the mbed pull configurations, eg: PinPullMode.PullUp
      */
@@ -706,7 +706,7 @@ declare namespace pins {
     function setPull(name: DigitalPin, pull: PinPullMode): void;
 
     /**
-     * Configures the events emitted by this pin. Events can be subscribed to
+     * Configure the events emitted by this pin. Events can be subscribed to
      * using ``control.onEvent()``.
      * @param name pin to set the event mode on, eg: DigitalPin.P0
      * @param type the type of events for this pin to emit, eg: PinEventType.Edge
@@ -745,7 +745,7 @@ declare namespace pins {
     function spiWrite(value: int32): int32;
 
     /**
-     * Sets the SPI frequency
+     * Set the SPI frequency
      * @param frequency the clock frequency, eg: 1000000
      */
     //% help=pins/spi-frequency weight=4 advanced=true
@@ -753,7 +753,7 @@ declare namespace pins {
     function spiFrequency(frequency: int32): void;
 
     /**
-     * Sets the SPI bits and mode
+     * Set the SPI bits and mode
      * @param bits the number of bits, eg: 8
      * @param mode the mode, eg: 3
      */
@@ -762,7 +762,7 @@ declare namespace pins {
     function spiFormat(bits: int32, mode: int32): void;
 
     /**
-     * Sets the MOSI, MISO, SCK pins used by the SPI instance
+     * Set the MOSI, MISO, SCK pins used by the SPI connection
      *
      */
     //% help=pins/spi-pins weight=2 advanced=true