diff --git a/src/core/chuck.cpp b/src/core/chuck.cpp
index 9382806ee..bb8fff9a6 100644
--- a/src/core/chuck.cpp
+++ b/src/core/chuck.cpp
@@ -1218,9 +1218,12 @@ t_CKBOOL ChucK::start()
 
 //-----------------------------------------------------------------------------
 // name: run()
-// desc: run engine (call from host callback)
+// desc: run ChucK and synthesize audio for `numFrames`
+//       `input`: the incoming input array of audio samples
+//       `output`: the outgoing output array of audio samples
+//       `numFrames` : the number of audio frames to run
 //-----------------------------------------------------------------------------
-void ChucK::run( SAMPLE * input, SAMPLE * output, t_CKINT numFrames )
+void ChucK::run( const SAMPLE * input, SAMPLE * output, t_CKINT numFrames )
 {
     // make sure we started...
     if( !m_started ) this->start();
@@ -1231,6 +1234,7 @@ void ChucK::run( SAMPLE * input, SAMPLE * output, t_CKINT numFrames )
 
 
 
+
 //-----------------------------------------------------------------------------
 // name: globals()
 // desc: returns VM Globals Manager
diff --git a/src/core/chuck.h b/src/core/chuck.h
index 3187c5cd9..da8a2a2e0 100644
--- a/src/core/chuck.h
+++ b/src/core/chuck.h
@@ -133,8 +133,15 @@ class ChucK
     t_CKBOOL start();
 
 public:
-    // run engine (call from callback)
-    void run( SAMPLE * input, SAMPLE * output, t_CKINT numFrames );
+    // run ChucK and synthesize audio for `numFrames`...
+    //     (NOTE this function is often called from audio callback)
+    // `input`: the incoming input array of audio samples
+    //        input array size expected to == `numFrames` * number-of-input-chanels, as initialized in setParam(CHUCK_PARAM_INPUT_CHANNELS, ...)
+    // `output`: the outgoing output array of audio samples
+    //         output array size expected to == `numFrames` * number-of-output-chanels, as initialized in setParam(CHUCK_PARAM_OUTPUT_CHANNELS, ...)
+    // `numFrames` : the number of audio frames to run
+    //             each audio frame corresponds to one point in time, and contains values for every audio channel
+    void run( const SAMPLE * input, SAMPLE * output, t_CKINT numFrames );
 
 public:
     // is initialized
diff --git a/src/core/chuck_vm.cpp b/src/core/chuck_vm.cpp
index 95a105d93..44646b984 100644
--- a/src/core/chuck_vm.cpp
+++ b/src/core/chuck_vm.cpp
@@ -587,7 +587,10 @@ t_CKBOOL Chuck_VM::compute()
 
 //-----------------------------------------------------------------------------
 // name: run()
-// desc: ...
+// desc: run VM and compute the next N frames of audio
+//       `N` : the number of audio frames to run
+//       `input`: the incoming input array of audio samples
+//       `output`: the outgoing output array of audio samples
 //-----------------------------------------------------------------------------
 t_CKBOOL Chuck_VM::run( t_CKINT N, const SAMPLE * input, SAMPLE * output )
 {