Update 'pins' ref pages (#1733)

* Update 'pins' ref pages

* Some jsdoc touchups

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

@@ -8,11 +8,9 @@ pins.i2cReadBuffer(0, 0, false);
 
 A device connected to the I2C pins on the @boardname@ at the address is selected to read data from. If it has data available to transfer, the data is received and copied into a buffer for your program to use. Your program says how big (how many bytes to receive) the buffer should be. You won't get back that many bytes of data if the connected device has less to send than what you asked for.
 
-### ~hint
+### ~ 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

@@ -6,11 +6,9 @@ Read one number from an I2C address using a specified number format.
 pins.i2cReadNumber(0, NumberFormat.Int8LE, false);
 ```
 
-### ~hint
+### ~ 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

@@ -8,11 +8,9 @@ pins.i2cWriteBuffer(0, null, false);
 
 A device connected to the I2C pins on the @boardname@ at the address is selected to write data to. If the device is ready to take in your data, some or all of the data in your buffer is written to it.
 
-### ~hint
+### ~ 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

@@ -6,11 +6,9 @@ Write a number to a device at an I2C address using a specified number format.
 pins.i2cWriteNumber(0, 0, NumberFormat.Int8LE, true);
 ```
 
-### ~hint
+### ~ 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/_locales/core-strings.json

@@ -394,4 +394,4 @@
   "{id:category}Serial": "Serial",
   "{id:category}String": "String",
   "{id:category}Text": "Text"
-}
+}

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