diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index 3b2b5aab..e11937ea 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -355,6 +355,7 @@ const generic_params = [
    * s("<bd sd>,hh*3").fast(2).crush("<16 8 7 6 5 4 3 2>")
    *
    */
+  ['crush'],
   // TODO: currently duplicated with "native" legato
   // TODO: superdirt legato will do more: https://youtu.be/dQPmE1WaD1k?t=419
   /**
@@ -369,14 +370,16 @@ const generic_params = [
    */
   // ['legato'],
   // ['clhatdecay'],
-  ['crush'],
+
   /**
    * fake-resampling for lowering the sample rate. Caution: This effect seems to only work in chromium based browsers
    *
    * @name coarse
-   * @param {number | Pattern} factor 1 for original 2 for half, 3 for a third and so on.
+   * @param {number | Pattern} factor number between 0 and 1
    * @example
-   * s("bd sd [~ bd] sd,hh*8").coarse("<1 4 8 16 32>")
+   * s("bd sd [~ bd] sd,hh*8").coarse("<0 .1 .2  .8>")
+   * @example
+   * s("bd(5, 8),hh*8").coarse(saw.fast(3)),
    *
    */
   ['coarse'],
@@ -1215,11 +1218,15 @@ const generic_params = [
   // ['scrash'],
   /**
    * Wave shaping distortion. CAUTION: it might get loud
+   * second option in optional array syntax (ex: ".9:.5") applies a postgain to the output
+   * most useful shape values are usually between 0 and 1 (depending on source gain), however there is no limit
    *
    * @name shape
    * @param {number | Pattern} distortion between 0 and 1
    * @example
-   * s("bd sd [~ bd] sd,hh*8").shape("<0 .2 .4 .6 .8>")
+   * s("bd sd [~ bd] sd,hh*8").shape("<0 .1 .5 10:.5>")
+   * @example
+   * note("d1!8").s("sine").penv(36).pdecay(.12).decay(.2).shape("100:.4")
    *
    */
   ['shape'],