Fix typos in pin pulse docs (#5381)

* fix typos in pin pulse docs * more pitch pin edits * reformat simulator hint
microsoft · Jan 30, 2024 · b97b3ca · b97b3ca
1 parent a5d25f8
commit b97b3ca
Show file tree

Hide file tree

Showing 17 changed files with 66 additions and 30 deletions.
diff --git a/docs/reference/pins/analog-pitch.md b/docs/reference/pins/analog-pitch.md
@@ -1,24 +1,27 @@
 # Analog Pitch
 
-Emits a Pulse With Modulation (PWM) signal to the pin ``P0``.
-Use [analog set pitch pin](/reference/pins/analog-set-pitch-pin) to set the current pitch pin.
+Sends a pulse-width modulation (PWM) signal to the pin ``P0``.
 
 ```sig
 pins.analogPitch(440, 300)
 ```
 
+The PWM signal is sent to the current pitch pin. Use [analog set pitch pin](/reference/pins/analog-set-pitch-pin) to first set the current pitch pin.
+
 ## Parameters
 
-* `frequency` : [Number](/types/number)
-* `ms`: [Number](/types/number)
+* **frequency**: a [number](/types/number) which is the frequency of the PWM signal at the pitch pin.
+* **ms**: a [number](/types/number) in milliseconds that is the duration of the signal at the pitch pin.
 
 ## Example
 
+Set the pitch pin to `P1` and send a 440 Hz tone for 1 second.
+
 ```blocks
-pins.analogSetPitchPin(AnalogPin.P0);
+pins.analogSetPitchPin(AnalogPin.P0)
 let frequency1 = 440
 let duration = 1000
-pins.analogSetPitchPin(AnalogPin.P1);
+pins.analogSetPitchPin(AnalogPin.P1)
 pins.analogPitch(frequency1, duration)
 ```
 

diff --git a/docs/reference/pins/analog-read-pin.md b/docs/reference/pins/analog-read-pin.md
@@ -9,21 +9,23 @@ pins.analogReadPin(AnalogPin.P0)
 
 ## Parameters
 
-* ``name`` is a [string](/types/string) with the name of the pin
-  you say (`P0` through `P4`, or `P10`)
+* **name**: is a [string](/types/string) with the name of the pin
+you say (`P0` through `P4`, or `P10`).
 
 ## Returns
 
 * a [number](/types/number) from `0` through `1023`
 
+## Example
+
 This program reads pin `P1` and shows the number
 on the LED screen.
 
 ```blocks
-basic.forever(() => {
+basic.forever(function() {
     let value = pins.analogReadPin(AnalogPin.P1)
     basic.showNumber(value)
-});
+})
 ```
 
 ### ~hint

diff --git a/docs/reference/pins/analog-set-period.md b/docs/reference/pins/analog-set-period.md
@@ -1,6 +1,6 @@
 # Analog Set Period
 
-Configure the period of Pulse Width Modulation (PWM) on the specified 
+Configure the period of pulse-width modulation (PWM) on the specified 
 analog [pin](/device/pins).
 Before you call this function, you should set the specified pin as analog.
 
@@ -10,8 +10,10 @@ pins.analogSetPeriod(AnalogPin.P0, 20000)
 
 ## Parameters
 
-* ``name``: a [string](/types/string) that specifies the pin to configure (`P0` through `P4`, or `P10`)
-* ``micros``: a [number](/types/number) that specifies the analog period in microseconds.
+* **name**: a [string](/types/string) that specifies the pin to configure (`P0` through `P4`, or `P10`)
+* **micros**: a [number](/types/number) that specifies the analog period in microseconds.
+
+## Example
 
 The following code first sets `P0` to analog with **analog write
 pin**, and then sets the PWM period of `P0` to 20,000 microseconds.

diff --git a/docs/reference/pins/analog-set-pitch-pin.md b/docs/reference/pins/analog-set-pitch-pin.md
@@ -12,6 +12,8 @@ pins.analogSetPitchPin(AnalogPin.P0)
 
 ## Example
 
+Set the pitch pin to `P0` and send a 440 Hz tone for 1 second.
+
 ```blocks
 pins.analogSetPitchPin(AnalogPin.P0)
 let frequency = 440
@@ -26,5 +28,8 @@ pins.analogPitch(frequency, duration)
 
 ## See also
 
-[@boardname@ pins](/device/pins), [analog set period](/reference/pins/analog-set-period), [analog pitch](/reference/pins/analog-pitch)
+[@boardname@ pins](/device/pins),
+[analog set period](/reference/pins/analog-set-period),
+[analog pitch](/reference/pins/analog-pitch),
+[set audio pin](/reference/pins/set-audio-pin)
 
diff --git a/docs/reference/pins/i2c-read-buffer.md b/docs/reference/pins/i2c-read-buffer.md
@@ -10,7 +10,9 @@ A device connected to the I2C pins on the @boardname@ at the address is selected
 
 ### ~ hint
 
-**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+#### Simulator
+
+This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

diff --git a/docs/reference/pins/i2c-read-number.md b/docs/reference/pins/i2c-read-number.md
@@ -8,7 +8,9 @@ pins.i2cReadNumber(0, NumberFormat.Int8LE, false);
 
 ### ~ hint
 
-**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+#### Simulator
+
+This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

diff --git a/docs/reference/pins/i2c-write-buffer.md b/docs/reference/pins/i2c-write-buffer.md
@@ -10,7 +10,9 @@ A device connected to the I2C pins on the @boardname@ at the address is selected
 
 ### ~ hint
 
-**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+#### Simulator
+
+This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

diff --git a/docs/reference/pins/i2c-write-number.md b/docs/reference/pins/i2c-write-number.md
@@ -8,7 +8,9 @@ pins.i2cWriteNumber(0, 0, NumberFormat.Int8LE, true);
 
 ### ~ hint
 
-**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+#### Simulator
+
+This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

diff --git a/docs/reference/pins/on-pulsed.md b/docs/reference/pins/on-pulsed.md
@@ -8,7 +8,9 @@ pins.onPulsed(DigitalPin.P0, PulseValue.High, () => { });
 
 ### ~ hint
 
-**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+#### Simulator
+
+This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

diff --git a/docs/reference/pins/pulse-duration.md b/docs/reference/pins/pulse-duration.md
@@ -10,7 +10,9 @@ A pin pulse is detected in the [onPulsed](/reference/pins/on-pulsed) event. You
 
 ### ~ hint
 
-**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+#### Simulator
+
+This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

diff --git a/docs/reference/pins/pulse-in.md b/docs/reference/pins/pulse-in.md
@@ -15,7 +15,9 @@ 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.
+#### Simulator
+
+This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

diff --git a/docs/reference/pins/set-events.md b/docs/reference/pins/set-events.md
@@ -8,7 +8,9 @@ pins.setEvents(DigitalPin.P0, PinEventType.Edge);
 
 ### ~ hint
 
-**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+#### Simulator
+
+This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

diff --git a/docs/reference/pins/spi-format.md b/docs/reference/pins/spi-format.md
@@ -10,7 +10,9 @@ The data sent over a SPI connection has a number of _bits_ to represent each val
 
 ### ~ hint
 
-**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+#### Simulator
+
+This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

diff --git a/docs/reference/pins/spi-frequency.md b/docs/reference/pins/spi-frequency.md
@@ -10,7 +10,9 @@ The @boardname@ sets the rate of data transfer and control timing for a SPI conn
 
 ### ~ hint
 
-**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+#### Simulator
+
+This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

diff --git a/docs/reference/pins/spi-pins.md b/docs/reference/pins/spi-pins.md
@@ -10,7 +10,9 @@ To configure the @boardname@ to write to an external device using a SPI connecti
 
 ### ~ hint
 
-**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+#### Simulator
+
+This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

diff --git a/docs/reference/pins/spi-write.md b/docs/reference/pins/spi-write.md
@@ -10,7 +10,9 @@ Data values are written to a SPI slave device connected to the @boardname@ by th
 
 ### ~ hint
 
-**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
+#### Simulator
+
+This function needs real hardware to work with. It's not supported in the simulator.
 
 ### ~
 

diff --git a/libs/core/pins.cpp b/libs/core/pins.cpp
@@ -202,7 +202,7 @@ namespace pins {
      * 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
+     * @param micros period in microseconds. eg:20000
      */
     //% help=pins/analog-set-period weight=23 blockGap=8
     //% blockId=device_set_analog_period block="analog set period|pin %pin|to (µs)%micros"
@@ -318,7 +318,7 @@ namespace pins {
     /**
      * 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
+     * @param micros pulse duration in microseconds, eg:1500
      */
     //% help=pins/servo-set-pulse weight=19
     //% blockId=device_set_servo_pulse block="servo set pulse|pin %value|to (µs) %micros"
@@ -389,9 +389,9 @@ namespace pins {
     }
 
     /**
-     * Emit a plse-width modulation (PWM) signal to the current pitch pin. Use `analog set pitch pin` to define the pitch pin.
+     * Send a pulse-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.
+     * @param ms duration of the pitch in milliseconds.
      */
     //% blockId=device_analog_pitch block="analog pitch %frequency|for (ms) %ms"
     //% help=pins/analog-pitch async advanced=true