From 5c3501caa4345b4d12eb7686aeb4615d8cb6a7c9 Mon Sep 17 00:00:00 2001
From: Nachito <nachito.dev@proton.me>
Date: Sun, 18 May 2025 16:43:04 -0300
Subject: [PATCH] fix: typo on docs causing problems with autocompletion.
 (#1350)

* fix: scramble and shuffle comments

* fix: comments on themes,docs, tests and more
---
 packages/codemirror/themes/CutiePi.mjs       |  4 +-
 packages/codemirror/themes/androidstudio.mjs |  4 +-
 packages/codemirror/themes/atomone.mjs       |  4 +-
 packages/codemirror/themes/darcula.mjs       |  5 +-
 packages/codemirror/themes/dracula.mjs       |  3 +-
 packages/codemirror/themes/duotoneDark.mjs   |  6 +-
 packages/codemirror/themes/duotoneLight.mjs  |  6 +-
 packages/codemirror/themes/githubDark.mjs    |  3 -
 packages/codemirror/themes/githubLight.mjs   |  3 -
 packages/codemirror/themes/green-text.mjs    |  4 +-
 packages/codemirror/themes/gruvboxDark.mjs   |  7 +-
 packages/codemirror/themes/gruvboxLight.mjs  |  7 +-
 packages/codemirror/themes/red-text.mjs      |  4 +-
 packages/codemirror/themes/sonic-pink.mjs    |  4 +-
 packages/core/controls.mjs                   |  2 +-
 packages/core/pick.mjs                       |  3 +-
 packages/core/signal.mjs                     |  4 +-
 test/__snapshots__/examples.test.mjs.snap    | 75 ++++++++++++++++++--
 18 files changed, 100 insertions(+), 48 deletions(-)

diff --git a/packages/codemirror/themes/CutiePi.mjs b/packages/codemirror/themes/CutiePi.mjs
index f649a117..64b38eaa 100644
--- a/packages/codemirror/themes/CutiePi.mjs
+++ b/packages/codemirror/themes/CutiePi.mjs
@@ -1,5 +1,5 @@
-/**
- * @name Cutie Pi
+/*
+ * Cutie Pi
  * by Switch Angel
  */
 import { tags as t } from '@lezer/highlight';
diff --git a/packages/codemirror/themes/androidstudio.mjs b/packages/codemirror/themes/androidstudio.mjs
index 097f7951..77c16c33 100644
--- a/packages/codemirror/themes/androidstudio.mjs
+++ b/packages/codemirror/themes/androidstudio.mjs
@@ -1,5 +1,5 @@
-/**
- * @name androidstudio
+/*
+ * androidstudio
  */
 import { tags as t } from '@lezer/highlight';
 import { createTheme } from './theme-helper.mjs';
diff --git a/packages/codemirror/themes/atomone.mjs b/packages/codemirror/themes/atomone.mjs
index 4c9fdec6..ab9cd360 100644
--- a/packages/codemirror/themes/atomone.mjs
+++ b/packages/codemirror/themes/atomone.mjs
@@ -1,5 +1,5 @@
-/**
- * @name Atom One
+/*
+ * Atom One
  * Atom One dark syntax theme
  *
  * https://github.com/atom/one-dark-syntax
diff --git a/packages/codemirror/themes/darcula.mjs b/packages/codemirror/themes/darcula.mjs
index 176acbfe..ead66e66 100644
--- a/packages/codemirror/themes/darcula.mjs
+++ b/packages/codemirror/themes/darcula.mjs
@@ -1,6 +1,5 @@
-/**
- * @name darcula
- * @author darcula
+/*
+ * darcula
  * Name: IntelliJ IDEA darcula theme
  * From IntelliJ IDEA by JetBrains
  */
diff --git a/packages/codemirror/themes/dracula.mjs b/packages/codemirror/themes/dracula.mjs
index 10147eda..bdd9617d 100644
--- a/packages/codemirror/themes/dracula.mjs
+++ b/packages/codemirror/themes/dracula.mjs
@@ -1,6 +1,5 @@
-/**
+/*
  * @name dracula
- * @author dracula
  * Michael Kaminsky (http://github.com/mkaminsky11)
  * Original dracula color scheme by Zeno Rocha (https://github.com/zenorocha/dracula-theme)
  */
diff --git a/packages/codemirror/themes/duotoneDark.mjs b/packages/codemirror/themes/duotoneDark.mjs
index 057302cb..f54973e8 100644
--- a/packages/codemirror/themes/duotoneDark.mjs
+++ b/packages/codemirror/themes/duotoneDark.mjs
@@ -1,6 +1,6 @@
-/**
- * @name duotone
- * @author Bram de Haan
+/*
+ * duotone
+ * author Bram de Haan
  * by Bram de Haan, adapted from DuoTone themes by Simurai (http://simurai.com/projects/2016/01/01/duotone-themes)
  */
 import { tags as t } from '@lezer/highlight';
diff --git a/packages/codemirror/themes/duotoneLight.mjs b/packages/codemirror/themes/duotoneLight.mjs
index f7b0214b..81aa3484 100644
--- a/packages/codemirror/themes/duotoneLight.mjs
+++ b/packages/codemirror/themes/duotoneLight.mjs
@@ -1,6 +1,6 @@
-/**
- * @name duotone
- * @author Bram de Haan
+/*
+ * duotone
+ * author Bram de Haan
  * by Bram de Haan, adapted from DuoTone themes by Simurai (http://simurai.com/projects/2016/01/01/duotone-themes)
  */
 import { tags as t } from '@lezer/highlight';
diff --git a/packages/codemirror/themes/githubDark.mjs b/packages/codemirror/themes/githubDark.mjs
index 5187dcc2..477e7d7b 100644
--- a/packages/codemirror/themes/githubDark.mjs
+++ b/packages/codemirror/themes/githubDark.mjs
@@ -1,6 +1,3 @@
-/**
- * @name github
- */
 import { tags as t } from '@lezer/highlight';
 import { createTheme } from './theme-helper.mjs';
 
diff --git a/packages/codemirror/themes/githubLight.mjs b/packages/codemirror/themes/githubLight.mjs
index 382c7ac6..2ccec93b 100644
--- a/packages/codemirror/themes/githubLight.mjs
+++ b/packages/codemirror/themes/githubLight.mjs
@@ -1,6 +1,3 @@
-/**
- * @name github
- */
 import { tags as t } from '@lezer/highlight';
 import { createTheme } from './theme-helper.mjs';
 
diff --git a/packages/codemirror/themes/green-text.mjs b/packages/codemirror/themes/green-text.mjs
index bd21f6d3..08c7a4bb 100644
--- a/packages/codemirror/themes/green-text.mjs
+++ b/packages/codemirror/themes/green-text.mjs
@@ -1,5 +1,5 @@
-/**
- * @name Atom One
+/*
+ * Atom One
  * Atom One dark syntax theme
  *
  * https://github.com/atom/one-dark-syntax
diff --git a/packages/codemirror/themes/gruvboxDark.mjs b/packages/codemirror/themes/gruvboxDark.mjs
index 31d7e42c..67d8bffc 100644
--- a/packages/codemirror/themes/gruvboxDark.mjs
+++ b/packages/codemirror/themes/gruvboxDark.mjs
@@ -1,7 +1,6 @@
-/**
- * @name gruvbox-dark
- * @author morhetz
- * Name: Gruvbox
+/*
+ * gruvbox-dark
+ * author morhetz
  * From github.com/codemirror/codemirror5/blob/master/theme/gruvbox-dark.css
  */
 import { tags as t } from '@lezer/highlight';
diff --git a/packages/codemirror/themes/gruvboxLight.mjs b/packages/codemirror/themes/gruvboxLight.mjs
index ffb4d716..5d4b4ec0 100644
--- a/packages/codemirror/themes/gruvboxLight.mjs
+++ b/packages/codemirror/themes/gruvboxLight.mjs
@@ -1,7 +1,6 @@
-/**
- * @name gruvbox-light
- * @author morhetz
- * Name: Gruvbox
+/*
+ * gruvbox-light
+ * author morhetz
  * From github.com/codemirror/codemirror5/blob/master/theme/gruvbox-light.css
  */
 import { tags as t } from '@lezer/highlight';
diff --git a/packages/codemirror/themes/red-text.mjs b/packages/codemirror/themes/red-text.mjs
index 9fe7f516..44dda5dc 100644
--- a/packages/codemirror/themes/red-text.mjs
+++ b/packages/codemirror/themes/red-text.mjs
@@ -1,5 +1,5 @@
-/**
- * @name Atom One
+/*
+ * Atom One
  * Atom One dark syntax theme
  *
  * https://github.com/atom/one-dark-syntax
diff --git a/packages/codemirror/themes/sonic-pink.mjs b/packages/codemirror/themes/sonic-pink.mjs
index 976597ec..5a19555a 100644
--- a/packages/codemirror/themes/sonic-pink.mjs
+++ b/packages/codemirror/themes/sonic-pink.mjs
@@ -1,5 +1,5 @@
-/**
- * @name Atom One
+/*
+ * Atom One
  * Atom One dark syntax theme
  *
  * https://github.com/atom/one-dark-syntax
diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 0b9821ea..383c2ffa 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -1496,7 +1496,7 @@ export const { vowel } = registerControl('vowel');
  * @name waveloss
  */
 export const { waveloss } = registerControl('waveloss');
-/*
+/**
  * Noise crackle density
  *
  * @name density
diff --git a/packages/core/pick.mjs b/packages/core/pick.mjs
index 334551e1..702201fa 100644
--- a/packages/core/pick.mjs
+++ b/packages/core/pick.mjs
@@ -156,8 +156,7 @@ export const pickmodReset = register('pickmodReset', function (lookup, pat) {
   return _pick(lookup, pat, true).resetJoin();
 });
 
-/**
-  /** * Picks patterns (or plain values) either from a list (by index) or a lookup table (by name).
+/** Picks patterns (or plain values) either from a list (by index) or a lookup table (by name).
    * Similar to `pick`, but cycles are squeezed into the target ('inhabited') pattern.
    * @name inhabit
    * @synonyms pickSqueeze
diff --git a/packages/core/signal.mjs b/packages/core/signal.mjs
index 66ac8a5a..b6ba5d5c 100644
--- a/packages/core/signal.mjs
+++ b/packages/core/signal.mjs
@@ -279,9 +279,9 @@ const _rearrangeWith = (ipat, n, pat) => {
 };
 
 /**
- * @name shuffle
  * Slices a pattern into the given number of parts, then plays those parts in random order.
  * Each part will be played exactly once per cycle.
+ * @name shuffle
  * @example
  * note("c d e f").sound("piano").shuffle(4)
  * @example
@@ -292,9 +292,9 @@ export const shuffle = register('shuffle', (n, pat) => {
 });
 
 /**
- * @name scramble
  * Slices a pattern into the given number of parts, then plays those parts at random. Similar to `shuffle`,
  * but parts might be played more than once, or not at all, per cycle.
+ * @name scramble
  * @example
  * note("c d e f").sound("piano").scramble(4)
  * @example
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index a05d8aa6..e7d6dbb1 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -2403,6 +2403,27 @@ exports[`runs examples > example "delaytime" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "density" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | s:crackle density:0.01 ]",
+  "[ 1/4 → 1/2 | s:crackle density:0.01 ]",
+  "[ 1/2 → 3/4 | s:crackle density:0.01 ]",
+  "[ 3/4 → 1/1 | s:crackle density:0.01 ]",
+  "[ 1/1 → 5/4 | s:crackle density:0.01 ]",
+  "[ 5/4 → 3/2 | s:crackle density:0.01 ]",
+  "[ 3/2 → 7/4 | s:crackle density:0.01 ]",
+  "[ 7/4 → 2/1 | s:crackle density:0.01 ]",
+  "[ 2/1 → 9/4 | s:crackle density:0.01 ]",
+  "[ 9/4 → 5/2 | s:crackle density:0.01 ]",
+  "[ 5/2 → 11/4 | s:crackle density:0.01 ]",
+  "[ 11/4 → 3/1 | s:crackle density:0.01 ]",
+  "[ 3/1 → 13/4 | s:crackle density:0.01 ]",
+  "[ 13/4 → 7/2 | s:crackle density:0.01 ]",
+  "[ 7/2 → 15/4 | s:crackle density:0.01 ]",
+  "[ 15/4 → 4/1 | s:crackle density:0.01 ]",
+]
+`;
+
 exports[`runs examples > example "detune" example index 0 1`] = `
 [
   "[ 0/1 → 1/12 | note:d s:supersaw detune:0.1 ]",
@@ -8051,6 +8072,52 @@ but parts might be played more than once, or not at all, per cycle." example ind
 ]
 `;
 
+exports[`runs examples > example "scramble" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | note:c s:piano ]",
+  "[ 1/4 → 1/2 | note:d s:piano ]",
+  "[ 1/2 → 3/4 | note:d s:piano ]",
+  "[ 3/4 → 1/1 | note:c s:piano ]",
+  "[ 1/1 → 5/4 | note:e s:piano ]",
+  "[ 5/4 → 3/2 | note:e s:piano ]",
+  "[ 3/2 → 7/4 | note:e s:piano ]",
+  "[ 7/4 → 2/1 | note:c s:piano ]",
+  "[ 2/1 → 9/4 | note:f s:piano ]",
+  "[ 9/4 → 5/2 | note:d s:piano ]",
+  "[ 5/2 → 11/4 | note:d s:piano ]",
+  "[ 11/4 → 3/1 | note:e s:piano ]",
+  "[ 3/1 → 13/4 | note:c s:piano ]",
+  "[ 13/4 → 7/2 | note:f s:piano ]",
+  "[ 7/2 → 15/4 | note:d s:piano ]",
+  "[ 15/4 → 4/1 | note:f s:piano ]",
+]
+`;
+
+exports[`runs examples > example "scramble" example index 1 1`] = `
+[
+  "[ 0/1 → 1/8 | note:c s:piano ]",
+  "[ 1/8 → 1/4 | note:d s:piano ]",
+  "[ 1/4 → 3/8 | note:d s:piano ]",
+  "[ 3/8 → 1/2 | note:c s:piano ]",
+  "[ 1/2 → 1/1 | note:g s:piano ]",
+  "[ 1/1 → 9/8 | note:e s:piano ]",
+  "[ 9/8 → 5/4 | note:e s:piano ]",
+  "[ 5/4 → 11/8 | note:e s:piano ]",
+  "[ 11/8 → 3/2 | note:c s:piano ]",
+  "[ 3/2 → 2/1 | note:g s:piano ]",
+  "[ 2/1 → 17/8 | note:f s:piano ]",
+  "[ 17/8 → 9/4 | note:d s:piano ]",
+  "[ 9/4 → 19/8 | note:d s:piano ]",
+  "[ 19/8 → 5/2 | note:e s:piano ]",
+  "[ 5/2 → 3/1 | note:g s:piano ]",
+  "[ 3/1 → 25/8 | note:c s:piano ]",
+  "[ 25/8 → 13/4 | note:f s:piano ]",
+  "[ 13/4 → 27/8 | note:d s:piano ]",
+  "[ 27/8 → 7/2 | note:f s:piano ]",
+  "[ 7/2 → 4/1 | note:g s:piano ]",
+]
+`;
+
 exports[`runs examples > example "scrub" example index 0 1`] = `
 [
   "[ 0/1 → 1/8 | s:swpad n:0 begin:0.1 speed:1 clip:1 ]",
@@ -8481,9 +8548,7 @@ exports[`runs examples > example "shrink" example index 3 1`] = `
 ]
 `;
 
-exports[`runs examples > example "shuffle
-Slices a pattern into the given number of parts, then plays those parts in random order.
-Each part will be played exactly once per cycle." example index 0 1`] = `
+exports[`runs examples > example "shuffle" example index 0 1`] = `
 [
   "[ 0/1 → 1/4 | note:c s:piano ]",
   "[ 1/4 → 1/2 | note:d s:piano ]",
@@ -8504,9 +8569,7 @@ Each part will be played exactly once per cycle." example index 0 1`] = `
 ]
 `;
 
-exports[`runs examples > example "shuffle
-Slices a pattern into the given number of parts, then plays those parts in random order.
-Each part will be played exactly once per cycle." example index 1 1`] = `
+exports[`runs examples > example "shuffle" example index 1 1`] = `
 [
   "[ 0/1 → 1/8 | note:c s:piano ]",
   "[ 1/8 → 1/4 | note:d s:piano ]",