Added some nice comments,

so devs can easily figure out what options to pass
into the objects they want to construct.

IPython/html/static/notebook/js/cell.js

@@ -27,18 +27,17 b' define(['
         };
     // end monkey patching CodeMirror
 
-    /**
-     * The Base `Cell` class from which to inherit
-     * @class Cell
-     **/
-
-    /*
-     * @constructor
-     *
-     * @param {object|undefined} [options]
-     *     @param [options.cm_config] {object} config to pass to CodeMirror, will extend default parameters
-     */
     var Cell = function (options) {
+        // Constructor
+        //
+        // The Base `Cell` class from which to inherit.
+        //
+        // Parameters:
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          events: $(Events) instance 
+        //          config: dictionary
+        //          keyboard_manager: KeyboardManager instance 
         options = options || {};
         this.keyboard_manager = options.keyboard_manager;
         this.events = options.events;

IPython/html/static/notebook/js/codecell.js

@@ -41,21 +41,21 b' define(['
 
     var keycodes = keyboard.keycodes;
 
-    /**
-     * A Cell conceived to write code.
-     *
-     * The kernel doesn't have to be set at creation time, in that case
-     * it will be null and set_kernel has to be called later.
-     * @class CodeCell
-     * @extends Cell
-     *
-     * @constructor
-     * @param {Object|null} kernel
-     * @param {object|undefined} [options]
-     *      @param [options.cm_config] {object} config to pass to CodeMirror
-     */
     var CodeCell = function (kernel, options) {
-        options = options || {};
+        // Constructor
+        //
+        // A Cell conceived to write code.
+        //
+        // Parameters:
+        //  kernel: Kernel instance
+        //      The kernel doesn't have to be set at creation time, in that case
+        //      it will be null and set_kernel has to be called later.
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          events: $(Events) instance 
+        //          config: dictionary
+        //          keyboard_manager: KeyboardManager instance 
+        //          notebook: Notebook instance
         this.kernel = kernel || null;
         this.notebook = options.notebook;
         this.collapsed = false;

IPython/html/static/notebook/js/keyboardmanager.js

@@ -16,6 +16,13 b' define(['
     var keycodes = keyboard.keycodes;
 
     var KeyboardManager = function (options) {
+        // Constructor
+        //
+        // Parameters:
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          events: $(Events) instance
+        //          pager: Pager instance
         this.mode = 'command';
         this.enabled = true;
         this.pager = options.pager;

IPython/html/static/notebook/js/maintoolbar.js

@@ -10,6 +10,14 b' define(['
     "use strict";
 
     var MainToolBar = function (selector, options) {
+        // Constructor
+        //
+        // Parameters:
+        //  selector: string
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          events: $(Events) instance
+        //          notebook: Notebook instance
         toolbar.ToolBar.apply(this, arguments);
         this.events = options.events;
         this.notebook = options.notebook;

IPython/html/static/notebook/js/mathjaxutils.js

@@ -2,10 +2,11 b''
 // Distributed under the terms of the Modified BSD License.
 
 define([
+    'base/js/namespace',
     'jquery',
     'base/js/utils',
     'base/js/dialog',
-], function($, utils, dialog) {
+], function(IPython, $, utils, dialog) {
     "use strict";
 
     var init = function () {
@@ -235,9 +236,13 b' define(['
         return text;
     };
 
-    return {
+    var mathjaxutils = {
         init : init,
         remove_math : remove_math,
         replace_math : replace_math
     };
+
+    IPython.mathjaxutils = mathjaxutils;
+
+    return mathjaxutils;
 });

IPython/html/static/notebook/js/menubar.js

@@ -6,25 +6,26 b' define(['
     'jquery',
     'base/js/utils',
     'notebook/js/tour',
-    'components/bootstrap-tour/build/js/bootstrap-tour.min',
 ], function(IPython, $, utils, tour) {
     "use strict";
     
-    /**
-     * A MenuBar Class to generate the menubar of IPython notebook
-     * @Class MenuBar
-     *
-     * @constructor
-     *
-     *
-     * @param selector {string} selector for the menubar element in DOM
-     * @param {object} [options]
-     *      @param [options.base_url] {String} String to use for the
-     *      base project url. Default is to inspect
-     *      $('body').data('baseUrl');
-     *      does not support change for now is set through this option
-     */
     var MenuBar = function (selector, options) {
+        // Constructor
+        //
+        // A MenuBar Class to generate the menubar of IPython notebook
+        //
+        // Parameters:
+        //  selector: string
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          notebook: Notebook instance
+        //          layout_manager: LayoutManager instance
+        //          events: $(Events) instance
+        //          save_widget: SaveWidget instance
+        //          quick_help: QuickHelp instance
+        //          base_url : string
+        //          notebook_path : string
+        //          notebook_name : string
         options = options || {};
         this.base_url = options.base_url || utils.get_body_data("baseUrl");
         this.selector = selector;

IPython/html/static/notebook/js/notebook.js

@@ -20,7 +20,7 b' define(['
     $, 
     utils, 
     dialog, 
-    cells, 
+    textcell, 
     codecell, 
     session, 
     celltoolbar, 
@@ -29,16 +29,22 b' define(['
     keyboard
     ) {
 
-    /**
-     * A notebook contains and manages cells.
-     * 
-     * @class Notebook
-     * @constructor
-     * @param {String} selector A jQuery selector for the notebook's DOM element
-     * @param {Object} [options] A config object
-     * @param {Object} [events] An events object
-     */
     var Notebook = function (selector, options) {
+        // Constructor
+        //
+        // A notebook contains and manages cells.
+        //
+        // Parameters:
+        //  selector: string
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          events: $(Events) instance
+        //          keyboard_manager: KeyboardManager instance
+        //          save_widget: SaveWidget instance
+        //          config: dictionary
+        //          base_url : string
+        //          notebook_path : string
+        //          notebook_name : string
         this.config = options.config || {};
         this.base_url = options.base_url;
         this.notebook_path = options.notebook_path;
@@ -806,9 +812,6 b' define(['
 
         if (ncells === 0 || this.is_valid_cell_index(index) || index === ncells) {
             var cell_options = {
-                base_url: base_url,
-                notebook_path: notebook_path,
-                notebook_name: notebook_name,
                 events: this.events, 
                 config: this.config, 
                 keyboard_manager: this.keyboard_manager, 
@@ -818,11 +821,11 b' define(['
                 cell = new codecell.CodeCell(this.kernel, cell_options);
                 cell.set_input_prompt();
             } else if (type === 'markdown') {
-                cell = new cells.MarkdownCell(cell_options);
+                cell = new textcell.MarkdownCell(cell_options);
             } else if (type === 'raw') {
-                cell = new cells.RawCell(cell_options);
+                cell = new textcell.RawCell(cell_options);
             } else if (type === 'heading') {
-                cell = new cells.HeadingCell(cell_options);
+                cell = new textcell.HeadingCell(cell_options);
             }
 
             if(this._insert_element_at_index(cell.element,index)) {
@@ -967,7 +970,7 b' define(['
         if (this.is_valid_cell_index(i)) {
             var source_element = this.get_cell_element(i);
             var source_cell = source_element.data("cell");
-            if (!(source_cell instanceof cells.MarkdownCell)) {
+            if (!(source_cell instanceof textcell.MarkdownCell)) {
                 var target_cell = this.insert_cell_below('markdown',i);
                 var text = source_cell.get_text();
                 if (text === source_cell.placeholder) {
@@ -981,7 +984,7 b' define(['
                 target_cell.code_mirror.clearHistory();
                 source_element.remove();
                 this.select(i);
-                if ((source_cell instanceof cells.TextCell) && source_cell.rendered) {
+                if ((source_cell instanceof textcell.TextCell) && source_cell.rendered) {
                     target_cell.render();
                 }
                 var cursor = source_cell.code_mirror.getCursor();
@@ -1003,7 +1006,7 b' define(['
             var source_element = this.get_cell_element(i);
             var source_cell = source_element.data("cell");
             var target_cell = null;
-            if (!(source_cell instanceof cells.RawCell)) {
+            if (!(source_cell instanceof textcell.RawCell)) {
                 target_cell = this.insert_cell_below('raw',i);
                 var text = source_cell.get_text();
                 if (text === source_cell.placeholder) {
@@ -1038,7 +1041,7 b' define(['
             var source_element = this.get_cell_element(i);
             var source_cell = source_element.data("cell");
             var target_cell = null;
-            if (source_cell instanceof cells.HeadingCell) {
+            if (source_cell instanceof textcell.HeadingCell) {
                 source_cell.set_level(level);
             } else {
                 target_cell = this.insert_cell_below('heading',i);
@@ -1057,7 +1060,7 b' define(['
                 this.select(i);
                 var cursor = source_cell.code_mirror.getCursor();
                 target_cell.code_mirror.setCursor(cursor);
-                if ((source_cell instanceof cells.TextCell) && source_cell.rendered) {
+                if ((source_cell instanceof textcell.TextCell) && source_cell.rendered) {
                     target_cell.render();
                 }
             }
@@ -1176,8 +1179,8 b' define(['
      * @method split_cell
      */
     Notebook.prototype.split_cell = function () {
-        var mdc = cells.MarkdownCell;
-        var rc = cells.RawCell;
+        var mdc = textcell.MarkdownCell;
+        var rc = textcell.RawCell;
         var cell = this.get_selected_cell();
         if (cell.is_splittable()) {
             var texta = cell.get_pre_cursor();
@@ -1205,8 +1208,8 b' define(['
      * @method merge_cell_above
      */
     Notebook.prototype.merge_cell_above = function () {
-        var mdc = cells.MarkdownCell;
-        var rc = cells.RawCell;
+        var mdc = textcell.MarkdownCell;
+        var rc = textcell.RawCell;
         var index = this.get_selected_index();
         var cell = this.get_cell(index);
         var render = cell.rendered;
@@ -1242,8 +1245,8 b' define(['
      * @method merge_cell_below
      */
     Notebook.prototype.merge_cell_below = function () {
-        var mdc = cells.MarkdownCell;
-        var rc = cells.RawCell;
+        var mdc = textcell.MarkdownCell;
+        var rc = textcell.RawCell;
         var index = this.get_selected_index();
         var cell = this.get_cell(index);
         var render = cell.rendered;

IPython/html/static/notebook/js/notificationarea.js

@@ -11,6 +11,15 b' define(['
     "use strict";
 
     var NotificationArea = function (selector, options) {
+        // Constructor
+        //
+        // Parameters:
+        //  selector: string
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          notebook: Notebook instance
+        //          events: $(Events) instance
+        //          save_widget: SaveWidget instance
         this.selector = selector;
         this.events = options.events;
         this.save_widget = options.save_widget;

IPython/html/static/notebook/js/pager.js

@@ -9,6 +9,15 b' define(['
     "use strict";
 
     var Pager = function (pager_selector, pager_splitter_selector, options) {
+        // Constructor
+        //
+        // Parameters:
+        //  pager_selector: string
+        //  pager_splitter_selector: string
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          events: $(Events) instance
+        //          layout_manager: LayoutManager instance
         this.events = options.events;
         this.pager_element = $(pager_selector);
         this.pager_button_area = $('#pager_button_area');

IPython/html/static/notebook/js/quickhelp.js

@@ -11,6 +11,13 b' define(['
     var platform = utils.platform;
 
     var QuickHelp = function (options) {
+        // Constructor
+        //
+        // Parameters:
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          events: $(Events) instance
+        //          keyboard_manager: KeyboardManager instance
         this.keyboard_manager = options.keyboard_manager;
         this.keyboard_manager.quick_help = this;
         this.events = options.events;

IPython/html/static/notebook/js/savewidget.js

@@ -12,6 +12,7 b' define(['
     "use strict";
 
     var SaveWidget = function (selector, events) {
+        // TODO: Remove circulat ref.
         this.notebook = undefined;
         this.selector = selector;
         this.events = events;

IPython/html/static/notebook/js/textcell.js

@@ -13,19 +13,21 b' define(['
     "use strict";
     var Cell = cell.Cell;
 
-    /**
-     * Construct a new TextCell, codemirror mode is by default 'htmlmixed', and cell type is 'text'
-     * cell start as not redered.
-     *
-     * @class TextCell
-     * @constructor TextCell
-     * @extend Cell
-     * @param {object|undefined} [options]
-     *      @param [options.cm_config] {object} config to pass to CodeMirror, will extend/overwrite default config
-     *      @param [options.placeholder] {string} default string to use when souce in empty for rendering (only use in some TextCell subclass)
-     */
     var TextCell = function (options) {
+        // Constructor
+        //
+        // Construct a new TextCell, codemirror mode is by default 'htmlmixed', 
+        // and cell type is 'text' cell start as not redered.
+        //
+        // Parameters:
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          events: $(Events) instance 
+        //          config: dictionary
+        //          keyboard_manager: KeyboardManager instance 
+        //          notebook: Notebook instance
         options = options || {};
+
         // in all TextCell/Cell subclasses
         // do not assign most of members here, just pass it down
         // in the options dict potentially overwriting what you wish.
@@ -214,12 +216,16 b' define(['
     };
 
 
-    /**
-     * @class MarkdownCell
-     * @constructor MarkdownCell
-     * @extends IPython.HTMLCell
-     */
     var MarkdownCell = function (options) {
+        // Constructor
+        //
+        // Parameters:
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          events: $(Events) instance 
+        //          config: dictionary
+        //          keyboard_manager: KeyboardManager instance 
+        //          notebook: Notebook instance
         options = options || {};
         var config = this.mergeopt(MarkdownCell, options.config);
         TextCell.apply(this, [$.extend({}, options, {config: config})]);
@@ -263,14 +269,16 b' define(['
     };
 
 
-    // RawCell
-
-    /**
-     * @class RawCell
-     * @constructor RawCell
-     * @extends TextCell
-     */
     var RawCell = function (options) {
+        // Constructor
+        //
+        // Parameters:
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          events: $(Events) instance 
+        //          config: dictionary
+        //          keyboard_manager: KeyboardManager instance 
+        //          notebook: Notebook instance
         options = options || {};
         var config = this.mergeopt(RawCell, options.config);
         TextCell.apply(this, [$.extend({}, options, {config: config})]);
@@ -321,16 +329,16 b' define(['
     };
 
 
-    /**
-     * @class HeadingCell
-     * @extends TextCell
-     */
-
-    /**
-     * @constructor HeadingCell
-     * @extends TextCell
-     */
     var HeadingCell = function (options) {
+        // Constructor
+        //
+        // Parameters:
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          events: $(Events) instance 
+        //          config: dictionary
+        //          keyboard_manager: KeyboardManager instance 
+        //          notebook: Notebook instance
         options = options || {};
         var config = this.mergeopt(HeadingCell, options.config);
         TextCell.apply(this, [$.extend({}, options, {config: config})]);

IPython/html/static/notebook/js/tour.js

@@ -4,7 +4,8 b''
 define([
     'base/js/namespace',
     'jquery',
-], function(IPython, $) {
+    'components/bootstrap-tour/build/js/bootstrap-tour.min',
+], function(IPython, $, Tour) {
     "use strict";
 
     var tour_style = "<div class='popover tour'>\n" +

IPython/html/static/tree/js/kernellist.js

@@ -9,6 +9,15 b' define(['
     "use strict";
 
     var KernelList = function (selector, options) {
+        // Constructor
+        //
+        // Parameters:
+        //  selector: string
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          session_list: SessionList instance
+        //          base_url: string
+        //          notebook_path: string
         notebooklist.NotebookList.call(this, selector, $.extend({
             element_name: 'running'}, 
             options));

IPython/html/static/tree/js/notebooklist.js

@@ -10,6 +10,16 b' define(['
     "use strict";
     
     var NotebookList = function (selector, options) {
+        // Constructor
+        //
+        // Parameters:
+        //  selector: string
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          session_list: SessionList instance
+        //          element_name: string
+        //          base_url: string
+        //          notebook_path: string
         var that = this;
         this.session_list = options.session_list;
         // allow code re-use by just changing element_name in kernellist.js

IPython/html/static/tree/js/sessionlist.js

@@ -8,7 +8,14 b' define(['
 ], function(IPython, $, utils) {
     "use strict";
 
-    var SesssionList = function (options, events) {
+    var SesssionList = function (options) {
+        // Constructor
+        //
+        // Parameters:
+        //  options: dictionary
+        //      Dictionary of keyword arguments.
+        //          events: $(Events) instance
+        //          base_url : string
         this.events = options.events;
         this.sessions = {};
         this.base_url = options.base_url || utils.get_body_data("baseUrl");