Merge pull request #7096 from jdfreder/jsdoc

JSDoc comments

IPython/html/static/base/js/dialog.js

@@ -92,8 +92,10 b' define(['
     };
 
     var kernel_modal = function (options) {
-        // only one kernel dialog should be open at a time -- but
-        // other modal dialogs can still be open
+        /**
+         * only one kernel dialog should be open at a time -- but
+         * other modal dialogs can still be open
+         */
         $('.kernel-modal').modal('hide');
         var dialog = modal(options);
         dialog.addClass('kernel-modal');
@@ -140,7 +142,9 b' define(['
             buttons: {
                 OK: { class : "btn-primary",
                     click: function() {
-                        // validate json and set it
+                        /**
+                         * validate json and set it
+                         */
                         var new_md;
                         try {
                             new_md = JSON.parse(editor.getValue());

IPython/html/static/base/js/page.js

@@ -15,23 +15,29 b' define(['
     };
 
     Page.prototype.show = function () {
-        // The header and site divs start out hidden to prevent FLOUC.
-        // Main scripts should call this method after styling everything.
+        /**
+         * The header and site divs start out hidden to prevent FLOUC.
+         * Main scripts should call this method after styling everything.
+         */
         this.show_header();
         this.show_site();
     };
 
     Page.prototype.show_header = function () {
-        // The header and site divs start out hidden to prevent FLOUC.
-        // Main scripts should call this method after styling everything.
-        // TODO: selector are hardcoded, pass as constructor argument
+        /**
+         * The header and site divs start out hidden to prevent FLOUC.
+         * Main scripts should call this method after styling everything.
+         * TODO: selector are hardcoded, pass as constructor argument
+         */
         $('div#header').css('display','block');
     };
 
     Page.prototype.show_site = function () {
-        // The header and site divs start out hidden to prevent FLOUC.
-        // Main scripts should call this method after styling everything.
-        // TODO: selector are hardcoded, pass as constructor argument
+        /**
+         * The header and site divs start out hidden to prevent FLOUC.
+         * Main scripts should call this method after styling everything.
+         * TODO: selector are hardcoded, pass as constructor argument
+         */
         $('div#site').css('display','block');
     };
 

IPython/html/static/base/js/security.js

@@ -18,8 +18,10 b' define(['
     }
     
     var sanitizeAttribs = function (tagName, attribs, opt_naiveUriRewriter, opt_nmTokenPolicy, opt_logger) {
-        // add trusting data-attributes to the default sanitizeAttribs from caja
-        // this function is mostly copied from the caja source
+        /**
+         * add trusting data-attributes to the default sanitizeAttribs from caja
+         * this function is mostly copied from the caja source
+         */
         var ATTRIBS = caja.html4.ATTRIBS;
         for (var i = 0; i < attribs.length; i += 2) {
             var attribName = attribs[i];
@@ -34,9 +36,11 b' define(['
     };
     
     var sanitize_css = function (css, tagPolicy) {
-        // sanitize CSS
-        // like sanitize_html, but for CSS
-        // called by sanitize_stylesheets
+        /**
+         * sanitize CSS
+         * like sanitize_html, but for CSS
+         * called by sanitize_stylesheets
+         */
         return caja.sanitizeStylesheet(
             window.location.pathname,
             css,
@@ -51,8 +55,10 b' define(['
     };
     
     var sanitize_stylesheets = function (html, tagPolicy) {
-        // sanitize just the css in style tags in a block of html
-        // called by sanitize_html, if allow_css is true
+        /**
+         * sanitize just the css in style tags in a block of html
+         * called by sanitize_html, if allow_css is true
+         */
         var h = $("<div/>").append(html);
         var style_tags = h.find("style");
         if (!style_tags.length) {
@@ -66,9 +72,11 b' define(['
     };
     
     var sanitize_html = function (html, allow_css) {
-        // sanitize HTML
-        // if allow_css is true (default: false), CSS is sanitized as well.
-        // otherwise, CSS elements and attributes are simply removed.
+        /**
+         * sanitize HTML
+         * if allow_css is true (default: false), CSS is sanitized as well.
+         * otherwise, CSS elements and attributes are simply removed.
+         */
         var html4 = caja.html4;
 
         if (allow_css) {

IPython/html/static/base/js/utils.js

@@ -154,7 +154,9 b' define(['
 
 
     var uuid = function () {
-        // http://www.ietf.org/rfc/rfc4122.txt
+        /**
+         * http://www.ietf.org/rfc/rfc4122.txt
+         */
         var s = [];
         var hexDigits = "0123456789ABCDEF";
         for (var i = 0; i < 32; i++) {
@@ -355,7 +357,9 b' define(['
     }
 
     var points_to_pixels = function (points) {
-        // A reasonably good way of converting between points and pixels.
+        /**
+         * A reasonably good way of converting between points and pixels.
+         */
         var test = $('<div style="display: none; width: 10000pt; padding:0; border:0;"></div>');
         $(body).append(test);
         var pixel_per_point = test.width()/10000;
@@ -364,10 +368,12 b' define(['
     };
     
     var always_new = function (constructor) {
-        // wrapper around contructor to avoid requiring `var a = new constructor()`
-        // useful for passing constructors as callbacks,
-        // not for programmer laziness.
-        // from http://programmers.stackexchange.com/questions/118798
+        /**
+         * wrapper around contructor to avoid requiring `var a = new constructor()`
+         * useful for passing constructors as callbacks,
+         * not for programmer laziness.
+         * from http://programmers.stackexchange.com/questions/118798
+         */
         return function () {
             var obj = Object.create(constructor.prototype);
             constructor.apply(obj, arguments);
@@ -376,7 +382,9 b' define(['
     };
 
     var url_path_join = function () {
-        // join a sequence of url components with '/'
+        /**
+         * join a sequence of url components with '/'
+         */
         var url = '';
         for (var i = 0; i < arguments.length; i++) {
             if (arguments[i] === '') {
@@ -393,8 +401,10 b' define(['
     };
     
     var url_path_split = function (path) {
-        // Like os.path.split for URLs.
-        // Always returns two strings, the directory path and the base filename
+        /**
+         * Like os.path.split for URLs.
+         * Always returns two strings, the directory path and the base filename
+         */
         
         var idx = path.lastIndexOf('/');
         if (idx === -1) {
@@ -405,35 +415,43 b' define(['
     };
     
     var parse_url = function (url) {
-        // an `a` element with an href allows attr-access to the parsed segments of a URL
-        // a = parse_url("http://localhost:8888/path/name#hash")
-        // a.protocol = "http:"
-        // a.host     = "localhost:8888"
-        // a.hostname = "localhost"
-        // a.port     = 8888
-        // a.pathname = "/path/name"
-        // a.hash     = "#hash"
+        /**
+         * an `a` element with an href allows attr-access to the parsed segments of a URL
+         * a = parse_url("http://localhost:8888/path/name#hash")
+         * a.protocol = "http:"
+         * a.host     = "localhost:8888"
+         * a.hostname = "localhost"
+         * a.port     = 8888
+         * a.pathname = "/path/name"
+         * a.hash     = "#hash"
+         */
         var a = document.createElement("a");
         a.href = url;
         return a;
     };
     
     var encode_uri_components = function (uri) {
-        // encode just the components of a multi-segment uri,
-        // leaving '/' separators
+        /**
+         * encode just the components of a multi-segment uri,
+         * leaving '/' separators
+         */
         return uri.split('/').map(encodeURIComponent).join('/');
     };
     
     var url_join_encode = function () {
-        // join a sequence of url components with '/',
-        // encoding each component with encodeURIComponent
+        /**
+         * join a sequence of url components with '/',
+         * encoding each component with encodeURIComponent
+         */
         return encode_uri_components(url_path_join.apply(null, arguments));
     };
 
 
     var splitext = function (filename) {
-        // mimic Python os.path.splitext
-        // Returns ['base', '.ext']
+        /**
+         * mimic Python os.path.splitext
+         * Returns ['base', '.ext']
+         */
         var idx = filename.lastIndexOf('.');
         if (idx > 0) {
             return [filename.slice(0, idx), filename.slice(idx)];
@@ -444,20 +462,26 b' define(['
 
 
     var escape_html = function (text) {
-        // escape text to HTML
+        /**
+         * escape text to HTML
+         */
         return $("<div/>").text(text).html();
     };
 
 
     var get_body_data = function(key) {
-        // get a url-encoded item from body.data and decode it
-        // we should never have any encoded URLs anywhere else in code
-        // until we are building an actual request
+        /**
+         * get a url-encoded item from body.data and decode it
+         * we should never have any encoded URLs anywhere else in code
+         * until we are building an actual request
+         */
         return decodeURIComponent($('body').data(key));
     };
     
     var to_absolute_cursor_pos = function (cm, cursor) {
-        // get the absolute cursor position from CodeMirror's col, ch
+        /**
+         * get the absolute cursor position from CodeMirror's col, ch
+         */
         if (!cursor) {
             cursor = cm.getCursor();
         }
@@ -469,7 +493,9 b' define(['
     };
     
     var from_absolute_cursor_pos = function (cm, cursor_pos) {
-        // turn absolute cursor postion into CodeMirror col, ch cursor
+        /**
+         * turn absolute cursor postion into CodeMirror col, ch cursor
+         */
         var i, line;
         var offset = 0;
         for (i = 0, line=cm.getLine(i); line !== undefined; i++, line=cm.getLine(i)) {
@@ -517,12 +543,16 b' define(['
     })();
 
     var is_or_has = function (a, b) {
-        // Is b a child of a or a itself?
+        /**
+         * Is b a child of a or a itself?
+         */
         return a.has(b).length !==0 || a.is(b);
     };
 
     var is_focused = function (e) {
-        // Is element e, or one of its children focused?
+        /**
+         * Is element e, or one of its children focused?
+         */
         e = $(e);
         var target = $(document.activeElement);
         if (target.length > 0) {
@@ -543,8 +573,10 b' define(['
     };
     
     var ajax_error_msg = function (jqXHR) {
-        // Return a JSON error message if there is one,
-        // otherwise the basic HTTP status text.
+        /**
+         * Return a JSON error message if there is one,
+         * otherwise the basic HTTP status text.
+         */
         if (jqXHR.responseJSON && jqXHR.responseJSON.traceback) {
             return jqXHR.responseJSON.traceback;
         } else if (jqXHR.responseJSON && jqXHR.responseJSON.message) {
@@ -554,7 +586,9 b' define(['
         }
     };
     var log_ajax_error = function (jqXHR, status, error) {
-        // log ajax failures with informative messages
+        /**
+         * log ajax failures with informative messages
+         */
         var msg = "API request failed (" + jqXHR.status + "): ";
         console.log(jqXHR);
         msg += ajax_error_msg(jqXHR);
@@ -562,7 +596,9 b' define(['
     };
     
     var requireCodeMirrorMode = function (mode, callback, errback) {
-        // load a mode with requirejs
+        /**
+         * load a mode with requirejs
+         */
         if (typeof mode != "string") mode = mode.name;
         if (CodeMirror.modes.hasOwnProperty(mode)) {
             callback(CodeMirror.modes.mode);
@@ -592,8 +628,10 b' define(['
     };
     
     var promising_ajax = function(url, settings) {
-        // Like $.ajax, but returning an ES6 promise. success and error settings
-        // will be ignored.
+        /**
+         * Like $.ajax, but returning an ES6 promise. success and error settings
+         * will be ignored.
+         */
         return new Promise(function(resolve, reject) {
             settings.success = function(data, status, jqXHR) {
                 resolve(data);
@@ -607,11 +645,13 b' define(['
     };
 
     var WrappedError = function(message, error){
-        // Wrappable Error class
-
-        // The Error class doesn't actually act on `this`.  Instead it always
-        // returns a new instance of Error.  Here we capture that instance so we
-        // can apply it's properties to `this`.
+        /**
+         * Wrappable Error class
+         *
+         * The Error class doesn't actually act on `this`.  Instead it always
+         * returns a new instance of Error.  Here we capture that instance so we
+         * can apply it's properties to `this`.
+         */
         var tmp = Error.apply(this, [message]);
 
         // Copy the properties of the error over to this.
@@ -635,11 +675,13 b' define(['
 
 
     var load_class = function(class_name, module_name, registry) {
-        // Tries to load a class
-        //
-        // Tries to load a class from a module using require.js, if a module 
-        // is specified, otherwise tries to load a class from the global 
-        // registry, if the global registry is provided.
+        /**
+         * Tries to load a class
+         *
+         * Tries to load a class from a module using require.js, if a module 
+         * is specified, otherwise tries to load a class from the global 
+         * registry, if the global registry is provided.
+         */
         return new Promise(function(resolve, reject) {
 
             // Try loading the view module using require.js
@@ -662,8 +704,10 b' define(['
     };
 
     var resolve_promises_dict = function(d) {
-        // Resolve a promiseful dictionary.
-        // Returns a single Promise.
+        /**
+         * Resolve a promiseful dictionary.
+         * Returns a single Promise.
+         */
         var keys = Object.keys(d);
         var values = [];
         keys.forEach(function(key) {
@@ -679,11 +723,13 b' define(['
     };
 
     var WrappedError = function(message, error){
-        // Wrappable Error class
-
-        // The Error class doesn't actually act on `this`.  Instead it always
-        // returns a new instance of Error.  Here we capture that instance so we
-        // can apply it's properties to `this`.
+        /**
+         * Wrappable Error class
+         *
+         * The Error class doesn't actually act on `this`.  Instead it always
+         * returns a new instance of Error.  Here we capture that instance so we
+         * can apply it's properties to `this`.
+         */
         var tmp = Error.apply(this, [message]);
 
         // Copy the properties of the error over to this.
@@ -706,11 +752,13 b' define(['
     WrappedError.prototype = Object.create(Error.prototype, {});
 
     var reject = function(message, log) {
-        // Creates a wrappable Promise rejection function.
-        // 
-        // Creates a function that returns a Promise.reject with a new WrappedError
-        // that has the provided message and wraps the original error that 
-        // caused the promise to reject.
+        /**
+         * Creates a wrappable Promise rejection function.
+         * 
+         * Creates a function that returns a Promise.reject with a new WrappedError
+         * that has the provided message and wraps the original error that 
+         * caused the promise to reject.
+         */
         return function(error) { 
             var wrapped_error = new WrappedError(message, error);
             if (log) console.error(wrapped_error); 

IPython/html/static/edit/js/menubar.js

@@ -10,19 +10,21 b' define(['
     "use strict";
     
     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.
-        //          codemirror: CodeMirror instance
-        //          contents: ContentManager instance
-        //          events: $(Events) instance
-        //          base_url : string
-        //          file_path : string
+        /**
+         * Constructor
+         *
+         * A MenuBar Class to generate the menubar of IPython notebook
+         *
+         * Parameters:
+         *  selector: string
+         *  options: dictionary
+         *      Dictionary of keyword arguments.
+         *          codemirror: CodeMirror instance
+         *          contents: ContentManager instance
+         *          events: $(Events) instance
+         *          base_url : string
+         *          file_path : string
+         */
         options = options || {};
         this.base_url = options.base_url || utils.get_body_data("baseUrl");
         this.selector = selector;
@@ -35,7 +37,9 b' define(['
     };
 
     MenuBar.prototype.bind_events = function () {
-        //  File
+        /**
+         *  File
+         */
         var that = this;
         this.element.find('#save_file').click(function () {
             that.editor.save();

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

@@ -112,8 +112,10 b' define(['
     };
 
     Cell.prototype.init_classes = function () {
-        // Call after this.element exists to initialize the css classes
-        // related to selected, rendered and mode.
+        /**
+         * Call after this.element exists to initialize the css classes
+         * related to selected, rendered and mode.
+         */
         if (this.selected) {
             this.element.addClass('selected');
         } else {
@@ -534,7 +536,9 b' define(['
      * @param {String|object|undefined} - CodeMirror mode | 'auto'
      **/
     Cell.prototype._auto_highlight = function (modes) {
-        //Here we handle manually selected modes
+        /**
+         *Here we handle manually selected modes
+         */
         var that = this;
         var mode;
         if( this.user_highlight !== undefined &&  this.user_highlight != 'auto' )
@@ -625,7 +629,9 b' define(['
     };
     
     UnrecognizedCell.prototype.toJSON = function () {
-        // deepcopy the metadata so copied cells don't share the same object
+        /**
+         * deepcopy the metadata so copied cells don't share the same object
+         */
         return JSON.parse(JSON.stringify(this.data));
     };
 

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

@@ -9,17 +9,19 b' define(['
     "use strict";
 
     var CellToolbar = function (options) {
-        // Constructor
-        //
-        // Parameters:
-        //  options: dictionary
-        //      Dictionary of keyword arguments.
-        //          events: $(Events) instance 
-        //          cell: Cell instance
-        //          notebook: Notebook instance 
-        //
-        //  TODO: This leaks, when cell are deleted
-        //  There is still a reference to each celltoolbars. 
+        /**
+         * Constructor
+         *
+         * Parameters:
+         *  options: dictionary
+         *      Dictionary of keyword arguments.
+         *          events: $(Events) instance 
+         *          cell: Cell instance
+         *          notebook: Notebook instance 
+         *
+         *  TODO: This leaks, when cell are deleted
+         *  There is still a reference to each celltoolbars.
+         */
         CellToolbar._instances.push(this);
         this.notebook = options.notebook;
         this.cell = options.cell;
@@ -248,9 +250,11 b' define(['
      * @method rebuild
      */
     CellToolbar.prototype.rebuild = function(){
-        // strip evrything from the div
-        // which is probably inner_element
-        // or this.element.
+        /**
+         * strip evrything from the div
+         * which is probably inner_element
+         * or this.element.
+         */
         this.inner_element.empty();
         this.ui_controls_list = [];
 

IPython/html/static/notebook/js/celltoolbarpresets/example.js

@@ -119,7 +119,9 b' define(['
                 width: 650,
                 modal: true,
                 close: function() {
-                    //cleanup on close
+                    /**
+                     *cleanup on close
+                     */
                     $(this).remove();
                 }
         });

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

@@ -53,21 +53,23 b' define(['
     var keycodes = keyboard.keycodes;
 
     var CodeCell = function (kernel, 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
-        //          tooltip: Tooltip instance
+        /**
+         * 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
+         *          tooltip: Tooltip instance
+         */
         this.kernel = kernel || null;
         this.notebook = options.notebook;
         this.collapsed = false;

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

@@ -92,8 +92,10 b' define(['
     };
 
     Completer.prototype.startCompletion = function () {
-        // call for a 'first' completion, that will set the editor and do some
-        // special behavior like autopicking if only one completion available.
+        /**
+         * call for a 'first' completion, that will set the editor and do some
+         * special behavior like autopicking if only one completion available.
+         */
         if (this.editor.somethingSelected()|| this.editor.getSelections().length > 1) return;
         this.done = false;
         // use to get focus back on opera
@@ -119,9 +121,11 b' define(['
      * shared start
      **/
     Completer.prototype.carry_on_completion = function (first_invocation) {
-        // Pass true as parameter if you want the completer to autopick when
-        // only one completion. This function is automatically reinvoked at
-        // each keystroke with first_invocation = false
+        /**
+         * Pass true as parameter if you want the completer to autopick when
+         * only one completion. This function is automatically reinvoked at
+         * each keystroke with first_invocation = false
+         */
         var cur = this.editor.getCursor();
         var line = this.editor.getLine(cur.line);
         var pre_cursor = this.editor.getRange({
@@ -164,8 +168,10 b' define(['
     };
 
     Completer.prototype.finish_completing = function (msg) {
-        // let's build a function that wrap all that stuff into what is needed
-        // for the new completer:
+        /**
+         * let's build a function that wrap all that stuff into what is needed
+         * for the new completer:
+         */
         var content = msg.content;
         var start = content.cursor_start;
         var end = content.cursor_end;
@@ -376,11 +382,13 b' define(['
     };
 
     Completer.prototype.keypress = function (event) {
-        // FIXME: This is a band-aid.
-        // on keypress, trigger insertion of a single character.
-        // This simulates the old behavior of completion as you type,
-        // before events were disconnected and CodeMirror stopped
-        // receiving events while the completer is focused.
+        /**
+         * FIXME: This is a band-aid.
+         * on keypress, trigger insertion of a single character.
+         * This simulates the old behavior of completion as you type,
+         * before events were disconnected and CodeMirror stopped
+         * receiving events while the completer is focused.
+         */
         
         var that = this;
         var code = event.keyCode;

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

@@ -10,14 +10,16 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
+        /**
+         * 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;
@@ -108,7 +110,9 b' define(['
                     label : 'Run Cell',
                     icon : 'fa-play',
                     callback : function () {
-                        // emulate default shift-enter behavior
+                        /**
+                         * emulate default shift-enter behavior
+                         */
                         that.notebook.execute_cell_and_select_below();
                     }
                 },

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

@@ -13,23 +13,25 b' define(['
     "use strict";
     
     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
-        //          contents: ContentManager 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
+        /**
+         * Constructor
+         *
+         * A MenuBar Class to generate the menubar of IPython notebook
+         *
+         * Parameters:
+         *  selector: string
+         *  options: dictionary
+         *      Dictionary of keyword arguments.
+         *          notebook: Notebook instance
+         *          contents: ContentManager 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;
@@ -87,7 +89,9 b' define(['
     };
 
     MenuBar.prototype.bind_events = function () {
-        //  File
+        /**
+         *  File
+         */
         var that = this;
         this.element.find('#new_notebook').click(function () {
             var w = window.open();
@@ -169,7 +173,9 b' define(['
         });
         this.element.find('#kill_and_exit').click(function () {
             var close_window = function () {
-                // allow closing of new tabs in Chromium, impossible in FF
+                /**
+                 * allow closing of new tabs in Chromium, impossible in FF
+                 */
                 window.open('', '_self', '');
                 window.close();
             };
@@ -352,7 +358,9 b' define(['
     };
     
     MenuBar.prototype.update_nbconvert_script = function(langinfo) {
-        // Set the 'Download as foo' menu option for the relevant language.
+        /**
+         * Set the 'Download as foo' menu option for the relevant language.
+         */
         var el = this.element.find('#download_script');
         var that = this;
         

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

@@ -45,22 +45,24 b' define(['
     "use strict";
 
     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
-        //          contents: Contents instance
-        //          save_widget: SaveWidget instance
-        //          config: dictionary
-        //          base_url : string
-        //          notebook_path : string
-        //          notebook_name : string
+        /**
+         * Constructor
+         *
+         * A notebook contains and manages cells.
+         *
+         * Parameters:
+         *  selector: string
+         *  options: dictionary
+         *      Dictionary of keyword arguments.
+         *          events: $(Events) instance
+         *          keyboard_manager: KeyboardManager instance
+         *          contents: Contents instance
+         *          save_widget: SaveWidget instance
+         *          config: dictionary
+         *          base_url : string
+         *          notebook_path : string
+         *          notebook_name : string
+         */
         this.config = utils.mergeopt(Notebook, options.config);
         this.base_url = options.base_url;
         this.notebook_path = options.notebook_path;
@@ -314,7 +316,9 b' define(['
     };
     
     Notebook.prototype.warn_nbformat_minor = function (event) {
-        // trigger a warning dialog about missing functionality from newer minor versions
+        /**
+         * trigger a warning dialog about missing functionality from newer minor versions
+         */
         var v = 'v' + this.nbformat + '.';
         var orig_vs = v + this.nbformat_minor;
         var this_vs = v + this.current_nbformat_minor;
@@ -1141,7 +1145,9 b' define(['
     };
     
     Notebook.prototype._warn_heading = function () {
-        // warn about heading cells being removed
+        /**
+         * warn about heading cells being removed
+         */
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
@@ -1677,7 +1683,9 b' define(['
      * @method execute_cell
      */
     Notebook.prototype.execute_cell = function () {
-        // mode = shift, ctrl, alt
+        /**
+         * mode = shift, ctrl, alt
+         */
         var cell = this.get_selected_cell();
         
         cell.execute();
@@ -1888,7 +1896,9 b' define(['
      * @return {Object} A JSON-friendly representation of this notebook.
      */
     Notebook.prototype.toJSON = function () {
-        // remove the conversion indicator, which only belongs in-memory
+        /**
+         * remove the conversion indicator, which only belongs in-memory
+         */
         delete this.metadata.orig_nbformat;
         delete this.metadata.orig_nbformat_minor;
 

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

@@ -246,7 +246,9 b' define(['
     ];
 
     OutputArea.prototype.validate_mimebundle = function (json) {
-        // scrub invalid outputs
+        /**
+         * scrub invalid outputs
+         */
         var data = json.data;
         $.map(OutputArea.output_types, function(key){
             if (key !== 'application/json' &&
@@ -297,8 +299,10 b' define(['
         // available.
         var that = this;
         var handle_appended = function ($el) {
-            // Only reset the height to automatic if the height is currently
-            // fixed (done by wait=True flag on clear_output).
+            /**
+             * Only reset the height to automatic if the height is currently
+             * fixed (done by wait=True flag on clear_output).
+             */
             if (needs_height_reset) {
                 that.element.height('');
             }
@@ -380,7 +384,9 b' define(['
 
 
     OutputArea.prototype._append_javascript_error = function (err, element) {
-        // display a message when a javascript error occurs in display output
+        /**
+         * display a message when a javascript error occurs in display output
+         */
         var msg = "Javascript error adding output!";
         if ( element === undefined ) return;
         element
@@ -390,10 +396,12 b' define(['
     };
     
     OutputArea.prototype._safe_append = function (toinsert) {
-        // safely append an item to the document
-        // this is an object created by user code,
-        // and may have errors, which should not be raised
-        // under any circumstances.
+        /**
+         * safely append an item to the document
+         * this is an object created by user code,
+         * and may have errors, which should not be raised
+         * under any circumstances.
+         */
         try {
             this.element.append(toinsert);
         } catch(err) {
@@ -588,7 +596,9 b' define(['
 
 
     var append_javascript = function (js, md, element) {
-        // We just eval the JS code, element appears in the local scope.
+        /**
+         * We just eval the JS code, element appears in the local scope.
+         */
         var type = 'application/javascript';
         var toinsert = this.create_output_subarea(md, "output_javascript", type);
         this.keyboard_manager.register_events(toinsert);
@@ -652,14 +662,16 b' define(['
     };
 
     OutputArea.prototype._dblclick_to_reset_size = function (img, immediately, resize_parent) {
-        // Add a resize handler to an element
-        //
-        // img: jQuery element
-        // immediately: bool=False
-        //      Wait for the element to load before creating the handle.
-        // resize_parent: bool=True
-        //      Should the parent of the element be resized when the element is
-        //      reset (by double click).
+        /**
+         * Add a resize handler to an element
+         *
+         * img: jQuery element
+         * immediately: bool=False
+         *      Wait for the element to load before creating the handle.
+         * resize_parent: bool=True
+         *      Should the parent of the element be resized when the element is
+         *      reset (by double click).
+         */
         var callback = function (){
             var h0 = img.height();
             var w0 = img.width();
@@ -690,7 +702,9 b' define(['
     };
     
     var set_width_height = function (img, md, mime) {
-        // set width and height of an img element from metadata
+        /**
+         * set width and height of an img element from metadata
+         */
         var height = _get_metadata_key(md, 'height', mime);
         if (height !== undefined) img.attr('height', height);
         var width = _get_metadata_key(md, 'width', mime);
@@ -745,8 +759,10 b' define(['
      };
 
     var append_latex = function (latex, md, element) {
-        // This method cannot do the typesetting because the latex first has to
-        // be on the page.
+        /**
+         * This method cannot do the typesetting because the latex first has to
+         * be on the page.
+         */
         var type = 'text/latex';
         var toinsert = this.create_output_subarea(md, "output_latex", type);
         toinsert.append(latex);
@@ -825,11 +841,13 b' define(['
 
 
     OutputArea.prototype.handle_clear_output = function (msg) {
-        // msg spec v4 had stdout, stderr, display keys
-        // v4.1 replaced these with just wait
-        // The default behavior is the same (stdout=stderr=display=True, wait=False),
-        // so v4 messages will still be properly handled,
-        // except for the rarely used clearing less than all output.
+        /**
+         * msg spec v4 had stdout, stderr, display keys
+         * v4.1 replaced these with just wait
+         * The default behavior is the same (stdout=stderr=display=True, wait=False),
+         * so v4 messages will still be properly handled,
+         * except for the rarely used clearing less than all output.
+         */
         this.clear_output(msg.content.wait || false);
     };
 

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

@@ -9,15 +9,17 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
+        /**
+         * 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');
@@ -30,7 +32,9 b' define(['
                         axis:'y',
                         helper: null ,
                         drag: function(event, ui) {
-                            // recalculate the amount of space the pager should take
+                            /**
+                             * recalculate the amount of space the pager should take
+                             */
                             var pheight = ($(document.body).height()-event.clientY-4);
                             var downprct = pheight/options.layout_manager.app_height();
                                 downprct = Math.min(0.9, downprct);
@@ -173,8 +177,10 b' define(['
     };
 
     Pager.prototype.append_text = function (text) {
-        // The only user content injected with this HTML call is escaped by
-        // the fixConsole() method.
+        /**
+         * The only user content injected with this HTML call is escaped by
+         * the fixConsole() method.
+         */
         this.pager_element.find(".container").append($('<pre/>').html(utils.fixCarriageReturn(utils.fixConsole(text))));
     };
 

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

@@ -11,14 +11,16 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
-        //          notebook: Notebook instance
+        /**
+         * Constructor
+         *
+         * Parameters:
+         *  options: dictionary
+         *      Dictionary of keyword arguments.
+         *          events: $(Events) instance
+         *          keyboard_manager: KeyboardManager instance
+         *          notebook: Notebook instance
+         */
         this.keyboard_manager = options.keyboard_manager;
         this.notebook = options.notebook;
         this.keyboard_manager.quick_help = this;
@@ -66,7 +68,9 b' define(['
 
 
     QuickHelp.prototype.show_keyboard_shortcuts = function () {
-        // toggles display of keyboard shortcut dialog
+        /**
+         * toggles display of keyboard shortcut dialog
+         */
         var that = this;
         if ( this.force_rebuild ) {
             this.shortcut_dialog.remove();

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

@@ -12,7 +12,9 b' define(['
     "use strict";
 
     var SaveWidget = function (selector, options) {
-        // TODO: Remove circular ref.
+        /**
+         * TODO: Remove circular ref.
+         */
         this.notebook = undefined;
         this.selector = selector;
         this.events = options.events;
@@ -111,7 +113,9 b' define(['
                 "Cancel": {}
                 },
             open : function () {
-                // Upon ENTER, click the OK button.
+                /**
+                 * Upon ENTER, click the OK button.
+                 */
                 d.find('input[type="text"]').keydown(function (event) {
                     if (event.which === keyboard.keycodes.enter) {
                         d.find('.btn-primary').first().click();
@@ -206,8 +210,10 b' define(['
 
         var that = this;
         var recall  = function(t){
-            // recall slightly later (1s) as long timeout in js might be imprecise,
-            // and you want to be call **after** the change of formatting should happend.
+            /**
+             * recall slightly later (1s) as long timeout in js might be imprecise,
+             * and you want to be call **after** the change of formatting should happend.
+             */
             return setTimeout(
                 $.proxy(that._regularly_update_checkpoint_date, that),
                 t + 1000

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

@@ -4,47 +4,57 b" define(['jquery'], function($){"
     "use strict";
 
     var ScrollManager = function(notebook, options) {
-        // Public constructor.
+        /**
+         * Public constructor.
+         */
         this.notebook = notebook;
         options = options || {};
         this.animation_speed = options.animation_speed || 250; //ms
     };
 
     ScrollManager.prototype.scroll = function (delta) {
-        // Scroll the document.
-        //
-        // Parameters
-        // ----------
-        // delta: integer
-        //  direction to scroll the document.  Positive is downwards. 
-        //  Unit is one page length.
+        /**
+         * Scroll the document.
+         *
+         * Parameters
+         * ----------
+         * delta: integer
+         *  direction to scroll the document.  Positive is downwards. 
+         *  Unit is one page length.
+         */
         this.scroll_some(delta);
         return false;
     };
 
     ScrollManager.prototype.scroll_to = function(selector) {
-        // Scroll to an element in the notebook.
+        /**
+         * Scroll to an element in the notebook.
+         */
         $('#notebook').animate({'scrollTop': $(selector).offset().top + $('#notebook').scrollTop() - $('#notebook').offset().top}, this.animation_speed);
     };
 
     ScrollManager.prototype.scroll_some = function(pages) {
-        // Scroll up or down a given number of pages.
-        //
-        // Parameters
-        // ----------
-        // pages: integer
-        //  number of pages to scroll the document, may be positive or negative.
+        /**
+         * Scroll up or down a given number of pages.
+         *
+         * Parameters
+         * ----------
+         * pages: integer
+         *  number of pages to scroll the document, may be positive or negative.
+         */
         $('#notebook').animate({'scrollTop': $('#notebook').scrollTop() + pages * $('#notebook').height()}, this.animation_speed);
     };
 
     ScrollManager.prototype.get_first_visible_cell = function() {
-        // Gets the index of the first visible cell in the document.
-
-        // First, attempt to be smart by guessing the index of the cell we are
-        // scrolled to.  Then, walk from there up or down until the right cell 
-        // is found.  To guess the index, get the top of the last cell, and
-        // divide that by the number of cells to get an average cell height.  
-        // Then divide the scroll height by the average cell height.
+        /**
+         * Gets the index of the first visible cell in the document.
+         *
+         * First, attempt to be smart by guessing the index of the cell we are
+         * scrolled to.  Then, walk from there up or down until the right cell 
+         * is found.  To guess the index, get the top of the last cell, and
+         * divide that by the number of cells to get an average cell height.  
+         * Then divide the scroll height by the average cell height.
+         */
         var cell_count = this.notebook.ncells();
         var first_cell_top = this.notebook.get_cell(0).element.offset().top;
         var last_cell_top = this.notebook.get_cell(cell_count-1).element.offset().top;
@@ -65,34 +75,40 b" define(['jquery'], function($){"
 
 
     var TargetScrollManager = function(notebook, options) {
-        // Public constructor.
+        /**
+         * Public constructor.
+         */
         ScrollManager.apply(this, [notebook, options]);
     };
     TargetScrollManager.prototype = Object.create(ScrollManager.prototype);
 
     TargetScrollManager.prototype.is_target = function (index) {
-        // Check if a cell should be a scroll stop.
-        //
-        // Returns `true` if the cell is a cell that the scroll manager
-        // should scroll to.  Otherwise, false is returned. 
-        //
-        // Parameters
-        // ----------
-        // index: integer
-        //  index of the cell to test.
+        /**
+         * Check if a cell should be a scroll stop.
+         *
+         * Returns `true` if the cell is a cell that the scroll manager
+         * should scroll to.  Otherwise, false is returned. 
+         *
+         * Parameters
+         * ----------
+         * index: integer
+         *  index of the cell to test.
+         */
         return false;
     };
 
     TargetScrollManager.prototype.scroll = function (delta) {
-        // Scroll the document.
-        //
-        // Parameters
-        // ----------
-        // delta: integer
-        //  direction to scroll the document.  Positive is downwards.
-        //  Units are targets.
-
-        // Try to scroll to the next slide.
+        /**
+         * Scroll the document.
+         *
+         * Parameters
+         * ----------
+         * delta: integer
+         *  direction to scroll the document.  Positive is downwards.
+         *  Units are targets.
+         *
+         * Try to scroll to the next slide.
+         */
         var cell_count = this.notebook.ncells();
         var selected_index = this.get_first_visible_cell() + delta;
         while (0 <= selected_index && selected_index < cell_count && !this.is_target(selected_index)) {
@@ -111,7 +127,9 b" define(['jquery'], function($){"
 
 
     var SlideScrollManager = function(notebook, options) {
-        // Public constructor.
+        /**
+         * Public constructor.
+         */
         TargetScrollManager.apply(this, [notebook, options]);
     };
     SlideScrollManager.prototype = Object.create(TargetScrollManager.prototype);
@@ -126,7 +144,9 b" define(['jquery'], function($){"
 
 
     var HeadingScrollManager = function(notebook, options) {
-        // Public constructor.
+        /**
+         * Public constructor.
+         */
         ScrollManager.apply(this, [notebook, options]);
         options = options || {};
         this._level = options.heading_level || 1;
@@ -134,16 +154,18 b" define(['jquery'], function($){"
     HeadingScrollManager.prototype = Object.create(ScrollManager.prototype)
 
     HeadingScrollManager.prototype.scroll = function (delta) {
-        // Scroll the document.
-        //
-        // Parameters
-        // ----------
-        // delta: integer
-        //  direction to scroll the document.  Positive is downwards.
-        //  Units are headers.
-
-        // Get all of the header elements that match the heading level or are of
-        // greater magnitude (a smaller header number).
+        /**
+         * Scroll the document.
+         *
+         * Parameters
+         * ----------
+         * delta: integer
+         *  direction to scroll the document.  Positive is downwards.
+         *  Units are headers.
+         *
+         * Get all of the header elements that match the heading level or are of
+         * greater magnitude (a smaller header number).
+         */
         var headers = $();
         var i;
         for (i = 1; i <= this._level; i++) {

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

@@ -18,18 +18,20 b' define(['
     var Cell = cell.Cell;
 
     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
+        /**
+         * 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
@@ -195,15 +197,17 b' define(['
 
 
     var MarkdownCell = function (options) {
-        // Constructor
-        //
-        // Parameters:
-        //  options: dictionary
-        //      Dictionary of keyword arguments.
-        //          events: $(Events) instance 
-        //          config: dictionary
-        //          keyboard_manager: KeyboardManager instance 
-        //          notebook: Notebook instance
+        /**
+         * Constructor
+         *
+         * Parameters:
+         *  options: dictionary
+         *      Dictionary of keyword arguments.
+         *          events: $(Events) instance 
+         *          config: dictionary
+         *          keyboard_manager: KeyboardManager instance 
+         *          notebook: Notebook instance
+         */
         options = options || {};
         var config = utils.mergeopt(MarkdownCell, options.config);
         TextCell.apply(this, [$.extend({}, options, {config: config})]);
@@ -221,7 +225,9 b' define(['
     MarkdownCell.prototype = Object.create(TextCell.prototype);
 
     MarkdownCell.prototype.set_heading_level = function (level) {
-        // make a markdown cell a heading
+        /**
+         * make a markdown cell a heading
+         */
         level = level || 1;
         var source = this.get_text();
         source = source.replace(/^(#*)\s?/,
@@ -274,15 +280,17 b' define(['
 
 
     var RawCell = function (options) {
-        // Constructor
-        //
-        // Parameters:
-        //  options: dictionary
-        //      Dictionary of keyword arguments.
-        //          events: $(Events) instance 
-        //          config: dictionary
-        //          keyboard_manager: KeyboardManager instance 
-        //          notebook: Notebook instance
+        /**
+         * Constructor
+         *
+         * Parameters:
+         *  options: dictionary
+         *      Dictionary of keyword arguments.
+         *          events: $(Events) instance 
+         *          config: dictionary
+         *          keyboard_manager: KeyboardManager instance 
+         *          notebook: Notebook instance
+         */
         options = options || {};
         var config = utils.mergeopt(RawCell, options.config);
         TextCell.apply(this, [$.extend({}, options, {config: config})]);

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

@@ -116,7 +116,9 b' define(['
     };
 
     Tooltip.prototype.showInPager = function (cell) {
-        // reexecute last call in pager by appending ? to show back in pager
+        /**
+         * reexecute last call in pager by appending ? to show back in pager
+         */
         this.events.trigger('open_with_text.Pager', this._reply.content);
         this.remove_and_cancel_tooltip();
     };
@@ -144,9 +146,11 b' define(['
     // return true on successfully removing a visible tooltip; otherwise return
     // false.
     Tooltip.prototype.remove_and_cancel_tooltip = function (force) {
-        // note that we don't handle closing directly inside the calltip
-        // as in the completer, because it is not focusable, so won't
-        // get the event.
+        /**
+         * note that we don't handle closing directly inside the calltip
+         * as in the completer, because it is not focusable, so won't
+         * get the event.
+         */
         this.cancel_pending();
         if (!this._hidden) {
           if (force || !this._sticky) {
@@ -186,9 +190,11 b' define(['
 
     // make an immediate completion request
     Tooltip.prototype.request = function (cell, hide_if_no_docstring) {
-        // request(codecell)
-        // Deal with extracting the text from the cell and counting
-        // call in a row
+        /**
+         * request(codecell)
+         * Deal with extracting the text from the cell and counting
+         * call in a row
+         */
         this.cancel_pending();
         var editor = cell.code_mirror;
         var cursor = editor.getCursor();
@@ -250,8 +256,10 b' define(['
 
     // should be called with the kernel reply to actually show the tooltip
     Tooltip.prototype._show = function (reply) {
-        // move the bubble if it is not hidden
-        // otherwise fade it
+        /**
+         * move the bubble if it is not hidden
+         * otherwise fade it
+         */
         this._reply = reply;
         var content = reply.content;
         if (!content.found) {

IPython/html/static/services/contents.js

@@ -7,16 +7,18 b' define(['
     'base/js/utils',
 ], function(IPython, $, utils) {
     var Contents = function(options) {
-        // Constructor
-        //
-        // A contents handles passing file operations
-        // to the back-end.  This includes checkpointing
-        // with the normal file operations.
-        //
-        // Parameters:
-        //  options: dictionary
-        //      Dictionary of keyword arguments.
-        //          base_url: string
+        /**
+         * Constructor
+         *
+         * A contents handles passing file operations
+         * to the back-end.  This includes checkpointing
+         * with the normal file operations.
+         *
+         * Parameters:
+         *  options: dictionary
+         *      Dictionary of keyword arguments.
+         *          base_url: string
+         */
         this.base_url = options.base_url;
     };
 
@@ -78,7 +80,9 b' define(['
      *    format: 'text' or 'base64'; only relevant for type: 'file'
      */
     Contents.prototype.get = function (path, options) {
-        // We do the call with settings so we can set cache to false.
+        /**
+         * We do the call with settings so we can set cache to false.
+         */
         var settings = {
             processData : false,
             cache : false,
@@ -151,7 +155,9 b' define(['
     };
 
     Contents.prototype.save = function(path, model) {
-        // We do the call with settings so we can set cache to false.
+        /**
+         * We do the call with settings so we can set cache to false.
+         */
         var settings = {
             processData : false,
             type : "PUT",
@@ -163,8 +169,10 b' define(['
     };
     
     Contents.prototype.copy = function(from_file, to_dir) {
-        // Copy a file into a given directory via POST
-        // The server will select the name of the copied file
+        /**
+         * Copy a file into a given directory via POST
+         * The server will select the name of the copied file
+         */
         var url = this.api_url(to_dir);
         
         var settings = {

IPython/html/static/services/kernels/comm.js

@@ -21,7 +21,9 b' define(['
     };
     
     CommManager.prototype.init_kernel = function (kernel) {
-        // connect the kernel, and register message handlers
+        /**
+         * connect the kernel, and register message handlers
+         */
         this.kernel = kernel;
         var msg_types = ['comm_open', 'comm_msg', 'comm_close'];
         for (var i = 0; i < msg_types.length; i++) {
@@ -31,8 +33,10 b' define(['
     };
     
     CommManager.prototype.new_comm = function (target_name, data, callbacks, metadata) {
-        // Create a new Comm, register it, and open its Kernel-side counterpart
-        // Mimics the auto-registration in `Comm.__init__` in the IPython Comm
+        /**
+         * Create a new Comm, register it, and open its Kernel-side counterpart
+         * Mimics the auto-registration in `Comm.__init__` in the IPython Comm
+         */
         var comm = new Comm(target_name);
         this.register_comm(comm);
         comm.open(data, callbacks, metadata);
@@ -40,24 +44,32 b' define(['
     };
     
     CommManager.prototype.register_target = function (target_name, f) {
-        // Register a target function for a given target name
+        /**
+         * Register a target function for a given target name
+         */
         this.targets[target_name] = f;
     };
     
     CommManager.prototype.unregister_target = function (target_name, f) {
-        // Unregister a target function for a given target name
+        /**
+         * Unregister a target function for a given target name
+         */
         delete this.targets[target_name];
     };
     
     CommManager.prototype.register_comm = function (comm) {
-        // Register a comm in the mapping
+        /**
+         * Register a comm in the mapping
+         */
         this.comms[comm.comm_id] = Promise.resolve(comm);
         comm.kernel = this.kernel;
         return comm.comm_id;
     };
     
     CommManager.prototype.unregister_comm = function (comm) {
-        // Remove a comm from the mapping
+        /**
+         * Remove a comm from the mapping
+         */
         delete this.comms[comm.comm_id];
     };
     

IPython/html/static/services/kernels/kernel.js

@@ -266,7 +266,9 b' define(['
 
         var that = this;
         var on_success = function (data, status, xhr) {
-            // get kernel info so we know what state the kernel is in
+            /**
+             * get kernel info so we know what state the kernel is in
+             */
             that.kernel_info();
             if (success) {
                 success(data, status, xhr);
@@ -538,8 +540,10 b' define(['
     };
     
     Kernel.prototype._schedule_reconnect = function () {
-        // function to call when kernel connection is lost
-        // schedules reconnect, or fires 'connection_dead' if reconnect limit is hit
+        /**
+         * function to call when kernel connection is lost
+         * schedules reconnect, or fires 'connection_dead' if reconnect limit is hit
+         */
         if (this._reconnect_attempt < this.reconnect_limit) {
             var timeout = Math.pow(2, this._reconnect_attempt);
             console.log("Connection lost, reconnecting in " + timeout + " seconds.");

IPython/html/static/services/kernels/serialize.js

@@ -31,9 +31,11 b' define(['
     };
     
     var _deserialize_binary = function(data, callback) {
-        // deserialize the binary message format
-        // callback will be called with a message whose buffers attribute
-        // will be an array of DataViews.
+        /**
+         * deserialize the binary message format
+         * callback will be called with a message whose buffers attribute
+         * will be an array of DataViews.
+         */
         if (data instanceof Blob) {
             // data is Blob, have to deserialize from ArrayBuffer in reader callback
             var reader = new FileReader();
@@ -50,7 +52,9 b' define(['
     };
 
     var deserialize = function (data, callback) {
-        // deserialize a message and pass the unpacked message object to callback
+        /**
+         * deserialize a message and pass the unpacked message object to callback
+         */
         if (typeof data === "string") {
             // text JSON message
             callback(JSON.parse(data));
@@ -61,8 +65,10 b' define(['
     };
     
     var _serialize_binary = function (msg) {
-        // implement the binary serialization protocol
-        // serializes JSON message to ArrayBuffer
+        /**
+         * implement the binary serialization protocol
+         * serializes JSON message to ArrayBuffer
+         */
         msg = _.clone(msg);
         var offsets = [];
         var buffers = [];

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

@@ -9,15 +9,17 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
+        /**
+         * 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));
@@ -26,7 +28,9 b' define(['
     KernelList.prototype = Object.create(notebooklist.NotebookList.prototype);
 
     KernelList.prototype.add_duplicate_button = function () {
-        // do nothing
+        /**
+         * do nothing
+         */
     };
     
     KernelList.prototype.sessions_loaded = function (d) {

IPython/html/static/tree/js/main.js

@@ -88,7 +88,9 b' require(['
     var time_refresh = 60; // in sec
 
     var enable_autorefresh = function(){
-        //refresh immediately , then start interval
+        /**
+         *refresh immediately , then start interval
+         */
         session_list.load_sessions();
         cluster_list.load_list();
 	if (terminal_list) {

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

@@ -11,17 +11,19 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
-        //          contents: Contents instance
+        /**
+         * Constructor
+         *
+         * Parameters:
+         *  selector: string
+         *  options: dictionary
+         *      Dictionary of keyword arguments.
+         *          session_list: SessionList instance
+         *          element_name: string
+         *          base_url: string
+         *          notebook_path: string
+         *          contents: Contents instance
+         */
         var that = this;
         this.session_list = options.session_list;
         // allow code re-use by just changing element_name in kernellist.js
@@ -119,11 +121,13 b' define(['
     };
 
     NotebookList.prototype.clear_list = function (remove_uploads) {
-        // Clears the navigation tree.
-        //
-        // Parameters
-        // remove_uploads: bool=False
-        //      Should upload prompts also be removed from the tree.
+        /**
+         * Clears the navigation tree.
+         *
+         * Parameters
+         * remove_uploads: bool=False
+         *      Should upload prompts also be removed from the tree.
+         */
         if (remove_uploads) {
             this.element.children('.list_item').remove();
         } else {
@@ -378,7 +382,9 b' define(['
     };
 
     NotebookList.prototype.notebook_deleted = function(path) {
-        // Remove the deleted notebook.
+        /**
+         * Remove the deleted notebook.
+         */
         $( ":data(path)" ).each(function() {
             var element = $(this);
             if (element.data("path") == path) {

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

@@ -9,13 +9,15 b' define(['
     "use strict";
 
     var SesssionList = function (options) {
-        // Constructor
-        //
-        // Parameters:
-        //  options: dictionary
-        //      Dictionary of keyword arguments.
-        //          events: $(Events) instance
-        //          base_url : string
+        /**
+         * 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");

IPython/html/static/tree/js/terminallist.js

@@ -10,13 +10,15 b' define(['
     "use strict";
 
     var TerminalList = function (selector, options) {
-        // Constructor
-        //
-        // Parameters:
-        //  selector: string
-        //  options: dictionary
-        //      Dictionary of keyword arguments.
-        //          base_url: string
+        /**
+         * Constructor
+         *
+         * Parameters:
+         *  selector: string
+         *  options: dictionary
+         *      Dictionary of keyword arguments.
+         *          base_url: string
+         */
         this.base_url = options.base_url || utils.get_body_data("baseUrl");
         this.element_name = options.element_name || 'terminal';
         this.selector = selector;

IPython/html/static/widgets/js/manager.js

@@ -13,7 +13,9 b' define(['
     // WidgetManager class
     //--------------------------------------------------------------------
     var WidgetManager = function (comm_manager, notebook) {
-        // Public constructor
+        /**
+         * Public constructor
+         */
         WidgetManager._managers.push(this);
 
         // Attach a comm manager to the 
@@ -47,7 +49,9 b' define(['
     // Instance level
     //--------------------------------------------------------------------
     WidgetManager.prototype.display_view = function(msg, model) {
-        // Displays a view for a particular model.
+        /**
+         * Displays a view for a particular model.
+         */
         var that = this;
         var cell = this.get_msg_cell(msg.parent_header.msg_id);
         if (cell === null) {
@@ -67,9 +71,11 b' define(['
     };
 
     WidgetManager.prototype._handle_display_view = function (view) {
-        // Have the IPython keyboard manager disable its event
-        // handling so the widget can capture keyboard input.
-        // Note, this is only done on the outer most widgets.
+        /**
+         * Have the IPython keyboard manager disable its event
+         * handling so the widget can capture keyboard input.
+         * Note, this is only done on the outer most widgets.
+         */
         if (this.keyboard_manager) {
             this.keyboard_manager.register_events(view.$el);
         
@@ -82,10 +88,12 b' define(['
     };
     
     WidgetManager.prototype.create_view = function(model, options) {
-        // Creates a promise for a view of a given model
-
-        // Make sure the view creation is not out of order with 
-        // any state updates.
+        /**
+         * Creates a promise for a view of a given model
+         *
+         * Make sure the view creation is not out of order with 
+         * any state updates.
+         */
         model.state_change = model.state_change.then(function() {
             
             return utils.load_class(model.get('_view_name'), model.get('_view_module'),
@@ -135,7 +143,9 b' define(['
     };
 
     WidgetManager.prototype.callbacks = function (view) {
-        // callback handlers specific a view
+        /**
+         * callback handlers specific a view
+         */
         var callbacks = {};
         if (view && view.options.cell) {
 
@@ -168,12 +178,16 b' define(['
     };
 
     WidgetManager.prototype.get_model = function (model_id) {
-        // Get a promise for a model by model id.
+        /**
+         * Get a promise for a model by model id.
+         */
         return this._models[model_id];
     };
 
     WidgetManager.prototype._handle_comm_open = function (comm, msg) {
-        // Handle when a comm is opened.
+        /**
+         * Handle when a comm is opened.
+         */
         return this.create_model({
             model_name: msg.content.data.model_name, 
             model_module: msg.content.data.model_module, 
@@ -181,33 +195,35 b' define(['
     };
 
     WidgetManager.prototype.create_model = function (options) {
-        // Create and return a promise for a new widget model
-        //
-        // Minimally, one must provide the model_name and widget_class
-        // parameters to create a model from Javascript.
-        //
-        // Example
-        // --------
-        // JS:
-        // IPython.notebook.kernel.widget_manager.create_model({
-        //      model_name: 'WidgetModel', 
-        //      widget_class: 'IPython.html.widgets.widget_int.IntSlider'})
-        //      .then(function(model) { console.log('Create success!', model); },
-        //      $.proxy(console.error, console));
-        //
-        // Parameters
-        // ----------
-        // options: dictionary
-        //  Dictionary of options with the following contents:
-        //      model_name: string
-        //          Target name of the widget model to create.
-        //      model_module: (optional) string
-        //          Module name of the widget model to create.
-        //      widget_class: (optional) string
-        //          Target name of the widget in the back-end.
-        //      comm: (optional) Comm
-        
-        // Create a comm if it wasn't provided.
+        /**
+         * Create and return a promise for a new widget model
+         *
+         * Minimally, one must provide the model_name and widget_class
+         * parameters to create a model from Javascript.
+         *
+         * Example
+         * --------
+         * JS:
+         * IPython.notebook.kernel.widget_manager.create_model({
+         *      model_name: 'WidgetModel', 
+         *      widget_class: 'IPython.html.widgets.widget_int.IntSlider'})
+         *      .then(function(model) { console.log('Create success!', model); },
+         *      $.proxy(console.error, console));
+         *
+         * Parameters
+         * ----------
+         * options: dictionary
+         *  Dictionary of options with the following contents:
+         *      model_name: string
+         *          Target name of the widget model to create.
+         *      model_module: (optional) string
+         *          Module name of the widget model to create.
+         *      widget_class: (optional) string
+         *          Target name of the widget in the back-end.
+         *      comm: (optional) Comm
+         *
+         * Create a comm if it wasn't provided.
+         */
         var comm = options.comm;
         if (!comm) {
             comm = this.comm_manager.new_comm('ipython.widget', {'widget_class': options.widget_class});

IPython/html/static/widgets/js/widget.js

@@ -11,16 +11,18 b' define(["widgets/js/manager",'
 
     var WidgetModel = Backbone.Model.extend({
         constructor: function (widget_manager, model_id, comm) {
-            // Constructor
-            //
-            // Creates a WidgetModel instance.
-            //
-            // Parameters
-            // ----------
-            // widget_manager : WidgetManager instance
-            // model_id : string
-            //      An ID unique to this model.
-            // comm : Comm instance (optional)
+            /**
+             * Constructor
+             *
+             * Creates a WidgetModel instance.
+             *
+             * Parameters
+             * ----------
+             * widget_manager : WidgetManager instance
+             * model_id : string
+             *      An ID unique to this model.
+             * comm : Comm instance (optional)
+             */
             this.widget_manager = widget_manager;
             this.state_change = Promise.resolve();
             this._buffered_state_diff = {};
@@ -43,7 +45,9 b' define(["widgets/js/manager",'
         },
 
         send: function (content, callbacks) {
-            // Send a custom msg over the comm.
+            /**
+             * Send a custom msg over the comm.
+             */
             if (this.comm !== undefined) {
                 var data = {method: 'custom', content: content};
                 this.comm.send(data, callbacks);
@@ -52,7 +56,9 b' define(["widgets/js/manager",'
         },
 
         _handle_comm_closed: function (msg) {
-            // Handle when a widget is closed.
+            /**
+             * Handle when a widget is closed.
+             */
             this.trigger('comm:close');
             this.stopListening();
             this.trigger('destroy', this);
@@ -67,7 +73,9 b' define(["widgets/js/manager",'
         },
 
         _handle_comm_msg: function (msg) {
-            // Handle incoming comm msg.
+            /**
+             * Handle incoming comm msg.
+             */
             var method = msg.content.data.method;
             var that = this;
             switch (method) {
@@ -99,9 +107,11 b' define(["widgets/js/manager",'
         },
 
         _handle_status: function (msg, callbacks) {
-            // Handle status msgs.
-
-            // execution_state : ('busy', 'idle', 'starting')
+            /**
+             * Handle status msgs.
+             *
+             * execution_state : ('busy', 'idle', 'starting')
+             */
             if (this.comm !== undefined) {
                 if (msg.content.execution_state ==='idle') {
                     // Send buffer if this message caused another message to be
@@ -119,7 +129,9 b' define(["widgets/js/manager",'
         },
 
         callbacks: function(view) {
-            // Create msg callbacks for a comm msg.
+            /**
+             * Create msg callbacks for a comm msg.
+             */
             var callbacks = this.widget_manager.callbacks(view);
 
             if (callbacks.iopub === undefined) {
@@ -134,7 +146,9 b' define(["widgets/js/manager",'
         },
 
         set: function(key, val, options) {
-            // Set a value.
+            /**
+             * Set a value.
+             */
             var return_value = WidgetModel.__super__.set.apply(this, arguments);
 
             // Backbone only remembers the diff of the most recent set()
@@ -145,9 +159,11 b' define(["widgets/js/manager",'
         },
 
         sync: function (method, model, options) {
-            // Handle sync to the back-end.  Called when a model.save() is called.
-
-            // Make sure a comm exists.
+            /**
+             * Handle sync to the back-end.  Called when a model.save() is called.
+             *
+             * Make sure a comm exists.
+             */
             var error = options.error || function() {
                 console.error('Backbone sync error:', arguments);
             };
@@ -213,14 +229,18 b' define(["widgets/js/manager",'
         },
 
         save_changes: function(callbacks) {
-            // Push this model's state to the back-end
-            //
-            // This invokes a Backbone.Sync.
+            /**
+             * Push this model's state to the back-end
+             *
+             * This invokes a Backbone.Sync.
+             */
             this.save(this._buffered_state_diff, {patch: true, callbacks: callbacks});
         },
 
         _pack_models: function(value) {
-            // Replace models with model ids recursively.
+            /**
+             * Replace models with model ids recursively.
+             */
             var that = this;
             var packed;
             if (value instanceof Backbone.Model) {
@@ -247,7 +267,9 b' define(["widgets/js/manager",'
         },
 
         _unpack_models: function(value) {
-            // Replace model ids with models recursively.
+            /**
+             * Replace model ids with models recursively.
+             */
             var that = this;
             var unpacked;
             if ($.isArray(value)) {
@@ -271,11 +293,13 b' define(["widgets/js/manager",'
         },
 
         on_some_change: function(keys, callback, context) {
-            // on_some_change(["key1", "key2"], foo, context) differs from
-            // on("change:key1 change:key2", foo, context).
-            // If the widget attributes key1 and key2 are both modified, 
-            // the second form will result in foo being called twice
-            // while the first will call foo only once.
+            /**
+             * on_some_change(["key1", "key2"], foo, context) differs from
+             * on("change:key1 change:key2", foo, context).
+             * If the widget attributes key1 and key2 are both modified, 
+             * the second form will result in foo being called twice
+             * while the first will call foo only once.
+             */
             this.on('change', function() {
                 if (keys.some(this.hasChanged, this)) {
                     callback.apply(context);
@@ -289,7 +313,9 b' define(["widgets/js/manager",'
 
     var WidgetView = Backbone.View.extend({
         initialize: function(parameters) {
-            // Public constructor.
+            /**
+             * Public constructor.
+             */
             this.model.on('change',this.update,this);
             this.options = parameters.options;
             this.id = this.id || utils.uuid();
@@ -300,31 +326,41 b' define(["widgets/js/manager",'
         },
 
         update: function(){
-            // Triggered on model change.
-            //
-            // Update view to be consistent with this.model
+            /**
+             * Triggered on model change.
+             *
+             * Update view to be consistent with this.model
+             */
         },
 
         create_child_view: function(child_model, options) {
-            // Create and promise that resolves to a child view of a given model
+            /**
+             * Create and promise that resolves to a child view of a given model
+             */
             var that = this;
             options = $.extend({ parent: this }, options || {});
             return this.model.widget_manager.create_view(child_model, options).catch(utils.reject("Couldn't create child view"), true);
         },
 
         callbacks: function(){
-            // Create msg callbacks for a comm msg.
+            /**
+             * Create msg callbacks for a comm msg.
+             */
             return this.model.callbacks(this);
         },
 
         render: function(){
-            // Render the view.
-            //
-            // By default, this is only called the first time the view is created
+            /**
+             * Render the view.
+             *
+             * By default, this is only called the first time the view is created
+             */
         },
 
         show: function(){
-            // Show the widget-area
+            /**
+             * Show the widget-area
+             */
             if (this.options && this.options.cell &&
                 this.options.cell.widget_area !== undefined) {
                 this.options.cell.widget_area.show();
@@ -332,7 +368,9 b' define(["widgets/js/manager",'
         },
 
         send: function (content) {
-            // Send a custom msg associated with this view.
+            /**
+             * Send a custom msg associated with this view.
+             */
             this.model.send(content, this.callbacks());
         },
 
@@ -341,8 +379,10 b' define(["widgets/js/manager",'
         },
 
         after_displayed: function (callback, context) {
-            // Calls the callback right away is the view is already displayed
-            // otherwise, register the callback to the 'displayed' event.
+            /**
+             * Calls the callback right away is the view is already displayed
+             * otherwise, register the callback to the 'displayed' event.
+             */
             if (this.is_displayed) {
                 callback.apply(context);
             } else {
@@ -354,7 +394,9 b' define(["widgets/js/manager",'
 
     var DOMWidgetView = WidgetView.extend({
         initialize: function (parameters) {
-            // Public constructor
+            /**
+             * Public constructor
+             */
             DOMWidgetView.__super__.initialize.apply(this, [parameters]);
             this.on('displayed', this.show, this);
             this.model.on('change:visible', this.update_visible, this);
@@ -431,7 +473,9 b' define(["widgets/js/manager",'
         },
 
         _default_px: function(value) {
-            // Makes browser interpret a numerical string as a pixel value.
+            /**
+             * Makes browser interpret a numerical string as a pixel value.
+             */
             if (/^\d+\.?(\d+)?$/.test(value.trim())) {
                 return value.trim() + 'px';
             }
@@ -439,17 +483,23 b' define(["widgets/js/manager",'
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             this.$el.css(name, value);
         },
 
         update_visible: function(model, value) {
-            // Update visibility
+            /**
+             * Update visibility
+             */
             this.$el.toggle(value);
          },
 
         update_css: function (model, css) {
-            // Update the css styling of this view.
+            /**
+             * Update the css styling of this view.
+             */
             var e = this.$el;
             if (css === undefined) {return;}
             for (var i = 0; i < css.length; i++) {
@@ -465,7 +515,9 b' define(["widgets/js/manager",'
         },
 
         update_classes: function (old_classes, new_classes, $el) {
-            // Update the DOM classes applied to an element, default to this.$el.
+            /**
+             * Update the DOM classes applied to an element, default to this.$el.
+             */
             if ($el===undefined) {
                 $el = this.$el;
             }
@@ -474,30 +526,32 b' define(["widgets/js/manager",'
         },
 
         update_mapped_classes: function(class_map, trait_name, previous_trait_value, $el) {
-            // Update the DOM classes applied to the widget based on a single
-            // trait's value.
-            //
-            // Given a trait value classes map, this function automatically
-            // handles applying the appropriate classes to the widget element
-            // and removing classes that are no longer valid.
-            //
-            // Parameters
-            // ----------
-            // class_map: dictionary
-            //  Dictionary of trait values to class lists.
-            //  Example:
-            //      {
-            //          success: ['alert', 'alert-success'],
-            //          info: ['alert', 'alert-info'],
-            //          warning: ['alert', 'alert-warning'],
-            //          danger: ['alert', 'alert-danger']
-            //      };
-            // trait_name: string
-            //  Name of the trait to check the value of.
-            // previous_trait_value: optional string, default ''
-            //  Last trait value
-            // $el: optional jQuery element handle, defaults to this.$el
-            //  Element that the classes are applied to.
+            /**
+             * Update the DOM classes applied to the widget based on a single
+             * trait's value.
+             *
+             * Given a trait value classes map, this function automatically
+             * handles applying the appropriate classes to the widget element
+             * and removing classes that are no longer valid.
+             *
+             * Parameters
+             * ----------
+             * class_map: dictionary
+             *  Dictionary of trait values to class lists.
+             *  Example:
+             *      {
+             *          success: ['alert', 'alert-success'],
+             *          info: ['alert', 'alert-info'],
+             *          warning: ['alert', 'alert-warning'],
+             *          danger: ['alert', 'alert-danger']
+             *      };
+             * trait_name: string
+             *  Name of the trait to check the value of.
+             * previous_trait_value: optional string, default ''
+             *  Last trait value
+             * $el: optional jQuery element handle, defaults to this.$el
+             *  Element that the classes are applied to.
+             */
             var key = previous_trait_value;
             if (key === undefined) {
                 key = this.model.previous(trait_name);
@@ -510,7 +564,9 b' define(["widgets/js/manager",'
         },
         
         _get_selector_element: function (selector) {
-            // Get the elements via the css selector.
+            /**
+             * Get the elements via the css selector.
+             */
             var elements;
             if (!selector) {
                 elements = this.$el;
@@ -523,16 +579,18 b' define(["widgets/js/manager",'
 
 
     var ViewList = function(create_view, remove_view, context) {
-        // * create_view and remove_view are default functions called when adding or removing views
-        // * create_view takes a model and returns a view or a promise for a view for that model
-        // * remove_view takes a view and destroys it (including calling `view.remove()`)
-        // * each time the update() function is called with a new list, the create and remove
-        //   callbacks will be called in an order so that if you append the views created in the
-        //   create callback and remove the views in the remove callback, you will duplicate 
-        //   the order of the list.
-        // * the remove callback defaults to just removing the view (e.g., pass in null for the second parameter)
-        // * the context defaults to the created ViewList.  If you pass another context, the create and remove
-        //   will be called in that context.
+        /**
+         * - create_view and remove_view are default functions called when adding or removing views
+         * - create_view takes a model and returns a view or a promise for a view for that model
+         * - remove_view takes a view and destroys it (including calling `view.remove()`)
+         * - each time the update() function is called with a new list, the create and remove
+         *   callbacks will be called in an order so that if you append the views created in the
+         *   create callback and remove the views in the remove callback, you will duplicate 
+         *   the order of the list.
+         * - the remove callback defaults to just removing the view (e.g., pass in null for the second parameter)
+         * - the context defaults to the created ViewList.  If you pass another context, the create and remove
+         *   will be called in that context.
+         */
 
         this.initialize.apply(this, arguments);
     };
@@ -548,9 +606,11 b' define(["widgets/js/manager",'
         },
 
         update: function(new_models, create_view, remove_view, context) {
-            // the create_view, remove_view, and context arguments override the defaults
-            // specified when the list is created.
-            // returns a promise that resolves after this update is done
+            /**
+             * the create_view, remove_view, and context arguments override the defaults
+             * specified when the list is created.
+             * returns a promise that resolves after this update is done
+             */
             var remove = remove_view || this._remove_view;
             var create = create_view || this._create_view;
             if (create === undefined || remove === undefined){
@@ -588,9 +648,11 b' define(["widgets/js/manager",'
         },
 
         remove: function() {
-            // removes every view in the list; convenience function for `.update([])`
-            // that should be faster
-            // returns a promise that resolves after this removal is done
+            /**
+             * removes every view in the list; convenience function for `.update([])`
+             * that should be faster
+             * returns a promise that resolves after this removal is done
+             */
             var that = this;
             this.state_change = this.state_change.then(function() {
                 for (var i = 0; i < that.views.length; i++) {

IPython/html/static/widgets/js/widget_bool.js

@@ -9,7 +9,9 b' define(['
 
     var CheckboxView = widget.DOMWidgetView.extend({
         render : function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.$el
                 .addClass('widget-hbox widget-checkbox');
             this.$label = $('<div />')
@@ -25,25 +27,31 b' define(['
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             this.$checkbox.css(name, value);
         },
 
         handle_click: function() {
-            // Handles when the checkbox is clicked.
-
-            // Calling model.set will trigger all of the other views of the 
-            // model to update.
+            /**
+             * Handles when the checkbox is clicked.
+             *
+             * Calling model.set will trigger all of the other views of the 
+             * model to update.
+             */
             var value = this.model.get('value');
             this.model.set('value', ! value, {updated_view: this});
             this.touch();
         },
         
         update : function(options){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             this.$checkbox.prop('checked', this.model.get('value'));
 
             if (options === undefined || options.updated_view != this) {
@@ -67,7 +75,9 b' define(['
 
     var ToggleButtonView = widget.DOMWidgetView.extend({
         render : function() {
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             var that = this;
             this.setElement($('<button />')
                 .addClass('btn btn-default')
@@ -97,10 +107,12 b' define(['
         },
         
         update : function(options){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             if (this.model.get('value')) {
                 this.$el.addClass('active');
             } else {
@@ -124,10 +136,12 b' define(['
         },
         
         handle_click: function(e) { 
-            // Handles and validates user input.
-
-            // Calling model.set will trigger all of the other views of the 
-            // model to update.
+            /**
+             * Handles and validates user input.
+             *
+             * Calling model.set will trigger all of the other views of the 
+             * model to update.
+             */
             var value = this.model.get('value');
             this.model.set('value', ! value, {updated_view: this});
             this.touch();

IPython/html/static/widgets/js/widget_box.js

@@ -10,7 +10,9 b' define(['
 
     var BoxView = widget.DOMWidgetView.extend({
         initialize: function(){
-            // Public constructor
+            /**
+             * Public constructor
+             */
             BoxView.__super__.initialize.apply(this, arguments);
             this.children_views = new widget.ViewList(this.add_child_model, null, this);
             this.listenTo(this.model, 'change:children', function(model, value) {
@@ -28,12 +30,16 b' define(['
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             this.$box.css(name, value);
         },
 
         render: function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.$box = this.$el;
             this.$box.addClass('widget-box');
             this.children_views.update(this.model.get('children'));
@@ -43,12 +49,16 b' define(['
         },
 
         update_overflow_x: function() {
-            // Called when the x-axis overflow setting is changed.
+            /**
+             * Called when the x-axis overflow setting is changed.
+             */
             this.$box.css('overflow-x', this.model.get('overflow_x'));
         },
 
         update_overflow_y: function() {
-            // Called when the y-axis overflow setting is changed.
+            /**
+             * Called when the y-axis overflow setting is changed.
+             */
             this.$box.css('overflow-y', this.model.get('overflow_y'));
         },
 
@@ -63,7 +73,9 b' define(['
         },
         
         add_child_model: function(model) {
-            // Called when a model is added to the children list.
+            /**
+             * Called when a model is added to the children list.
+             */
             var that = this;
             var dummy = $('<div/>');
             that.$box.append(dummy);
@@ -79,9 +91,11 b' define(['
         },
         
         remove: function() {
-            // We remove this widget before removing the children as an optimization
-            // we want to remove the entire container from the DOM first before
-            // removing each individual child separately.
+            /**
+             * We remove this widget before removing the children as an optimization
+             * we want to remove the entire container from the DOM first before
+             * removing each individual child separately.
+             */
             BoxView.__super__.remove.apply(this, arguments);
             this.children_views.remove();
         },
@@ -135,7 +149,9 b' define(['
     var PopupView = BoxView.extend({
 
         render: function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             var that = this;
             
             this.$el.on("remove", function(){
@@ -245,13 +261,17 b' define(['
         },
         
         hide: function() {
-            // Called when the modal hide button is clicked.
+            /**
+             * Called when the modal hide button is clicked.
+             */
             this.$window.hide();
             this.$show_button.removeClass('btn-info');
         },
         
         show: function() {
-            // Called when the modal show button is clicked.
+            /**
+             * Called when the modal show button is clicked.
+             */
             this.$show_button.addClass('btn-info');
             this.$window.show();
             if (this.popped_out) {
@@ -264,7 +284,9 b' define(['
         },
         
         bring_to_front: function() {
-            // Make the modal top-most, z-ordered about the other modals.
+            /**
+             * Make the modal top-most, z-ordered about the other modals.
+             */
             var $widget_modals = $(".widget-modal");
             var max_zindex = 0;
             $widget_modals.each(function (index, el){
@@ -287,10 +309,12 b' define(['
         },
         
         update: function(){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             var description = this.model.get('description');
             if (description.trim().length === 0) {
                 this.$title.html("&nbsp;"); // Preserve title height
@@ -315,15 +339,17 b' define(['
         },
         
         _get_selector_element: function(selector) {
-            // Get an element view a 'special' jquery selector.  (see widget.js)
-            //
-            // Since the modal actually isn't within the $el in the DOM, we need to extend
-            // the selector logic to allow the user to set css on the modal if need be.
-            // The convention used is:
-            // "modal" - select the modal div
-            // "modal [selector]" - select element(s) within the modal div.
-            // "[selector]" - select elements within $el
-            // "" - select the $el
+            /**
+             * Get an element view a 'special' jquery selector.  (see widget.js)
+             *
+             * Since the modal actually isn't within the $el in the DOM, we need to extend
+             * the selector logic to allow the user to set css on the modal if need be.
+             * The convention used is:
+             * "modal" - select the modal div
+             * "modal [selector]" - select element(s) within the modal div.
+             * "[selector]" - select elements within $el
+             * "" - select the $el
+             */
             if (selector.substring(0, 5) == 'modal') {
                 if (selector == 'modal') {
                     return this.$window;

IPython/html/static/widgets/js/widget_button.js

@@ -9,7 +9,9 b' define(['
 
     var ButtonView = widget.DOMWidgetView.extend({
         render : function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.setElement($("<button />")
                 .addClass('btn btn-default'));
             this.$el.attr("data-toggle", "tooltip");
@@ -22,10 +24,12 b' define(['
         },
         
         update : function(){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             var description = this.model.get('description');
             this.$el.attr("title", this.model.get("tooltip"));
             if (description.length === 0) {
@@ -60,7 +64,9 b' define(['
         },
         
         _handle_click: function(){
-            // Handles when the button is clicked.
+            /**
+             * Handles when the button is clicked.
+             */
             this.send({event: 'click'});
         },
     });

IPython/html/static/widgets/js/widget_float.js

@@ -15,8 +15,10 b' define(['
         _range_regex: /^\s*([+-]?(?:\d*\.?\d+|\d+\.)(?:[eE][+-]?\d+)?)\s*[-:]\s*([+-]?(?:\d*\.?\d+|\d+\.)(?:[eE][+-]?\d+)?)/,
 
         _validate_slide_value: function(x) {
-            // Validate the value of the slider before sending it to the back-end
-            // and applying it to the other views on the page.
+            /**
+             * Validate the value of the slider before sending it to the back-end
+             * and applying it to the other views on the page.
+             */
             return x;
         },
     });

IPython/html/static/widgets/js/widget_image.js

@@ -8,16 +8,20 b' define(['
     
     var ImageView = widget.DOMWidgetView.extend({  
         render : function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.setElement($("<img />"));
             this.update(); // Set defaults.
         },
         
         update : function(){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             var image_src = 'data:image/' + this.model.get('format') + ';base64,' + this.model.get('_b64value');
             this.$el.attr('src', image_src);
             

IPython/html/static/widgets/js/widget_int.js

@@ -10,7 +10,9 b' define(['
     
     var IntSliderView = widget.DOMWidgetView.extend({
         render : function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.$el
                 .addClass('widget-hbox widget-slider');
             this.$label = $('<div />')
@@ -43,7 +45,9 b' define(['
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             if (name == 'color') {
                 this.$readout.css(name, value);
             } else if (name.substring(0, 4) == 'font') {
@@ -59,10 +63,12 b' define(['
         },
         
         update : function(options){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             if (options === undefined || options.updated_view != this) {
                 // JQuery slider option keys.  These keys happen to have a
                 // one-to-one mapping with the corrosponding keys of the model.
@@ -179,15 +185,17 b' define(['
         },
 
         handleTextChange: function() {
-            // this handles the entry of text into the contentEditable label
-            // first, the value is checked if it contains a parseable number
-            //      (or pair of numbers, for the _range case)
-            // then it is clamped within the min-max range of the slider
-            // finally, the model is updated if the value is to be changed
-            //
-            // if any of these conditions are not met, the text is reset
-            //
-            // the step size is not enforced
+            /**
+             * this handles the entry of text into the contentEditable label
+             * first, the value is checked if it contains a parseable number
+             *      (or pair of numbers, for the _range case)
+             * then it is clamped within the min-max range of the slider
+             * finally, the model is updated if the value is to be changed
+             *
+             * if any of these conditions are not met, the text is reset
+             *
+             * the step size is not enforced
+             */
 
             var text = this.$readout.text();
             var vmin = this.model.get('min');
@@ -245,10 +253,12 b' define(['
         _range_regex: /^\s*([+-]?\d+)\s*[-:]\s*([+-]?\d+)/,
 
         handleSliderChange: function(e, ui) { 
-            // Called when the slider value is changed.
-
-            // Calling model.set will trigger all of the other views of the 
-            // model to update.
+            /**
+             * Called when the slider value is changed.
+             *
+             * Calling model.set will trigger all of the other views of the 
+             * model to update.
+             */
             if (this.model.get("_range")) {
                 var actual_value = ui.values.map(this._validate_slide_value);
                 this.$readout.text(actual_value.join("-"));
@@ -261,10 +271,12 b' define(['
         },
 
         _validate_slide_value: function(x) {
-            // Validate the value of the slider before sending it to the back-end
-            // and applying it to the other views on the page.
-
-            // Double bit-wise not truncates the decimel (int cast).
+            /**
+             * Validate the value of the slider before sending it to the back-end
+             * and applying it to the other views on the page.
+             *
+             * Double bit-wise not truncates the decimel (int cast).
+             */
             return ~~x;
         },
     });
@@ -272,7 +284,9 b' define(['
 
     var IntTextView = widget.DOMWidgetView.extend({    
         render : function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.$el
                 .addClass('widget-hbox widget-text');
             this.$label = $('<div />')
@@ -287,10 +301,12 b' define(['
         },
         
         update : function(options){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             if (options === undefined || options.updated_view != this) {
                 var value = this.model.get('value');
                 if (this._parse_value(this.$textbox.val()) != value) {
@@ -316,7 +332,9 b' define(['
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             this.$textbox.css(name, value);
         },
 
@@ -331,9 +349,11 b' define(['
         }, 
         
         handleChanging: function(e) { 
-            // Handles and validates user input.
-            
-            // Try to parse value as a int.
+            /**
+             * Handles and validates user input.
+             *
+             * Try to parse value as a int.
+             */
             var numericalValue = 0;
             var trimmed = e.target.value.trim();
             if (trimmed === '') {
@@ -367,7 +387,9 b' define(['
         },
         
         handleChanged: function(e) {
-            // Applies validated input.
+            /**
+             * Applies validated input.
+             */
             if (e.target.value.trim() === '' || e.target.value !== this.model.get('value')) {
                 e.target.value = this.model.get('value');
             }
@@ -379,7 +401,9 b' define(['
 
     var ProgressView = widget.DOMWidgetView.extend({
         render : function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.$el
                 .addClass('widget-hbox widget-progress');
             this.$label = $('<div />')
@@ -403,10 +427,12 b' define(['
         },
         
         update : function(){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             var value = this.model.get('value');
             var max = this.model.get('max');
             var min = this.model.get('min');
@@ -435,7 +461,9 b' define(['
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             if (name.substring(0, 6) == 'border' || name == 'width' || 
                 name == 'height' || name == 'background' || name == 'margin' || 
                 name == 'padding') {

IPython/html/static/widgets/js/widget_output.js

@@ -10,13 +10,17 b' define(['
 
     var OutputView = widget.DOMWidgetView.extend({
         initialize: function (parameters) {
-            // Public constructor
+            /**
+             * Public constructor
+             */
             OutputView.__super__.initialize.apply(this, [parameters]);
             this.model.on('msg:custom', this._handle_route_msg, this);
         },
 
         render: function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.output_area = new outputarea.OutputArea({
                 selector: this.$el, 
                 prompt_area: false, 

IPython/html/static/widgets/js/widget_selection.js

@@ -10,7 +10,9 b' define(['
 
     var DropdownView = widget.DOMWidgetView.extend({
         render : function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.$el
                 .addClass('widget-hbox widget-dropdown');
             this.$label = $('<div />')
@@ -47,10 +49,12 b' define(['
         },
         
         update : function(options){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
 
             if (options === undefined || options.updated_view != this) {
                 var selected_item_text = this.model.get('value_name');
@@ -114,7 +118,9 b' define(['
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             if (name.substring(0, 6) == 'border' || name == 'background' || name == 'color') {
                 this.$droplabel.css(name, value);
                 this.$dropbutton.css(name, value);
@@ -137,10 +143,12 b' define(['
         },
 
         handle_click: function (e) {
-            // Handle when a value is clicked.
-            
-            // Calling model.set will trigger all of the other views of the 
-            // model to update.
+            /**
+             * Handle when a value is clicked.
+             *
+             * Calling model.set will trigger all of the other views of the 
+             * model to update.
+             */
             this.model.set('value_name', $(e.target).text(), {updated_view: this});
             this.touch();
         },
@@ -150,7 +158,9 b' define(['
 
     var RadioButtonsView = widget.DOMWidgetView.extend({    
         render : function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.$el
                 .addClass('widget-hbox widget-radio');
             this.$label = $('<div />')
@@ -164,10 +174,12 b' define(['
         },
         
         update : function(options){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             if (options === undefined || options.updated_view != this) {
                 // Add missing items to the DOM.
                 var items = this.model.get('value_names');
@@ -227,15 +239,19 b' define(['
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             this.$container.css(name, value);
         },
 
         handle_click: function (e) {
-            // Handle when a value is clicked.
-            
-            // Calling model.set will trigger all of the other views of the 
-            // model to update.
+            /**
+             * Handle when a value is clicked.
+             *
+             * Calling model.set will trigger all of the other views of the 
+             * model to update.
+             */
             this.model.set('value_name', $(e.target).val(), {updated_view: this});
             this.touch();
         },
@@ -249,7 +265,9 b' define(['
         },
 
         render: function() {
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.$el
                 .addClass('widget-hbox widget-toggle-buttons');
             this.$label = $('<div />')
@@ -269,10 +287,12 b' define(['
         },
         
         update : function(options){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             if (options === undefined || options.updated_view != this) {
                 // Add missing items to the DOM.
                 var items = this.model.get('value_names');
@@ -334,7 +354,9 b' define(['
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             this._css_state[name] = value;
             this.update_style_traits();
         },
@@ -367,10 +389,12 b' define(['
         },
 
         handle_click: function (e) {
-            // Handle when a value is clicked.
-            
-            // Calling model.set will trigger all of the other views of the 
-            // model to update.
+            /**
+             * Handle when a value is clicked.
+             *
+             * Calling model.set will trigger all of the other views of the 
+             * model to update.
+             */
             this.model.set('value_name', $(e.target).data('value'), {updated_view: this});
             this.touch();
         },    
@@ -379,7 +403,9 b' define(['
 
     var SelectView = widget.DOMWidgetView.extend({    
         render : function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.$el
                 .addClass('widget-hbox widget-select');
             this.$label = $('<div />')
@@ -394,10 +420,12 b' define(['
         },
         
         update : function(options){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             if (options === undefined || options.updated_view != this) {
                 // Add missing items to the DOM.
                 var items = this.model.get('value_names');
@@ -449,15 +477,19 b' define(['
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             this.$listbox.css(name, value);
         },
 
         handle_click: function (e) {
-            // Handle when a value is clicked.
-            
-            // Calling model.set will trigger all of the other views of the 
-            // model to update.
+            /**
+             * Handle when a value is clicked.
+             *
+             * Calling model.set will trigger all of the other views of the 
+             * model to update.
+             */
             this.model.set('value_name', $(e.target).text(), {updated_view: this});
             this.touch();
         },    

IPython/html/static/widgets/js/widget_selectioncontainer.js

@@ -21,7 +21,9 b' define(['
         },
 
         render: function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             var guid = 'panel-group' + utils.uuid();
             this.$el
                 .attr('id', guid)
@@ -40,7 +42,9 b' define(['
         },
 
         update_titles: function(titles) {
-            // Set tab titles
+            /**
+             * Set tab titles
+             */
             if (!titles) {
                 titles = this.model.get('_titles');
             }
@@ -58,8 +62,10 b' define(['
         },
 
         update_selected_index: function(old_index, new_index, options) {
-            // Only update the selection if the selection wasn't triggered
-            // by the front-end.  It must be triggered by the back-end.
+            /**
+             * Only update the selection if the selection wasn't triggered
+             * by the front-end.  It must be triggered by the back-end.
+             */
             if (options === undefined || options.updated_view != this) {
                 this.containers[old_index].find('.panel-collapse').collapse('hide');
                 if (0 <= new_index && new_index < this.containers.length) {
@@ -69,8 +75,10 b' define(['
         },
 
         remove_child_view: function(view) {
-            // Called when a child is removed from children list.
-            // TODO: does this handle two different views of the same model as children?
+            /**
+             * Called when a child is removed from children list.
+             * TODO: does this handle two different views of the same model as children?
+             */
             var model = view.model;
             var accordion_group = this.model_containers[model.id];
             this.containers.splice(accordion_group.container_index, 1);
@@ -79,7 +87,9 b' define(['
         },
 
         add_child_view: function(model) {
-            // Called when a child is added to children list.
+            /**
+             * Called when a child is added to children list.
+             */
             var index = this.containers.length;
             var uuid = utils.uuid();
             var accordion_group = $('<div />')
@@ -129,9 +139,11 b' define(['
         },
         
         remove: function() {
-            // We remove this widget before removing the children as an optimization
-            // we want to remove the entire container from the DOM first before
-            // removing each individual child separately.
+            /**
+             * We remove this widget before removing the children as an optimization
+             * we want to remove the entire container from the DOM first before
+             * removing each individual child separately.
+             */
             AccordionView.__super__.remove.apply(this, arguments);
             this.children_views.remove();
         },
@@ -140,7 +152,9 b' define(['
 
     var TabView = widget.DOMWidgetView.extend({    
         initialize: function() {
-            // Public constructor.
+            /**
+             * Public constructor.
+             */
             TabView.__super__.initialize.apply(this, arguments);
             
             this.containers = [];
@@ -151,7 +165,9 b' define(['
         },
 
         render: function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             var uuid = 'tabs'+utils.uuid();
             var that = this;
             this.$tabs = $('<div />', {id: uuid})
@@ -165,12 +181,16 b' define(['
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             this.$tabs.css(name, value);
         },
 
         remove_child_view: function(view) {
-            // Called when a child is removed from children list.
+            /**
+             * Called when a child is removed from children list.
+             */
             this.containers.splice(view.parent_tab.tab_text_index, 1);
             view.parent_tab.remove();
             view.parent_container.remove();
@@ -178,7 +198,9 b' define(['
         },
 
         add_child_view: function(model) {
-            // Called when a child is added to children list.
+            /**
+             * Called when a child is added to children list.
+             */
             var index = this.containers.length;
             var uuid = utils.uuid();
 
@@ -224,10 +246,12 b' define(['
         },
 
         update: function(options) {
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             if (options === undefined || options.updated_view != this) {
                 // Set tab titles
                 var titles = this.model.get('_titles');
@@ -248,16 +272,20 b' define(['
         },
 
         select_page: function(index) {
-            // Select a page.
+            /**
+             * Select a page.
+             */
             this.$tabs.find('li')
                 .removeClass('active');
             this.containers[index].tab('show');
         },
         
         remove: function() {
-            // We remove this widget before removing the children as an optimization
-            // we want to remove the entire container from the DOM first before
-            // removing each individual child separately.
+            /**
+             * We remove this widget before removing the children as an optimization
+             * we want to remove the entire container from the DOM first before
+             * removing each individual child separately.
+             */
             TabView.__super__.remove.apply(this, arguments);
             this.children_views.remove();
         },

IPython/html/static/widgets/js/widget_string.js

@@ -9,15 +9,19 b' define(['
 
     var HTMLView = widget.DOMWidgetView.extend({  
         render : function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.update(); // Set defaults.
         },
         
         update : function(){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             this.$el.html(this.model.get('value')); // CAUTION! .html(...) CALL MANDITORY!!!
             return HTMLView.__super__.update.apply(this);
         },
@@ -26,15 +30,19 b' define(['
 
     var LatexView = widget.DOMWidgetView.extend({  
         render : function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.update(); // Set defaults.
         },
         
         update : function(){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             this.$el.text(this.model.get('value'));
             MathJax.Hub.Queue(["Typeset",MathJax.Hub,this.$el.get(0)]);
 
@@ -45,7 +53,9 b' define(['
 
     var TextareaView = widget.DOMWidgetView.extend({  
         render: function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.$el
                 .addClass('widget-hbox widget-textarea');
             this.$label = $('<div />')
@@ -67,7 +77,9 b' define(['
         },
 
         _handle_textarea_msg: function (content){
-            // Handle when a custom msg is recieved from the back-end.
+            /**
+             * Handle when a custom msg is recieved from the back-end.
+             */
             if (content.method == "scroll_to_bottom") {
                 this.scroll_to_bottom();                
             }
@@ -81,15 +93,19 b' define(['
         },
 
         scroll_to_bottom: function (){
-            // Scroll the text-area view to the bottom.
+            /**
+             * Scroll the text-area view to the bottom.
+             */
             this.$textbox.scrollTop(this.$textbox[0].scrollHeight);
         },
 
         update: function(options){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             if (options === undefined || options.updated_view != this) {
                 this.$textbox.val(this.model.get('value'));
 
@@ -109,7 +125,9 b' define(['
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             this.$textbox.css(name, value);
         },
         
@@ -121,10 +139,12 b' define(['
         },
         
         handleChanging: function(e) { 
-            // Handles and validates user input.
-            
-            // Calling model.set will trigger all of the other views of the 
-            // model to update.
+            /**
+             * Handles and validates user input.
+             *
+             * Calling model.set will trigger all of the other views of the 
+             * model to update.
+             */
             this.model.set('value', e.target.value, {updated_view: this});
             this.touch();
         },
@@ -133,7 +153,9 b' define(['
 
     var TextView = widget.DOMWidgetView.extend({  
         render: function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             this.$el
                 .addClass('widget-hbox widget-text');
             this.$label = $('<div />')
@@ -160,10 +182,12 b' define(['
         },
         
         update: function(options){
-            // Update the contents of this view
-            //
-            // Called when the model is changed.  The model may have been 
-            // changed by another view or by a state update from the back-end.
+            /**
+             * Update the contents of this view
+             *
+             * Called when the model is changed.  The model may have been 
+             * changed by another view or by a state update from the back-end.
+             */
             if (options === undefined || options.updated_view != this) {
                 if (this.$textbox.val() != this.model.get('value')) {
                     this.$textbox.val(this.model.get('value'));
@@ -185,7 +209,9 b' define(['
         },
 
         update_attr: function(name, value) {
-            // Set a css attr of the widget view.
+            /**
+             * Set a css attr of the widget view.
+             */
             this.$textbox.css(name, value);
         },
         
@@ -200,16 +226,20 b' define(['
         },
         
         handleChanging: function(e) { 
-            // Handles user input.
-
-            // Calling model.set will trigger all of the other views of the 
-            // model to update.
+            /**
+             * Handles user input.
+             *
+             * Calling model.set will trigger all of the other views of the 
+             * model to update.
+             */
             this.model.set('value', e.target.value, {updated_view: this});
             this.touch();
         },
         
         handleKeypress: function(e) { 
-            // Handles text submition
+            /**
+             * Handles text submition
+             */
             if (e.keyCode == 13) { // Return key
                 this.send({event: 'submit'});
                 e.stopPropagation();
@@ -219,10 +249,12 b' define(['
         },
 
         handleBlur: function(e) { 
-            // Prevent a blur from firing if the blur was not user intended.
-            // This is a workaround for the return-key focus loss bug.
-            // TODO: Is the original bug actually a fault of the keyboard
-            // manager?
+            /**
+             * Prevent a blur from firing if the blur was not user intended.
+             * This is a workaround for the return-key focus loss bug.
+             * TODO: Is the original bug actually a fault of the keyboard
+             * manager?
+             */
             if (e.relatedTarget === null) {
                 e.stopPropagation();
                 e.preventDefault();
@@ -231,8 +263,10 b' define(['
         },
 
         handleFocusOut: function(e) { 
-            // Prevent a blur from firing if the blur was not user intended.
-            // This is a workaround for the return-key focus loss bug.
+            /**
+             * Prevent a blur from firing if the blur was not user intended.
+             * This is a workaround for the return-key focus loss bug.
+             */
             if (e.relatedTarget === null) {
                 e.stopPropagation();
                 e.preventDefault();