fix(sound): sound module functions have no descriptions in generated docs

[Akshay-2007-1]

Summary

The published sound module docs (source-academy.github.io/modules/documentation/modules/sound.html) show every function with a bare signature and no explanation - reported by Martin Henz.

• Root cause: TypeDoc documents SoundModulePlugin's @moduleMethod-decorated class methods in src/bundles/sound/src/index.ts, since that's the bundle's actual public API surface. None of its 40 methods carried a doc comment, so the generated docs had nothing to render per function.
• The descriptions already existed, just on the wrong layer: functions.ts's pure implementations each have a full doc comment, but functions.ts isn't part of what TypeDoc treats as public. This copies each comment onto its corresponding class method in index.ts (trimming internal migration-only asides like trombone's envelope quirk, and switching @examples from Math.sin/Math.PI to math_sin/math_PI, since Source doesn't expose a global Math object).
• Also fixes an unrelated pre-existing bug found along the way: adsr()'s doc comment in functions.ts was sitting above the private adsrTransformer() helper instead of above adsr() itself.

Test plan

• yarn workspace @sourceacademy/bundle-sound tsc passes
• yarn workspace @sourceacademy/bundle-sound lint - 0 errors (6 pre-existing warnings, unchanged from baseline)
• yarn workspace @sourceacademy/bundle-sound test - 82/82 passing
• Ran the bundle's own docs generation (buildtools build docs .) and inspected the resulting docs.json: all 40 exported functions now carry their description end-to-end (spot-checked sine_sound, adsr, trombone, consecutively, stacking_adsr, record, play_in_tab)

[Akshay-2007-1]

@coderabbitai, do you think so that the changes in this PR when merged will fix the docs issue over at the documentation site generated by TypeDocs?

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '--- Changed files and summary ---'
git diff --stat HEAD^ HEAD
git diff --name-only HEAD^ HEAD

echo '--- Sound module public API outline ---'
ast-grep outline src/bundles/sound/src/index.ts --items all --view expanded 2>/dev/null || true

echo '--- Documentation-related workflows and configuration ---'
fd -HI -t f '.*' .github 2>/dev/null | while IFS= read -r file; do
  if rg -qni 'typedoc|buildtools build docs|github-pages|pages|documentation' "$file"; then
    echo "### $file"
    rg -ni -C 3 'typedoc|buildtools build docs|github-pages|pages|documentation' "$file"
  fi
done

echo '--- Relevant diff excerpts ---'
git diff --unified=3 HEAD^ HEAD -- src/bundles/sound/src/index.ts src/bundles/sound/src/functions.ts

Length of output: 32106

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '--- GitHub Pages deployment workflow ---'
cat -n .github/workflows/pages-deploy.yml

echo '--- Root package documentation and build scripts ---'
if [ -f package.json ]; then
  jq '{scripts: (.scripts // {})}' package.json
fi

echo '--- Documentation build command references outside PR checks ---'
rg -n -C 4 'buildtools build docs|build docs|typedoc|documentation/modules' \
  -g 'package.json' \
  -g '*.yml' \
  -g '*.yaml' \
  -g '*.json' \
  -g '*.ts' \
  . \
  -g '!node_modules/**' -g '!build/**' -g '!dist/**'

echo '--- Sound bundle documentation configuration ---'
fd -HI -t f 'package.json|typedoc.*|tsconfig.*' src/bundles/sound | while IFS= read -r file; do
  echo "### $file"
  if [ "$(basename "$file")" = 'package.json' ]; then
    jq '{name, scripts, typedoc, documentation}' "$file"
  else
    sed -n '1,220p' "$file"
  fi
done

Length of output: 39356

---

@Akshay-2007-1, yes. This PR should fix the missing descriptions on the published sound-module documentation site.

TypeDoc uses src/bundles/sound/src/index.ts as the sound bundle entry point. The PR adds doc comments directly to the public SoundModulePlugin methods that have @moduleMethod decorators. Those are the methods that TypeDoc documents.

After merge to master, the GitHub Pages workflow runs yarn build:docs. That command regenerates docs for all bundles, including sound, and deploys the generated build directory.

The update will appear on the site after the deployment workflow completes successfully.

_{You are interacting with an AI system.}

[RichDom2185]

LGTM with a nit: Should you use JSDoc @returns instead of "Returns"?