fix: replaced the old script that was blocking p5.sound.js multiple files' docs generation

[kunstewi]

fixes #1226 and #72 (p5.sound.js)

@ksen0 @limzykenneth please take a look whenever you are free.

Thanks a lot for your time.

Old Script

      // Fix p5.sound classes
      for (const key in soundData.classes) {
        const newName = `p5.${  soundData.classes[key].name}`;
        const updated = {
          ...soundData.classes[key],
          name: newName,
        };
        soundData.classes[newName] = updated;
        delete soundData.classes[key];
      }
      for (const item of soundData.classitems) {
        item.class = `p5.${  item.class}`;
      }

Problems

1. In the p5.sound.js repository, global library functions like loadSound(), getAudioContext(), and userStartAudio() are documented with the tag @for p5.sound. YUIDoc reads this information and assigns the functions to the p5.sound class. The old script added p5. to everything without thinking, which meant it took those methods and assigned them to a class called p5.p5.sound that does not exist.

2. The old script mistakenly added p5. to the front of every class and item name, regardless of the situation. This works for a class named SoundFile, which becomes p5.SoundFile. However, if a developer specifically wrote @Class p5.SoundFile in the JSDoc comments, the old script would incorrectly change it to p5.p5.SoundFile.

3. The old script used a for...in loop to iterate over the keys inside soundData.classes. In JavaScript, adding and deleting keys in an object while looping through it with a for...in loop is very risky. The JavaScript compiler may become confused. It could end up iterating over the newly added keys in an infinite loop, skipping existing keys, or generating errors.

Updated Script

      // Fix p5.sound classes and map global methods to the 'p5' class
      const classKeys = Object.keys(soundData.classes);
      for (const key of classKeys) {
        let newName = soundData.classes[key].name;
        if (newName === 'p5.sound') {
          newName = 'p5';
        } else if (!newName.startsWith('p5.')) {
          newName = `p5.${newName}`;
        }

        if (newName !== soundData.classes[key].name) {
          const updated = {
            ...soundData.classes[key],
            name: newName,
          };
          soundData.classes[newName] = updated;
          delete soundData.classes[key];
        }
      }
      for (const item of soundData.classitems) {
        if (item.class === 'p5.sound') {
          item.class = 'p5';
        } else if (!item.class.startsWith('p5.')) {
          item.class = `p5.${item.class}`;
        }
      }

this updated script fixes these three critical bugs:

1. Mapping Global Functions to the p5 Sketch Object (The p5.sound to p5 change):

if (item.class === 'p5.sound') {
  item.class = 'p5';
}

The new script specifically hunts for anything assigned to the p5.sound class and explicitly reassigns it to the p5 class. This correctly integrates them as global methods in the documentation (alongside things like createCanvas() and ellipse()) instead of breaking them.

2. Preventing "Double Prefixing" (startsWith('p5.'))

} else if (!item.class.startsWith('p5.')) {
  item.class = `p5.${item.class}`;
}

The new script safely double-checks if the string already starts with "p5.". If it does, it skips it; if it doesn't, it adds it. This prevents double-prefixing.

3. Safe Object Iteration (Object.keys())

const classKeys = Object.keys(soundData.classes);
for (const key of classKeys) {

The new script uses Object.keys() to grab a strict, immutable array of the original class names before the loop starts. It then safely loops over that array, ensuring that any modifications made to soundData.classes down below have no effect on the loop's logic.

Results

Previously no result for userStartAudio or any methods in Utils.js and also no loadSound method from SoundFile

After the change all methods are present in the reference docs

[ksen0]

Thanks for the fix! I checked that it works locally, just minor note on p5.sound string -> const for readability

The old script used a for...in loop to iterate over the keys inside soundData.classes. In JavaScript, adding and deleting keys in an object while looping through it with a for...in loop is very risky. The JavaScript compiler may become confused. It could end up iterating over the newly added keys in an infinite loop, skipping existing keys, or generating errors.

Just to call this out, thanks for both the catch and the fix.

[ksen0]

Is there some way to factor out the hardcoded strings here into a const? Both 'p5.sound' and 'p5' prefixes are repeatedly used and there's some delicate logic in the whole setup (not this PR specifically, but overall)

[kunstewi]

Thanks a lot @ksen0

understood.

done