--- a/js/ff-herdict-preso.js	Wed Feb 10 18:27:26 2010 +0000
+++ b/js/ff-herdict-preso.js	Wed Feb 10 10:45:38 2010 -0800
@@ -1,8 +1,22 @@
 $(window).ready(
   function() {
+    // Ordered list of slides in the presentation. Each element
+    // is a JS object containing the following keys:
+    //
+    //   timestamp - number of seconds into the presentation
+    //               at which the slide should be shown.
+    //
+    //   element   - the DOM element containing the slide's
+    //               content; has the HTML class 'slide'.
     var slides = [];
+
+    // The main HTML5 audio element that stores our presentation's
+    // soundtrack.
     var audio = $("audio#main").get(0);
 
+    // Build the 'slides' list by analyzing all slides in the DOM
+    // and parsing out their metadata, throwing an exception
+    // if we encounter any errors.
     $("#slides .slide").each(
       function() {
         var rawTimestamp = $(this).attr("data-at");
@@ -12,6 +26,8 @@
         slides.push({timestamp: timestamp, element: this});
       });
 
+    // Return the DOM element that should be displayed as the active
+    // slide the given number of seconds into the movie.
     function findSlideElementForTime(timestamp) {
       var bestElement;
 
@@ -24,6 +40,8 @@
       return bestElement;
     }
 
+    // Potentially change the current slide depending on
+    // how far we are into the movie.
     function maybeChangeSlide() {
       var element = findSlideElementForTime(audio.currentTime);
       if (element && !$(element).hasClass("visible")) {
@@ -32,5 +50,9 @@
       }
     }
 
+    // Whenever the current time in the audio soundtrack
+    // changes, alter the current visual if necessary. This
+    // effectively makes the audio UI work just like a
+    // movie UI.
     audio.addEventListener("timeupdate", maybeChangeSlide, false);
   });