--- a/planet.js	Tue Mar 03 10:54:45 2009 -0800
+++ b/planet.js	Tue Mar 03 11:28:40 2009 -0800
@@ -1,6 +1,27 @@
 // = Planet Ubiquity Code =
 //
 // This is the JavaScript source code for the Planet Ubiquity Redesign.
+//
+// == Workflow ==
+//
+// Each column on the Planet represents a feed. Each feed has a
+// "feed processor" associated with it, which is in charge of taking
+// the raw feed information and converting it into HTML content;
+// during this time, it may also mash-up the feed with other
+// information.
+//
+// However, the HTML generated by the feed processor is not its final
+// representation. Once the feed processor is finished, we put each
+// entry created by it into a "bin" depending on the date it was
+// published. This allows us to create vertical rows that represent
+// the region of time a set of entries originate from.
+//
+// Once this process is completed for all feeds, we do some final
+// layout calculations and display the page.
+
+// == Functions ==
+//
+// All functionality is contained in the {{{Planet}}} namespace.
 
 var Planet = {
   // The base URL for where Ubiquity buildbot information is located.
@@ -10,6 +31,13 @@
   HG_BASE: "https://ubiquity.mozilla.com/hg/ubiquity-firefox/"
 };
 
+// === {{{Planet.getBuildInfo()}}} ===
+//
+// This function takes a DOM node or jQuery representing a buildbot
+// Recent Builds HTML page (aka the "one line per build" page),
+// scrapes it, and returns an array of objects containing information
+// about the recent builds.
+
 Planet.getBuildInfo = function getBuildInfo(page) {
   var builds = [];
   $("li", page).each(
@@ -25,6 +53,12 @@
   return builds;
 };
 
+// === {{{Planet.mashupBuildbotWithHgData()}}} ===
+//
+// This function takes a jQuery representing the HG log HTML and
+// mashes it up with the DOM node or jQuery representing a Buildbot
+// Recent Builds HTML page for the repository.
+
 Planet.mashupBuildbotWithHgData = function mashup(hgLog, buildbotPage) {
   var builds = Planet.getBuildInfo(buildbotPage);
   builds.forEach(
@@ -47,6 +81,11 @@
     });
 };
 
+// === {{{Planet.processHgFeed()}}} ===
+//
+// Feed processor to display recent HG commits mashed-up with Buildbot
+// continuous-integration information about each revision.
+
 Planet.processHgFeed = function processHgFeed(feed, content, cb) {
   Planet.processBlogFeed(
     feed,
@@ -65,6 +104,13 @@
     });
 };
 
+// === {{{Planet.processBlogFeed()}}} ===
+//
+// Generic feed processor to display a feed as though it represents a
+// series of blog entries. It also performs some basic author
+// filtering to remove email addresses and only include full names
+// (this is done for the sake of readability, not spam prevention).
+
 Planet.processBlogFeed = function processBlogFeed(feed, content, cb) {
   jQuery.each(
     feed.entries,
@@ -103,31 +149,11 @@
   cb();
 };
 
-Planet.FEEDS = [
-  {name: "Blogs",
-   url: "http://ubiquity.mozilla.com/planet/?feed=rss2",
-   processFeed: Planet.processBlogFeed,
-   entries: 10},
-  {name: "Bugs",
-   url: ("https://ubiquity.mozilla.com/trac/timeline?ticket=on" +
-         "&milestone=on&wiki=on&max=50&daysback=90&format=rss"),
-   processFeed: Planet.processBlogFeed,
-   entries: 10},
-  {name: "Code",
-   url: Planet.HG_BASE + "rss-log",
-   processFeed: Planet.processHgFeed,
-   entries: 15},
-  {name: "Discussions",
-   url: ("http://groups.google.com/group/ubiquity-firefox/feed/" +
-         "rss_v2_0_msgs.xml"),
-   processFeed: Planet.processBlogFeed,
-   entries: 30},
-  {name: "Support",
-   url: ("http://getsatisfaction.com/mozilla/products/mozilla_ubiquity.rss?" +
-         "sort=recently_created"),
-   processFeed: Planet.processBlogFeed,
-   entries: 10}
-];
+// === {{{Planet.doneLoadingFeeds()}}} ===
+//
+// Called when all feeds are done being loaded. At this point, we
+// know exactly what will appear on the page, so we can do some
+// final changes to the layout based on its content.
 
 Planet.doneLoadingFeeds = function doneLoadingFeeds() {
   function fixHeights(timeAgo) {
@@ -149,6 +175,12 @@
   $(document.body).width(columns.outerWidth() * columns.length);
 };
 
+// === {{{Planet.splitByDate()}}} ===
+//
+// Takes the {{{published}}} attribute inserted in each entry by
+// a feed processor and puts each entry into a separate "bin"
+// based on its publish date.
+
 Planet.splitByDate = function splitByDate(rawContent, content) {
   var now = new Date();
   $(".blog-item", rawContent).each(
@@ -166,6 +198,10 @@
     });
 };
 
+// === {{{Planet.showFeed()}}} ===
+//
+// Fetches content for a feed and renders it.
+
 Planet.showFeed = function showFeed(feedInfo, cb) {
   var column = $('<div class="column"></div>');
   var headline = $('<div class="headline"></div>');
@@ -195,6 +231,43 @@
     });
 };
 
+// == The Feed Array ==
+//
+// This is an array of objects containing information about what
+// feeds to display information for. Each object represents a
+// column in the final rendered content.
+
+Planet.FEEDS = [
+  {name: "Blogs",
+   url: "http://ubiquity.mozilla.com/planet/?feed=rss2",
+   processFeed: Planet.processBlogFeed,
+   entries: 10},
+  {name: "Bugs",
+   url: ("https://ubiquity.mozilla.com/trac/timeline?ticket=on" +
+         "&milestone=on&wiki=on&max=50&daysback=90&format=rss"),
+   processFeed: Planet.processBlogFeed,
+   entries: 10},
+  {name: "Code",
+   url: Planet.HG_BASE + "rss-log",
+   processFeed: Planet.processHgFeed,
+   entries: 15},
+  {name: "Discussions",
+   url: ("http://groups.google.com/group/ubiquity-firefox/feed/" +
+         "rss_v2_0_msgs.xml"),
+   processFeed: Planet.processBlogFeed,
+   entries: 30},
+  {name: "Support",
+   url: ("http://getsatisfaction.com/mozilla/products/mozilla_ubiquity.rss?" +
+         "sort=recently_created"),
+   processFeed: Planet.processBlogFeed,
+   entries: 10}
+];
+
+// == Initialization ==
+//
+// Here we load the Google AJAX Feed API and commence the loading
+// of our feeds.
+
 google.load("feeds", "1");
 google.setOnLoadCallback(
   function() {