diff --git a/packages/core/controls.mjs b/packages/core/controls.mjs
index a3ca638aa..6f247180d 100644
--- a/packages/core/controls.mjs
+++ b/packages/core/controls.mjs
@@ -1750,17 +1750,58 @@ export const { semitone } = registerControl('semitone');
 // TODO: synth param
 export const { voice } = registerControl('voice');
 // voicings // https://codeberg.org/uzu/strudel/issues/506
-// chord to voice, like C Eb Fm7 G7. the symbols can be defined via addVoicings
+/**
+ * The chord to voice
+ * @name chord
+ * @param {string | Pattern} symbols chord symbols to voice e.g., C, Eb, Fm7, G7. The symbols can be defined via addVoicings
+ * @example
+ * chord("<Am C D F Am E Am E>").voicing()
+ **/
 export const { chord } = registerControl('chord');
-// which dictionary to use for the voicings
+/**
+ * Which dictionary to use for the voicings. This falls back to the default dictionary if not provided
+ *
+ * @name dictionary
+ * @param {string} dictionaryName which dictionary (having been defined with `addVoicings`) to use
+ * @example
+ * chord("Am C D F Am E Am E").dict('house').voicing
+ **/
 export const { dictionary, dict } = registerControl('dictionary', 'dict');
-// the top note to align the voicing to, defaults to c5
+/** The top note to align the voicing to. Defaults to c5
+ *
+ * @name anchor
+ * @param {string | Pattern} anchorNote the note to align the voicings to
+ * @example
+ * anchor("<c4 g4 c5 g5>").chord("C").voicing()
+ **/
 export const { anchor } = registerControl('anchor');
-// how the voicing is offset from the anchored position
+/**
+ * Sets how the voicing is offset from the anchored position
+ *
+ * @name offset
+ * @param {number | Pattern} shift the amount to shift the voicing up or down
+ * @example
+ * chord("<Am C D F Am E Am E>").offset("<0 1 2 3 4 5>") // alter the voicing each time
+ **/
 export const { offset } = registerControl('offset');
-// how many octaves are voicing steps spread apart, defaults to 1
+/**
+ *  How many octaves are voicing steps spread apart, defaults to 1
+ *
+ *  @name octaves
+ *  @param {number | Pattern} count the number of octaves
+ *  @example
+ *  chord("<Am C D F Am E Am E>").octaves("<2 4>").voicing()
+ **/
 export const { octaves } = registerControl('octaves');
-// below = anchor note will be removed from the voicing, useful for melody harmonization
+/**
+ * Remove anchor note from the voicing. Useful for melody harmonization
+ *
+ * @name mode
+ * @param {string | Pattern} modeName one of {below | above | duck | root}
+ * @example
+ * mode("<below above duck root>").chord("C").voicing()
+ *
+ **/
 export const { mode } = registerControl(['mode', 'anchor']);
 
 /**