From 0f801980bb1efb6755f305783a4275417dc604ae Mon Sep 17 00:00:00 2001
From: Galen Nickel <gnickel@aquent.com>
Date: Tue, 30 Jul 2024 10:05:15 -0700
Subject: [PATCH] Add audio pin ref page (#5766)

* fix help path for 'resume'

* add ref page for 'set-audio-pin-enabled'
---
 docs/reference/pins/set-audio-pin-enabled.md | 38 ++++++++++++++++++++
 docs/reference/pins/set-audio-pin.md         |  3 +-
 libs/core/game.ts                            |  2 +-
 libs/core/pins.cpp                           |  2 +-
 libs/core/shims.d.ts                         |  2 +-
 5 files changed, 43 insertions(+), 4 deletions(-)
 create mode 100644 docs/reference/pins/set-audio-pin-enabled.md

diff --git a/docs/reference/pins/set-audio-pin-enabled.md b/docs/reference/pins/set-audio-pin-enabled.md
new file mode 100644
index 00000000000..ac04c187d53
--- /dev/null
+++ b/docs/reference/pins/set-audio-pin-enabled.md
@@ -0,0 +1,38 @@
+# set Audio Pin Enabled
+
+Enable a pin on the edge connector to output audio.
+
+```sig
+pins.setAudioPinEnabled(false)
+```
+
+You can enable the @boardname@ to output audio to a pin on the edge connector. 
+
+### ~ hint
+
+#### micro:bit V2 speaker
+
+With the [micro:bit V2](/device/v2) hardware, the built-in speaker will play (mirror) the same tones and music sent to the audio pin.
+
+### ~
+
+## Parameters
+
+* **enabled**: audio is output to a pin is enabled if `true`, disabled if `false`.
+
+## Example
+
+Enable audio output to a pin on the edge connector and play a tone for the "A4" note at pin **P0** for 1 second.
+
+```blocks
+pins.setAudioPinEnabled(false)
+pins.setAudioPin(AnalogPin.P0)
+let frequency = 440
+let duration = 1000
+pins.analogPitch(frequency, duration)
+```
+
+## See also
+
+[@boardname@ pins](/device/pins), [set audio pin](/reference/pins/set-audio-pin),
+[analog set pitch pin](/reference/pins/analog-set-pitch-pin)
diff --git a/docs/reference/pins/set-audio-pin.md b/docs/reference/pins/set-audio-pin.md
index 458f0bac23c..aeab54fe4c6 100644
--- a/docs/reference/pins/set-audio-pin.md
+++ b/docs/reference/pins/set-audio-pin.md
@@ -31,4 +31,5 @@ pins.analogPitch(frequency, duration)
 
 ## See also
 
-[@boardname@ pins](/device/pins), [analog set pitch pin](/reference/pins/analog-set-pitch-pin)
+[@boardname@ pins](/device/pins), [set audio pin enabled](/reference/pins/set-audio-pin-enabled),
+[analog set pitch pin](/reference/pins/analog-set-pitch-pin)
diff --git a/libs/core/game.ts b/libs/core/game.ts
index 103741b4cdf..0c2a454fe45 100644
--- a/libs/core/game.ts
+++ b/libs/core/game.ts
@@ -305,7 +305,7 @@ namespace game {
      * Resumes the game rendering engine
      */
     //% blockId=game_resume block="resume"
-    //% advanced=true blockGap=8 help=game/resumeP
+    //% advanced=true blockGap=8 help=game/resume
     export function resume(): void {
         _paused = false;
         plot();
diff --git a/libs/core/pins.cpp b/libs/core/pins.cpp
index e374b7a5485..4042c65e2d6 100644
--- a/libs/core/pins.cpp
+++ b/libs/core/pins.cpp
@@ -696,7 +696,7 @@ namespace pins {
     */
     //% blockId=pin_set_audio_pin_enabled
     //% block="set audio pin enabled $enabled"
-    //% weight=0
+    //% weight=0 help=pins/set-audio-pin-enabled
     void setAudioPinEnabled(bool enabled) {
         edgeConnectorSoundDisabled = !enabled;
 #if MICROBIT_CODAL
diff --git a/libs/core/shims.d.ts b/libs/core/shims.d.ts
index 6a7e7ec2163..a94f3d6a030 100644
--- a/libs/core/shims.d.ts
+++ b/libs/core/shims.d.ts
@@ -1000,7 +1000,7 @@ declare namespace pins {
      */
     //% blockId=pin_set_audio_pin_enabled
     //% block="set audio pin enabled $enabled"
-    //% weight=0 shim=pins::setAudioPinEnabled
+    //% weight=0 help=pins/set-audio-pin-enabled shim=pins::setAudioPinEnabled
     function setAudioPinEnabled(enabled: boolean): void;
 }