Ran function comment conversion tool

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

@@ -1,174 +1,178 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'codemirror/lib/codemirror',
 ], function(IPython, $, CodeMirror) {
     "use strict";
     
     var modal = function (options) {
 
         var modal = $("<div/>")
             .addClass("modal")
             .addClass("fade")
             .attr("role", "dialog");
         var dialog = $("<div/>")
             .addClass("modal-dialog")
             .appendTo(modal);
         var dialog_content = $("<div/>")
             .addClass("modal-content")
             .appendTo(dialog);
         dialog_content.append(
             $("<div/>")
                 .addClass("modal-header")
                 .append($("<button>")
                     .attr("type", "button")
                     .addClass("close")
                     .attr("data-dismiss", "modal")
                     .attr("aria-hidden", "true")
                     .html("&times;")
                 ).append(
                     $("<h4/>")
                         .addClass('modal-title')
                         .text(options.title || "")
                 )
         ).append(
             $("<div/>").addClass("modal-body").append(
                 options.body || $("<p/>")
             )
         );
         
         var footer = $("<div/>").addClass("modal-footer");
         
         for (var label in options.buttons) {
             var btn_opts = options.buttons[label];
             var button = $("<button/>")
                 .addClass("btn btn-default btn-sm")
                 .attr("data-dismiss", "modal")
                 .text(label);
             if (btn_opts.click) {
                 button.click($.proxy(btn_opts.click, dialog_content));
             }
             if (btn_opts.class) {
                 button.addClass(btn_opts.class);
             }
             footer.append(button);
         }
         dialog_content.append(footer);
         // hook up on-open event
         modal.on("shown.bs.modal", function() {
             setTimeout(function() {
                 footer.find("button").last().focus();
                 if (options.open) {
                     $.proxy(options.open, modal)();
                 }
             }, 0);
         });
         
         // destroy modal on hide, unless explicitly asked not to
         if (options.destroy === undefined || options.destroy) {
             modal.on("hidden.bs.modal", function () {
                 modal.remove();
             });
         }
         modal.on("hidden.bs.modal", function () {
             if (options.notebook) {
                 var cell = options.notebook.get_selected_cell();
                 if (cell) cell.select();
             }
             if (options.keyboard_manager) {
                 options.keyboard_manager.enable();
                 options.keyboard_manager.command_mode();
             }
         });
         
         if (options.keyboard_manager) {
             options.keyboard_manager.disable();
         }
         
         return modal.modal(options);
     };
 
     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');
         return dialog;
     };
 
     var edit_metadata = function (options) {
         options.name = options.name || "Cell";
         var error_div = $('<div/>').css('color', 'red');
         var message = 
             "Manually edit the JSON below to manipulate the metadata for this " + options.name + "." +
             " We recommend putting custom metadata attributes in an appropriately named sub-structure," +
             " so they don't conflict with those of others.";
 
         var textarea = $('<textarea/>')
             .attr('rows', '13')
             .attr('cols', '80')
             .attr('name', 'metadata')
             .text(JSON.stringify(options.md || {}, null, 2));
         
         var dialogform = $('<div/>').attr('title', 'Edit the metadata')
             .append(
                 $('<form/>').append(
                     $('<fieldset/>').append(
                         $('<label/>')
                         .attr('for','metadata')
                         .text(message)
                         )
                         .append(error_div)
                         .append($('<br/>'))
                         .append(textarea)
                     )
             );
         var editor = CodeMirror.fromTextArea(textarea[0], {
             lineNumbers: true,
             matchBrackets: true,
             indentUnit: 2,
             autoIndent: true,
             mode: 'application/json',
         });
         var modal_obj = modal({
             title: "Edit " + options.name + " Metadata",
             body: dialogform,
             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());
                         } catch(e) {
                             console.log(e);
                             error_div.text('WARNING: Could not save invalid JSON.');
                             return false;
                         }
                         options.callback(new_md);
                     }
                 },
                 Cancel: {}
             },
             notebook: options.notebook,
             keyboard_manager: options.keyboard_manager,
         });
 
         modal_obj.on('shown.bs.modal', function(){ editor.refresh(); });
     };
     
     var dialog = {
         modal : modal,
         kernel_modal : kernel_modal,
         edit_metadata : edit_metadata,
     };
 
     // Backwards compatability.
     IPython.dialog = dialog;
 
     return dialog;
 });

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

@@ -1,41 +1,47 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
 ], function(IPython, $){
     "use strict";
 
     var Page = function () {
         this.bind_events();
     };
 
     Page.prototype.bind_events = function () {
     };
 
     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');
     };
 
     // Register self in the global namespace for convenience.
     IPython.Page = Page;
     return {'Page': Page};
 });

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

@@ -1,121 +1,129 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'components/google-caja/html-css-sanitizer-minified',
 ], function(IPython, $) {
     "use strict";
     
     var noop = function (x) { return x; };
     
     var caja;
     if (window && window.html) {
         caja = window.html;
         caja.html4 = window.html4;
         caja.sanitizeStylesheet = window.sanitizeStylesheet;
     }
     
     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];
             if (attribName.substr(0,5) == 'data-') {
                 var attribKey = '*::' + attribName;
                 if (!ATTRIBS.hasOwnProperty(attribKey)) {
                     ATTRIBS[attribKey] = 0;
                 }
             }
         }
         return caja.sanitizeAttribs(tagName, attribs, opt_naiveUriRewriter, opt_nmTokenPolicy, opt_logger);
     };
     
     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,
             {
                 containerClass: null,
                 idSuffix: '',
                 tagPolicy: tagPolicy,
                 virtualizeAttrName: noop
             },
             noop
         );
     };
     
     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) {
             // no style tags to sanitize
             return html;
         }
         style_tags.each(function(i, style) {
             style.innerHTML = sanitize_css(style.innerHTML, tagPolicy);
         });
         return h.html();
     };
     
     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) {
             // allow sanitization of style tags,
             // not just scrubbing
             html4.ELEMENTS.style &= ~html4.eflags.UNSAFE;
             html4.ATTRIBS.style = html4.atype.STYLE;
         } else {
             // scrub all CSS
             html4.ELEMENTS.style |= html4.eflags.UNSAFE;
             html4.ATTRIBS.style = html4.atype.SCRIPT;
         }
         
         var record_messages = function (msg, opts) {
             console.log("HTML Sanitizer", msg, opts);
         };
         
         var policy = function (tagName, attribs) {
             if (!(html4.ELEMENTS[tagName] & html4.eflags.UNSAFE)) {
                 return {
                     'attribs': sanitizeAttribs(tagName, attribs,
                         noop, noop, record_messages)
                     };
             } else {
                 record_messages(tagName + " removed", {
                   change: "removed",
                   tagName: tagName
                 });
             }
         };
         
         var sanitized = caja.sanitizeWithPolicy(html, policy);
         
         if (allow_css) {
             // sanitize style tags as stylesheets
             sanitized = sanitize_stylesheets(result.sanitized, policy);
         }
         
         return sanitized;
     };
     
     var security = {
         caja: caja,
         sanitize_html: sanitize_html
     };
 
     IPython.security = security;
 
     return security;
 });

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

@@ -1,760 +1,810 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'codemirror/lib/codemirror',
 ], function(IPython, $, CodeMirror){
     "use strict";
     
     IPython.load_extensions = function () {
         // load one or more IPython notebook extensions with requirejs
         
         var extensions = [];
         var extension_names = arguments;
         for (var i = 0; i < extension_names.length; i++) {
             extensions.push("nbextensions/" + arguments[i]);
         }
         
         require(extensions,
             function () {
                 for (var i = 0; i < arguments.length; i++) {
                     var ext = arguments[i];
                     var ext_name = extension_names[i];
                     // success callback
                     console.log("Loaded extension: " + ext_name);
                     if (ext && ext.load_ipython_extension !== undefined) {
                         ext.load_ipython_extension();
                     }
                 }
             },
             function (err) {
                 // failure callback
                 console.log("Failed to load extension(s):", err.requireModules, err);
             }
         );
     };
 
     //============================================================================
     // Cross-browser RegEx Split
     //============================================================================
 
     // This code has been MODIFIED from the code licensed below to not replace the
     // default browser split.  The license is reproduced here.
 
     // see http://blog.stevenlevithan.com/archives/cross-browser-split for more info:
     /*!
      * Cross-Browser Split 1.1.1
      * Copyright 2007-2012 Steven Levithan <stevenlevithan.com>
      * Available under the MIT License
      * ECMAScript compliant, uniform cross-browser split method
      */
 
     /**
      * Splits a string into an array of strings using a regex or string
      * separator. Matches of the separator are not included in the result array.
      * However, if `separator` is a regex that contains capturing groups,
      * backreferences are spliced into the result each time `separator` is
      * matched. Fixes browser bugs compared to the native
      * `String.prototype.split` and can be used reliably cross-browser.
      * @param {String} str String to split.
      * @param {RegExp|String} separator Regex or string to use for separating
      *     the string.
      * @param {Number} [limit] Maximum number of items to include in the result
      *     array.
      * @returns {Array} Array of substrings.
      * @example
      *
      * // Basic use
      * regex_split('a b c d', ' ');
      * // -> ['a', 'b', 'c', 'd']
      *
      * // With limit
      * regex_split('a b c d', ' ', 2);
      * // -> ['a', 'b']
      *
      * // Backreferences in result array
      * regex_split('..word1 word2..', /([a-z]+)(\d+)/i);
      * // -> ['..', 'word', '1', ' ', 'word', '2', '..']
      */
     var regex_split = function (str, separator, limit) {
-        // If `separator` is not a regex, use `split`
+        /**
+         * If `separator` is not a regex, use `split`
+         */
         if (Object.prototype.toString.call(separator) !== "[object RegExp]") {
             return split.call(str, separator, limit);
         }
         var output = [],
             flags = (separator.ignoreCase ? "i" : "") +
                     (separator.multiline  ? "m" : "") +
                     (separator.extended   ? "x" : "") + // Proposed for ES6
                     (separator.sticky     ? "y" : ""), // Firefox 3+
             lastLastIndex = 0,
             // Make `global` and avoid `lastIndex` issues by working with a copy
             separator = new RegExp(separator.source, flags + "g"),
             separator2, match, lastIndex, lastLength;
         str += ""; // Type-convert
 
         var compliantExecNpcg = typeof(/()??/.exec("")[1]) === "undefined";
         if (!compliantExecNpcg) {
             // Doesn't need flags gy, but they don't hurt
             separator2 = new RegExp("^" + separator.source + "$(?!\\s)", flags);
         }
         /* Values for `limit`, per the spec:
          * If undefined: 4294967295 // Math.pow(2, 32) - 1
          * If 0, Infinity, or NaN: 0
          * If positive number: limit = Math.floor(limit); if (limit > 4294967295) limit -= 4294967296;
          * If negative number: 4294967296 - Math.floor(Math.abs(limit))
          * If other: Type-convert, then use the above rules
          */
         limit = typeof(limit) === "undefined" ?
             -1 >>> 0 : // Math.pow(2, 32) - 1
             limit >>> 0; // ToUint32(limit)
         while (match = separator.exec(str)) {
             // `separator.lastIndex` is not reliable cross-browser
             lastIndex = match.index + match[0].length;
             if (lastIndex > lastLastIndex) {
                 output.push(str.slice(lastLastIndex, match.index));
                 // Fix browsers whose `exec` methods don't consistently return `undefined` for
                 // nonparticipating capturing groups
                 if (!compliantExecNpcg && match.length > 1) {
                     match[0].replace(separator2, function () {
                         for (var i = 1; i < arguments.length - 2; i++) {
                             if (typeof(arguments[i]) === "undefined") {
                                 match[i] = undefined;
                             }
                         }
                     });
                 }
                 if (match.length > 1 && match.index < str.length) {
                     Array.prototype.push.apply(output, match.slice(1));
                 }
                 lastLength = match[0].length;
                 lastLastIndex = lastIndex;
                 if (output.length >= limit) {
                     break;
                 }
             }
             if (separator.lastIndex === match.index) {
                 separator.lastIndex++; // Avoid an infinite loop
             }
         }
         if (lastLastIndex === str.length) {
             if (lastLength || !separator.test("")) {
                 output.push("");
             }
         } else {
             output.push(str.slice(lastLastIndex));
         }
         return output.length > limit ? output.slice(0, limit) : output;
     };
 
     //============================================================================
     // End contributed Cross-browser RegEx Split
     //============================================================================
 
 
     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++) {
             s[i] = hexDigits.substr(Math.floor(Math.random() * 0x10), 1);
         }
         s[12] = "4";  // bits 12-15 of the time_hi_and_version field to 0010
         s[16] = hexDigits.substr((s[16] & 0x3) | 0x8, 1);  // bits 6-7 of the clock_seq_hi_and_reserved to 01
 
         var uuid = s.join("");
         return uuid;
     };
 
 
     //Fix raw text to parse correctly in crazy XML
     function xmlencode(string) {
         return string.replace(/\&/g,'&'+'amp;')
             .replace(/</g,'&'+'lt;')
             .replace(/>/g,'&'+'gt;')
             .replace(/\'/g,'&'+'apos;')
             .replace(/\"/g,'&'+'quot;')
             .replace(/`/g,'&'+'#96;');
     }
 
 
     //Map from terminal commands to CSS classes
     var ansi_colormap = {
         "01":"ansibold",
         
         "30":"ansiblack",
         "31":"ansired",
         "32":"ansigreen",
         "33":"ansiyellow",
         "34":"ansiblue",
         "35":"ansipurple",
         "36":"ansicyan",
         "37":"ansigray",
         
         "40":"ansibgblack",
         "41":"ansibgred",
         "42":"ansibggreen",
         "43":"ansibgyellow",
         "44":"ansibgblue",
         "45":"ansibgpurple",
         "46":"ansibgcyan",
         "47":"ansibggray"
     };
     
     function _process_numbers(attrs, numbers) {
         // process ansi escapes
         var n = numbers.shift();
         if (ansi_colormap[n]) {
             if ( ! attrs["class"] ) {
                 attrs["class"] = ansi_colormap[n];
             } else {
                 attrs["class"] += " " + ansi_colormap[n];
             }
         } else if (n == "38" || n == "48") {
             // VT100 256 color or 24 bit RGB
             if (numbers.length < 2) {
                 console.log("Not enough fields for VT100 color", numbers);
                 return;
             }
             
             var index_or_rgb = numbers.shift();
             var r,g,b;
             if (index_or_rgb == "5") {
                 // 256 color
                 var idx = parseInt(numbers.shift());
                 if (idx < 16) {
                     // indexed ANSI
                     // ignore bright / non-bright distinction
                     idx = idx % 8;
                     var ansiclass = ansi_colormap[n[0] + (idx % 8).toString()];
                     if ( ! attrs["class"] ) {
                         attrs["class"] = ansiclass;
                     } else {
                         attrs["class"] += " " + ansiclass;
                     }
                     return;
                 } else if (idx < 232) {
                     // 216 color 6x6x6 RGB
                     idx = idx - 16;
                     b = idx % 6;
                     g = Math.floor(idx / 6) % 6;
                     r = Math.floor(idx / 36) % 6;
                     // convert to rgb
                     r = (r * 51);
                     g = (g * 51);
                     b = (b * 51);
                 } else {
                     // grayscale
                     idx = idx - 231;
                     // it's 1-24 and should *not* include black or white,
                     // so a 26 point scale
                     r = g = b = Math.floor(idx * 256 / 26);
                 }
             } else if (index_or_rgb == "2") {
                 // Simple 24 bit RGB
                 if (numbers.length > 3) {
                     console.log("Not enough fields for RGB", numbers);
                     return;
                 }
                 r = numbers.shift();
                 g = numbers.shift();
                 b = numbers.shift();
             } else {
                 console.log("unrecognized control", numbers);
                 return;
             }
             if (r !== undefined) {
                 // apply the rgb color
                 var line;
                 if (n == "38") {
                     line = "color: ";
                 } else {
                     line = "background-color: ";
                 }
                 line = line + "rgb(" + r + "," + g + "," + b + ");";
                 if ( !attrs.style ) {
                     attrs.style = line;
                 } else {
                     attrs.style += " " + line;
                 }
             }
         }
     }
 
     function ansispan(str) {
         // ansispan function adapted from github.com/mmalecki/ansispan (MIT License)
         // regular ansi escapes (using the table above)
         var is_open = false;
         return str.replace(/\033\[(0?[01]|22|39)?([;\d]+)?m/g, function(match, prefix, pattern) {
             if (!pattern) {
                 // [(01|22|39|)m close spans
                 if (is_open) {
                     is_open = false;
                     return "</span>";
                 } else {
                     return "";
                 }
             } else {
                 is_open = true;
 
                 // consume sequence of color escapes
                 var numbers = pattern.match(/\d+/g);
                 var attrs = {};
                 while (numbers.length > 0) {
                     _process_numbers(attrs, numbers);
                 }
 
                 var span = "<span ";
                 for (var attr in attrs) {
                     var value = attrs[attr];
                     span = span + " " + attr + '="' + attrs[attr] + '"';
                 }
                 return span + ">";
             }
         });
     }
 
     // Transform ANSI color escape codes into HTML <span> tags with css
     // classes listed in the above ansi_colormap object. The actual color used
     // are set in the css file.
     function fixConsole(txt) {
         txt = xmlencode(txt);
         var re = /\033\[([\dA-Fa-f;]*?)m/;
         var opened = false;
         var cmds = [];
         var opener = "";
         var closer = "";
 
         // Strip all ANSI codes that are not color related.  Matches
         // all ANSI codes that do not end with "m".
         var ignored_re = /(?=(\033\[[\d;=]*[a-ln-zA-Z]{1}))\1(?!m)/g;
         txt = txt.replace(ignored_re, "");
         
         // color ansi codes
         txt = ansispan(txt);
         return txt;
     }
 
     // Remove chunks that should be overridden by the effect of
     // carriage return characters
     function fixCarriageReturn(txt) {
         var tmp = txt;
         do {
             txt = tmp;
             tmp = txt.replace(/\r+\n/gm, '\n'); // \r followed by \n --> newline
             tmp = tmp.replace(/^.*\r+/gm, '');  // Other \r --> clear line
         } while (tmp.length < txt.length);
         return txt;
     }
 
     // Locate any URLs and convert them to a anchor tag
     function autoLinkUrls(txt) {
         return txt.replace(/(^|\s)(https?|ftp)(:[^'">\s]+)/gi,
             "$1<a target=\"_blank\" href=\"$2$3\">$2$3</a>");
     }
 
     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;
         test.remove();
         return Math.floor(points*pixel_per_point);
     };
     
     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);
             return obj;
         };
     };
 
     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] === '') {
                 continue;
             }
             if (url.length > 0 && url[url.length-1] != '/') {
                 url = url + '/' + arguments[i];
             } else {
                 url = url + arguments[i];
             }
         }
         url = url.replace(/\/\/+/, '/');
         return url;
     };
     
     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) {
             return ['', path];
         } else {
             return [ path.slice(0, idx), path.slice(idx + 1) ];
         }
     };
     
     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)];
         } else {
             return [filename, ''];
         }
     };
 
 
     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();
         }
         var cursor_pos = cursor.ch;
         for (var i = 0; i < cursor.line; i++) {
             cursor_pos += cm.getLine(i).length + 1;
         }
         return cursor_pos;
     };
     
     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)) {
             if (offset + line.length < cursor_pos) {
                 offset += line.length + 1;
             } else {
                 return {
                     line : i,
                     ch : cursor_pos - offset,
                 };
             }
         }
         // reached end, return endpoint
         return {
             ch : line.length - 1,
             line : i - 1,
         };
     };
     
     // http://stackoverflow.com/questions/2400935/browser-detection-in-javascript
     var browser = (function() {
         if (typeof navigator === 'undefined') {
             // navigator undefined in node
             return 'None';
         }
         var N= navigator.appName, ua= navigator.userAgent, tem;
         var M= ua.match(/(opera|chrome|safari|firefox|msie)\/?\s*(\.?\d+(\.\d+)*)/i);
         if (M && (tem= ua.match(/version\/([\.\d]+)/i)) !== null) M[2]= tem[1];
         M= M? [M[1], M[2]]: [N, navigator.appVersion,'-?'];
         return M;
     })();
 
     // http://stackoverflow.com/questions/11219582/how-to-detect-my-browser-version-and-operating-system-using-javascript
     var platform = (function () {
         if (typeof navigator === 'undefined') {
             // navigator undefined in node
             return 'None';
         }
         var OSName="None";
         if (navigator.appVersion.indexOf("Win")!=-1) OSName="Windows";
         if (navigator.appVersion.indexOf("Mac")!=-1) OSName="MacOS";
         if (navigator.appVersion.indexOf("X11")!=-1) OSName="UNIX";
         if (navigator.appVersion.indexOf("Linux")!=-1) OSName="Linux";
         return OSName;
     })();
 
     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) {
             if (is_or_has(e, target)) {
                 return true;
             } else {
                 return false;
             }
         } else {
             return false;
         }
     };
     
     var mergeopt = function(_class, options, overwrite){
         options = options || {};
         overwrite = overwrite || {};
         return $.extend(true, {}, _class.options_default, options, overwrite);
     };
     
     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) {
             return jqXHR.responseJSON.message;
         } else {
             return jqXHR.statusText;
         }
     };
     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);
         console.log(msg);
     };
     
     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);
             return;
         }
         require([
                 // might want to use CodeMirror.modeURL here
                 ['codemirror/mode', mode, mode].join('/'),
             ], callback, errback
         );
     };
     
     /** Error type for wrapped XHR errors. */
     var XHR_ERROR = 'XhrError';
     
     /**
      * Wraps an AJAX error as an Error object.
      */
     var wrap_ajax_error = function (jqXHR, status, error) {
         var wrapped_error = new Error(ajax_error_msg(jqXHR));
         wrapped_error.name =  XHR_ERROR;
         // provide xhr response
         wrapped_error.xhr = jqXHR;
         wrapped_error.xhr_status = status;
         wrapped_error.xhr_error = error;
         return wrapped_error;
     };
     
     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);
             };
             settings.error = function(jqXHR, status, error) {
                 log_ajax_error(jqXHR, status, error);
                 reject(wrap_ajax_error(jqXHR, status, error));
             };
             $.ajax(url, settings);
         });
     };
 
     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.
         var properties = Object.getOwnPropertyNames(tmp);
         for (var i = 0; i < properties.length; i++) {
             this[properties[i]] = tmp[properties[i]];
         }
 
         // Keep a stack of the original error messages.
         if (error instanceof WrappedError) {
             this.error_stack = error.error_stack;
         } else {
             this.error_stack = [error];
         }
         this.error_stack.push(tmp);
 
         return this;
     };
 
     WrappedError.prototype = Object.create(Error.prototype, {});
 
 
     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
             if (module_name) {
                 require([module_name], function(module) {
                     if (module[class_name] === undefined) {
                         reject(new Error('Class '+class_name+' not found in module '+module_name));
                     } else {
                         resolve(module[class_name]);
                     }
                 }, reject);
             } else {
                 if (registry && registry[class_name]) {
                     resolve(registry[class_name]);
                 } else {
                     reject(new Error('Class '+class_name+' not found in registry '));
                 }
             }
         });
     };
 
     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) {
             values.push(d[key]);
         });
         return Promise.all(values).then(function(v) {
             d = {};
             for(var i=0; i<keys.length; i++) {
                 d[keys[i]] = v[i];
             }
             return d;
         });
     };
 
     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.
         var properties = Object.getOwnPropertyNames(tmp);
         for (var i = 0; i < properties.length; i++) {
             this[properties[i]] = tmp[properties[i]];
         }
 
         // Keep a stack of the original error messages.
         if (error instanceof WrappedError) {
             this.error_stack = error.error_stack;
         } else {
             this.error_stack = [error];
         }
         this.error_stack.push(tmp);
 
         return this;
     };
 
     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); 
             return Promise.reject(wrapped_error); 
         };
     };
 
     var utils = {
         regex_split : regex_split,
         uuid : uuid,
         fixConsole : fixConsole,
         fixCarriageReturn : fixCarriageReturn,
         autoLinkUrls : autoLinkUrls,
         points_to_pixels : points_to_pixels,
         get_body_data : get_body_data,
         parse_url : parse_url,
         url_path_split : url_path_split,
         url_path_join : url_path_join,
         url_join_encode : url_join_encode,
         encode_uri_components : encode_uri_components,
         splitext : splitext,
         escape_html : escape_html,
         always_new : always_new,
         to_absolute_cursor_pos : to_absolute_cursor_pos,
         from_absolute_cursor_pos : from_absolute_cursor_pos,
         browser : browser,
         platform: platform,
         is_or_has : is_or_has,
         is_focused : is_focused,
         mergeopt: mergeopt,
         ajax_error_msg : ajax_error_msg,
         log_ajax_error : log_ajax_error,
         requireCodeMirrorMode : requireCodeMirrorMode,
         XHR_ERROR : XHR_ERROR,
         wrap_ajax_error : wrap_ajax_error,
         promising_ajax : promising_ajax,
         WrappedError: WrappedError,
         load_class: load_class,
         resolve_promises_dict: resolve_promises_dict,
         reject: reject,
     };
 
     // Backwards compatability.
     IPython.utils = utils;
     
     return utils;
 }); 

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

@@ -1,46 +1,50 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
     'bootstrap',
 ], function(IPython, $, utils, bootstrap) {
     "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;
         this.editor = options.editor;
 
         if (this.selector !== undefined) {
             this.element = $(selector);
             this.bind_events();
         }
     };
 
     MenuBar.prototype.bind_events = function () {
-        //  File
+        /**
+         *  File
+         */
         var that = this;
         this.element.find('#save_file').click(function () {
             that.editor.save();
         });
     };
 
     return {'MenuBar': MenuBar};
 });

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

@@ -1,675 +1,681 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 /**
  *
  *
  * @module cell
  * @namespace cell
  * @class Cell
  */
 
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
     'codemirror/lib/codemirror',
     'codemirror/addon/edit/matchbrackets',
     'codemirror/addon/edit/closebrackets',
     'codemirror/addon/comment/comment'
 ], function(IPython, $, utils, CodeMirror, cm_match, cm_closeb, cm_comment) {
     // TODO: remove IPython dependency here 
     "use strict";
 
     var Cell = function (options) {
         /* Constructor
          *
          * The Base `Cell` class from which to inherit.
          * @constructor
          * @param:
          *  options: dictionary
          *      Dictionary of keyword arguments.
          *          events: $(Events) instance
          *          config: dictionary
          *          keyboard_manager: KeyboardManager instance
          */
         options = options || {};
         this.keyboard_manager = options.keyboard_manager;
         this.events = options.events;
         var config = utils.mergeopt(Cell, options.config);
         // superclass default overwrite our default
         
         this.placeholder = config.placeholder || '';
         this.read_only = config.cm_config.readOnly;
         this.selected = false;
         this.rendered = false;
         this.mode = 'command';
 
         // Metadata property
         var that = this;
         this._metadata = {};
         Object.defineProperty(this, 'metadata', {
             get: function() { return that._metadata; },
             set: function(value) {
                 that._metadata = value;
                 if (that.celltoolbar) {
                     that.celltoolbar.rebuild();
                 }
             }
         });
 
         // load this from metadata later ?
         this.user_highlight = 'auto';
         this.cm_config = config.cm_config;
         this.cell_id = utils.uuid();
         this._options = config;
 
         // For JS VM engines optimization, attributes should be all set (even
         // to null) in the constructor, and if possible, if different subclass
         // have new attributes with same name, they should be created in the
         // same order. Easiest is to create and set to null in parent class.
 
         this.element = null;
         this.cell_type = this.cell_type || null;
         this.code_mirror = null;
 
         this.create_element();
         if (this.element !== null) {
             this.element.data("cell", this);
             this.bind_events();
             this.init_classes();
         }
     };
 
     Cell.options_default = {
         cm_config : {
             indentUnit : 4,
             readOnly: false,
             theme: "default",
             extraKeys: {
                 "Cmd-Right":"goLineRight",
                 "End":"goLineRight",
                 "Cmd-Left":"goLineLeft"
             }
         }
     };
     
     // FIXME: Workaround CM Bug #332 (Safari segfault on drag)
     // by disabling drag/drop altogether on Safari
     // https://github.com/codemirror/CodeMirror/issues/332    
     if (utils.browser[0] == "Safari") {
         Cell.options_default.cm_config.dragDrop = false;
     }
 
     /**
      * Empty. Subclasses must implement create_element.
      * This should contain all the code to create the DOM element in notebook
      * and will be called by Base Class constructor.
      * @method create_element
      */
     Cell.prototype.create_element = function () {
     };
 
     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 {
             this.element.addClass('unselected');
         }
         if (this.rendered) {
             this.element.addClass('rendered');
         } else {
             this.element.addClass('unrendered');
         }
         if (this.mode === 'edit') {
             this.element.addClass('edit_mode');
         } else {
             this.element.addClass('command_mode');
         }
     };
 
     /**
      * Subclasses can implement override bind_events.
      * Be carefull to call the parent method when overwriting as it fires event.
      * this will be triggerd after create_element in constructor.
      * @method bind_events
      */
     Cell.prototype.bind_events = function () {
         var that = this;
         // We trigger events so that Cell doesn't have to depend on Notebook.
         that.element.click(function (event) {
             if (!that.selected) {
                 that.events.trigger('select.Cell', {'cell':that});
             }
         });
         that.element.focusin(function (event) {
             if (!that.selected) {
                 that.events.trigger('select.Cell', {'cell':that});
             }
         });
         if (this.code_mirror) {
             this.code_mirror.on("change", function(cm, change) {
                 that.events.trigger("set_dirty.Notebook", {value: true});
             });
         }
         if (this.code_mirror) {
             this.code_mirror.on('focus', function(cm, change) {
                 that.events.trigger('edit_mode.Cell', {cell: that});
             });
         }
         if (this.code_mirror) {
             this.code_mirror.on('blur', function(cm, change) {
                 that.events.trigger('command_mode.Cell', {cell: that});
             });
         }
 
         this.element.dblclick(function () {
             if (that.selected === false) {
                 this.events.trigger('select.Cell', {'cell':that});
             }
             var cont = that.unrender();
             if (cont) {
                 that.focus_editor();
             }
         });
     };
     
     /**
      * This method gets called in CodeMirror's onKeyDown/onKeyPress
      * handlers and is used to provide custom key handling.
      *
      * To have custom handling, subclasses should override this method, but still call it
      * in order to process the Edit mode keyboard shortcuts.
      *
      * @method handle_codemirror_keyevent
      * @param {CodeMirror} editor - The codemirror instance bound to the cell
      * @param {event} event - key press event which either should or should not be handled by CodeMirror
      * @return {Boolean} `true` if CodeMirror should ignore the event, `false` Otherwise
      */
     Cell.prototype.handle_codemirror_keyevent = function (editor, event) {
         var shortcuts = this.keyboard_manager.edit_shortcuts;
 
         var cur = editor.getCursor();
         if((cur.line !== 0 || cur.ch !==0) && event.keyCode === 38){
             event._ipkmIgnore = true;
         }
         var nLastLine = editor.lastLine();
         if ((event.keyCode === 40) &&
              ((cur.line !== nLastLine) ||
                (cur.ch !== editor.getLineHandle(nLastLine).text.length))
            ) {
             event._ipkmIgnore = true;
         }
         // if this is an edit_shortcuts shortcut, the global keyboard/shortcut
         // manager will handle it
         if (shortcuts.handles(event)) {
             return true;
         }
         
         return false;
     };
 
 
     /**
      * Triger typsetting of math by mathjax on current cell element
      * @method typeset
      */
     Cell.prototype.typeset = function () {
         if (window.MathJax) {
             var cell_math = this.element.get(0);
             MathJax.Hub.Queue(["Typeset", MathJax.Hub, cell_math]);
         }
     };
 
     /**
      * handle cell level logic when a cell is selected
      * @method select
      * @return is the action being taken
      */
     Cell.prototype.select = function () {
         if (!this.selected) {
             this.element.addClass('selected');
             this.element.removeClass('unselected');
             this.selected = true;
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * handle cell level logic when a cell is unselected
      * @method unselect
      * @return is the action being taken
      */
     Cell.prototype.unselect = function () {
         if (this.selected) {
             this.element.addClass('unselected');
             this.element.removeClass('selected');
             this.selected = false;
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * should be overritten by subclass
      * @method execute
      */
     Cell.prototype.execute = function () {
         return;
     };
 
     /**
      * handle cell level logic when a cell is rendered
      * @method render
      * @return is the action being taken
      */
     Cell.prototype.render = function () {
         if (!this.rendered) {
             this.element.addClass('rendered');
             this.element.removeClass('unrendered');
             this.rendered = true;
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * handle cell level logic when a cell is unrendered
      * @method unrender
      * @return is the action being taken
      */
     Cell.prototype.unrender = function () {
         if (this.rendered) {
             this.element.addClass('unrendered');
             this.element.removeClass('rendered');
             this.rendered = false;
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * Delegates keyboard shortcut handling to either IPython keyboard
      * manager when in command mode, or CodeMirror when in edit mode
      *
      * @method handle_keyevent
      * @param {CodeMirror} editor - The codemirror instance bound to the cell
      * @param {event} - key event to be handled
      * @return {Boolean} `true` if CodeMirror should ignore the event, `false` Otherwise
      */
     Cell.prototype.handle_keyevent = function (editor, event) {
         if (this.mode === 'command') {
             return true;
         } else if (this.mode === 'edit') {
             return this.handle_codemirror_keyevent(editor, event);
         }
     };
 
     /**
      * @method at_top
      * @return {Boolean}
      */
     Cell.prototype.at_top = function () {
         var cm = this.code_mirror;
         var cursor = cm.getCursor();
         if (cursor.line === 0 && cursor.ch === 0) {
             return true;
         }
         return false;
     };
 
     /**
      * @method at_bottom
      * @return {Boolean}
      * */
     Cell.prototype.at_bottom = function () {
         var cm = this.code_mirror;
         var cursor = cm.getCursor();
         if (cursor.line === (cm.lineCount()-1) && cursor.ch === cm.getLine(cursor.line).length) {
             return true;
         }
         return false;
     };
 
     /**
      * enter the command mode for the cell
      * @method command_mode
      * @return is the action being taken
      */
     Cell.prototype.command_mode = function () {
         if (this.mode !== 'command') {
             this.element.addClass('command_mode');
             this.element.removeClass('edit_mode');
             this.mode = 'command';
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * enter the edit mode for the cell
      * @method command_mode
      * @return is the action being taken
      */
     Cell.prototype.edit_mode = function () {
         if (this.mode !== 'edit') {
             this.element.addClass('edit_mode');
             this.element.removeClass('command_mode');
             this.mode = 'edit';
             return true;
         } else {
             return false;
         }
     };
     
     /**
      * Focus the cell in the DOM sense
      * @method focus_cell
      */
     Cell.prototype.focus_cell = function () {
         this.element.focus();
     };
 
     /**
      * Focus the editor area so a user can type
      *
      * NOTE: If codemirror is focused via a mouse click event, you don't want to
      * call this because it will cause a page jump.
      * @method focus_editor
      */
     Cell.prototype.focus_editor = function () {
         this.refresh();
         this.code_mirror.focus();
     };
 
     /**
      * Refresh codemirror instance
      * @method refresh
      */
     Cell.prototype.refresh = function () {
         if (this.code_mirror) {
             this.code_mirror.refresh();
         }
     };
 
     /**
      * should be overritten by subclass
      * @method get_text
      */
     Cell.prototype.get_text = function () {
     };
 
     /**
      * should be overritten by subclass
      * @method set_text
      * @param {string} text
      */
     Cell.prototype.set_text = function (text) {
     };
 
     /**
      * should be overritten by subclass
      * serialise cell to json.
      * @method toJSON
      **/
     Cell.prototype.toJSON = function () {
         var data = {};
         // deepcopy the metadata so copied cells don't share the same object
         data.metadata = JSON.parse(JSON.stringify(this.metadata));
         data.cell_type = this.cell_type;
         return data;
     };
 
     /**
      * should be overritten by subclass
      * @method fromJSON
      **/
     Cell.prototype.fromJSON = function (data) {
         if (data.metadata !== undefined) {
             this.metadata = data.metadata;
         }
     };
 
 
     /**
      * can the cell be split into two cells (false if not deletable)
      * @method is_splittable
      **/
     Cell.prototype.is_splittable = function () {
         return this.is_deletable();
     };
 
 
     /**
      * can the cell be merged with other cells (false if not deletable)
      * @method is_mergeable
      **/
     Cell.prototype.is_mergeable = function () {
         return this.is_deletable();
     };
 
     /**
      * is the cell deletable? only false (undeletable) if
      * metadata.deletable is explicitly false -- everything else
      * counts as true
      *
      * @method is_deletable
      **/
     Cell.prototype.is_deletable = function () {
         if (this.metadata.deletable === false) {
             return false;
         }
         return true;
     };
 
     /**
      * @return {String} - the text before the cursor
      * @method get_pre_cursor
      **/
     Cell.prototype.get_pre_cursor = function () {
         var cursor = this.code_mirror.getCursor();
         var text = this.code_mirror.getRange({line:0, ch:0}, cursor);
         text = text.replace(/^\n+/, '').replace(/\n+$/, '');
         return text;
     };
 
 
     /**
      * @return {String} - the text after the cursor
      * @method get_post_cursor
      **/
     Cell.prototype.get_post_cursor = function () {
         var cursor = this.code_mirror.getCursor();
         var last_line_num = this.code_mirror.lineCount()-1;
         var last_line_len = this.code_mirror.getLine(last_line_num).length;
         var end = {line:last_line_num, ch:last_line_len};
         var text = this.code_mirror.getRange(cursor, end);
         text = text.replace(/^\n+/, '').replace(/\n+$/, '');
         return text;
     };
 
     /**
      * Show/Hide CodeMirror LineNumber
      * @method show_line_numbers
      *
      * @param value {Bool}  show (true), or hide (false) the line number in CodeMirror
      **/
     Cell.prototype.show_line_numbers = function (value) {
         this.code_mirror.setOption('lineNumbers', value);
         this.code_mirror.refresh();
     };
 
     /**
      * Toggle  CodeMirror LineNumber
      * @method toggle_line_numbers
      **/
     Cell.prototype.toggle_line_numbers = function () {
         var val = this.code_mirror.getOption('lineNumbers');
         this.show_line_numbers(!val);
     };
 
     /**
      * Force codemirror highlight mode
      * @method force_highlight
      * @param {object} - CodeMirror mode
      **/
     Cell.prototype.force_highlight = function(mode) {
         this.user_highlight = mode;
         this.auto_highlight();
     };
 
     /**
      * Try to autodetect cell highlight mode, or use selected mode
      * @methods _auto_highlight
      * @private
      * @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' )
         {
             mode = this.user_highlight;
             CodeMirror.autoLoadMode(this.code_mirror, mode);
             this.code_mirror.setOption('mode', mode);
             return;
         }
         var current_mode = this.code_mirror.getOption('mode', mode);
         var first_line = this.code_mirror.getLine(0);
         // loop on every pairs
         for(mode in modes) {
             var regs = modes[mode].reg;
             // only one key every time but regexp can't be keys...
             for(var i=0; i<regs.length; i++) {
                 // here we handle non magic_modes
                 if(first_line.match(regs[i]) !== null) {
                     if(current_mode == mode){
                         return;
                     }
                     if (mode.search('magic_') !== 0) {
                         utils.requireCodeMirrorMode(mode, function () {
                             that.code_mirror.setOption('mode', mode);
                         });
                         return;
                     }
                     var open = modes[mode].open || "%%";
                     var close = modes[mode].close || "%%end";
                     var magic_mode = mode;
                     mode = magic_mode.substr(6);
                     if(current_mode == magic_mode){
                         return;
                     }
                     utils.requireCodeMirrorMode(mode, function () {
                         // create on the fly a mode that switch between
                         // plain/text and something else, otherwise `%%` is
                         // source of some highlight issues.
                         CodeMirror.defineMode(magic_mode, function(config) {
                             return CodeMirror.multiplexingMode(
                                 CodeMirror.getMode(config, 'text/plain'),
                                 // always set something on close
                                 {open: open, close: close,
                                  mode: CodeMirror.getMode(config, mode),
                                  delimStyle: "delimit"
                                 }
                             );
                         });
                         that.code_mirror.setOption('mode', magic_mode);
                     });
                     return;
                 }
             }
         }
         // fallback on default
         var default_mode;
         try {
             default_mode = this._options.cm_config.mode;
         } catch(e) {
             default_mode = 'text/plain';
         }
         if( current_mode === default_mode){
             return;
         }
         this.code_mirror.setOption('mode', default_mode);
     };
 
     var UnrecognizedCell = function (options) {
         /** Constructor for unrecognized cells */
         Cell.apply(this, arguments);
         this.cell_type = 'unrecognized';
         this.celltoolbar = null;
         this.data = {};
         
         Object.seal(this);
     };
 
     UnrecognizedCell.prototype = Object.create(Cell.prototype);
     
     
     // cannot merge or split unrecognized cells
     UnrecognizedCell.prototype.is_mergeable = function () {
         return false;
     };
     
     UnrecognizedCell.prototype.is_splittable = function () {
         return false;
     };
     
     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));
     };
 
     UnrecognizedCell.prototype.fromJSON = function (data) {
         this.data = data;
         if (data.metadata !== undefined) {
             this.metadata = data.metadata;
         } else {
             data.metadata = this.metadata;
         }
         this.element.find('.inner_cell').find("a").text("Unrecognized cell type: " + data.cell_type);
     };
     
     UnrecognizedCell.prototype.create_element = function () {
         Cell.prototype.create_element.apply(this, arguments);
         var cell = this.element = $("<div>").addClass('cell unrecognized_cell');
         cell.attr('tabindex','2');
 
         var prompt = $('<div/>').addClass('prompt input_prompt');
         cell.append(prompt);
         var inner_cell = $('<div/>').addClass('inner_cell');
         inner_cell.append(
             $("<a>")
                 .attr("href", "#")
                 .text("Unrecognized cell type")
         );
         cell.append(inner_cell);
         this.element = cell;
     };
     
     UnrecognizedCell.prototype.bind_events = function () {
         Cell.prototype.bind_events.apply(this, arguments);
         var cell = this;
         
         this.element.find('.inner_cell').find("a").click(function () {
             cell.events.trigger('unrecognized_cell.Cell', {cell: cell})
         });
     };
 
     // Backwards compatibility.
     IPython.Cell = Cell;
 
     return {
         Cell: Cell,
         UnrecognizedCell: UnrecognizedCell
     };
 });

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

@@ -1,448 +1,452 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/events'
 ], function(IPython, $, events) {
     "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;
         this.create_element();
         this.rebuild();
         return this;
     };
 
 
     CellToolbar.prototype.create_element = function () {
         this.inner_element = $('<div/>').addClass('celltoolbar');
         this.element = $('<div/>').addClass('ctb_hideshow')
             .append(this.inner_element);
     };
 
 
     // The default css style for the outer celltoolbar div
     // (ctb_hideshow) is display: none.
     // To show the cell toolbar, *both* of the following conditions must be met:
     // - A parent container has class `ctb_global_show`
     // - The celltoolbar has the class `ctb_show`
     // This allows global show/hide, as well as per-cell show/hide.
 
     CellToolbar.global_hide = function () {
         $('body').removeClass('ctb_global_show');
     };
 
 
     CellToolbar.global_show = function () {
         $('body').addClass('ctb_global_show');
     };
 
 
     CellToolbar.prototype.hide = function () {
         this.element.removeClass('ctb_show');
     };
 
 
     CellToolbar.prototype.show = function () {
         this.element.addClass('ctb_show');
     };
 
 
     /**
      * Class variable that should contain a dict of all available callback
      * we need to think of wether or not we allow nested namespace
      * @property _callback_dict
      * @private
      * @static
      * @type Dict
      */
     CellToolbar._callback_dict = {};
 
 
     /**
      * Class variable that should contain the reverse order list of the button
      * to add to the toolbar of each cell
      * @property _ui_controls_list
      * @private
      * @static
      * @type List
      */
     CellToolbar._ui_controls_list = [];
 
 
     /**
      * Class variable that should contain the CellToolbar instances for each
      * cell of the notebook
      *
      * @private
      * @property _instances
      * @static
      * @type List
      */
     CellToolbar._instances = [];
 
 
     /**
      * keep a list of all the available presets for the toolbar
      * @private
      * @property _presets
      * @static
      * @type Dict
      */
     CellToolbar._presets = {};
 
 
     // this is by design not a prototype.
     /**
      * Register a callback to create an UI element in a cell toolbar.
      * @method register_callback
      * @param name {String} name to use to refer to the callback. It is advised to use a prefix with the name
      * for easier sorting and avoid collision
      * @param callback {function(div, cell)} callback that will be called to generate the ui element
      * @param [cell_types] {List_of_String|undefined} optional list of cell types. If present the UI element
      * will be added only to cells of types in the list.
      *
      *
      * The callback will receive the following element :
      *
      *    * a div in which to add element.
      *    * the cell it is responsible from
      *
      * @example
      *
      * Example that create callback for a button that toggle between `true` and `false` label,
      * with the metadata under the key 'foo' to reflect the status of the button.
      *
      *      // first param reference to a DOM div
      *      // second param reference to the cell.
      *      var toggle =  function(div, cell) {
      *          var button_container = $(div)
      *
      *          // let's create a button that show the  current value of the metadata
      *          var button = $('<div/>').button({label:String(cell.metadata.foo)});
      *
      *          // On click, change the metadata value and update the button label
      *          button.click(function(){
      *                      var v = cell.metadata.foo;
      *                      cell.metadata.foo = !v;
      *                      button.button("option", "label", String(!v));
      *                  })
      *
      *          // add the button to the DOM div.
      *          button_container.append(button);
      *      }
      *
      *      // now we register the callback under the name `foo` to give the
      *      // user the ability to use it later
      *      CellToolbar.register_callback('foo', toggle);
      */
     CellToolbar.register_callback = function(name, callback, cell_types) {
         // Overwrite if it already exists.
         CellToolbar._callback_dict[name] = cell_types ? {callback: callback, cell_types: cell_types} : callback;
     };
 
 
     /**
      * Register a preset of UI element in a cell toolbar.
      * Not supported Yet.
      * @method register_preset
      * @param name {String} name to use to refer to the preset. It is advised to use a prefix with the name
      * for easier sorting and avoid collision
      * @param  preset_list {List_of_String} reverse order of the button in the toolbar. Each String of the list
      *          should correspond to a name of a registerd callback.
      *
      * @private
      * @example
      *
      *      CellToolbar.register_callback('foo.c1', function(div, cell){...});
      *      CellToolbar.register_callback('foo.c2', function(div, cell){...});
      *      CellToolbar.register_callback('foo.c3', function(div, cell){...});
      *      CellToolbar.register_callback('foo.c4', function(div, cell){...});
      *      CellToolbar.register_callback('foo.c5', function(div, cell){...});
      *
      *      CellToolbar.register_preset('foo.foo_preset1', ['foo.c1', 'foo.c2', 'foo.c5'])
      *      CellToolbar.register_preset('foo.foo_preset2', ['foo.c4', 'foo.c5'])
      */
     CellToolbar.register_preset = function(name, preset_list, notebook) {
         CellToolbar._presets[name] = preset_list;
         events.trigger('preset_added.CellToolbar', {name: name});
         // When "register_callback" is called by a custom extension, it may be executed after notebook is loaded.
         // In that case, activate the preset if needed.
         if (notebook && notebook.metadata && notebook.metadata.celltoolbar === name){
             CellToolbar.activate_preset(name);
         }
     };
 
 
     /**
      * List the names of the presets that are currently registered.
      *
      * @method list_presets
      * @static
      */
     CellToolbar.list_presets = function() {
         var keys = [];
         for (var k in CellToolbar._presets) {
             keys.push(k);
         }
         return keys;
     };
 
 
     /**
      * Activate an UI preset from `register_preset`
      *
      * This does not update the selection UI.
      *
      * @method activate_preset
      * @param preset_name {String} string corresponding to the preset name
      *
      * @static
      * @private
      * @example
      *
      *      CellToolbar.activate_preset('foo.foo_preset1');
      */
     CellToolbar.activate_preset = function(preset_name){
         var preset = CellToolbar._presets[preset_name];
 
         if(preset !== undefined){
             CellToolbar._ui_controls_list = preset;
             CellToolbar.rebuild_all();
         }
 
         events.trigger('preset_activated.CellToolbar', {name: preset_name});
     };
 
 
     /**
      * This should be called on the class and not on a instance as it will trigger
      * rebuild of all the instances.
      * @method rebuild_all
      * @static
      *
      */
     CellToolbar.rebuild_all = function(){
         for(var i=0; i < CellToolbar._instances.length; i++){
             CellToolbar._instances[i].rebuild();
         }
     };
 
     /**
      * Rebuild all the button on the toolbar to update its state.
      * @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 = [];
 
         var callbacks = CellToolbar._callback_dict;
         var preset = CellToolbar._ui_controls_list;
         // Yes we iterate on the class variable, not the instance one.
         for (var i=0; i < preset.length; i++) {
             var key = preset[i];
             var callback = callbacks[key];
             if (!callback) continue;
 
             if (typeof callback === 'object') {
                 if (callback.cell_types.indexOf(this.cell.cell_type) === -1) continue;
                 callback = callback.callback;
             }
             
             var local_div = $('<div/>').addClass('button_container');
             try {
                 callback(local_div, this.cell, this);
                 this.ui_controls_list.push(key);
             } catch (e) {
                 console.log("Error in cell toolbar callback " + key, e);
                 continue;
             }
             // only append if callback succeeded.
             this.inner_element.append(local_div);
         }
 
         // If there are no controls or the cell is a rendered TextCell hide the toolbar.
         if (!this.ui_controls_list.length) {
             this.hide();
         } else {
             this.show();
         }
     };
 
 
     CellToolbar.utils = {};
 
 
     /**
      * A utility function to generate bindings between a checkbox and cell/metadata
      * @method utils.checkbox_ui_generator
      * @static
      *
      * @param name {string} Label in front of the checkbox
      * @param setter {function( cell, newValue )}
      *        A setter method to set the newValue
      * @param getter {function( cell )}
      *        A getter methods which return the current value.
      *
      * @return callback {function( div, cell )} Callback to be passed to `register_callback`
      *
      * @example
      *
      * An exmple that bind the subkey `slideshow.isSectionStart` to a checkbox with a `New Slide` label
      *
      *     var newSlide = CellToolbar.utils.checkbox_ui_generator('New Slide',
      *          // setter
      *          function(cell, value){
      *              // we check that the slideshow namespace exist and create it if needed
      *              if (cell.metadata.slideshow == undefined){cell.metadata.slideshow = {}}
      *              // set the value
      *              cell.metadata.slideshow.isSectionStart = value
      *              },
      *          //geter
      *          function(cell){ var ns = cell.metadata.slideshow;
      *              // if the slideshow namespace does not exist return `undefined`
      *              // (will be interpreted as `false` by checkbox) otherwise
      *              // return the value
      *              return (ns == undefined)? undefined: ns.isSectionStart
      *              }
      *      );
      *
      *      CellToolbar.register_callback('newSlide', newSlide);
      *
      */
     CellToolbar.utils.checkbox_ui_generator = function(name, setter, getter){
         return function(div, cell, celltoolbar) {
             var button_container = $(div);
 
             var chkb = $('<input/>').attr('type', 'checkbox');
             var lbl = $('<label/>').append($('<span/>').text(name));
             lbl.append(chkb);
             chkb.attr("checked", getter(cell));
 
             chkb.click(function(){
                         var v = getter(cell);
                         setter(cell, !v);
                         chkb.attr("checked", !v);
             });
             button_container.append($('<span/>').append(lbl));
         };
     };
 
 
     /**
      * A utility function to generate bindings between a input field and cell/metadata
      * @method utils.input_ui_generator
      * @static
      *
      * @param name {string} Label in front of the input field
      * @param setter {function( cell, newValue )}
      *        A setter method to set the newValue
      * @param getter {function( cell )}
      *        A getter methods which return the current value.
      *
      * @return callback {function( div, cell )} Callback to be passed to `register_callback`
      *
      */
     CellToolbar.utils.input_ui_generator = function(name, setter, getter){
         return function(div, cell, celltoolbar) {
             var button_container = $(div);
 
             var text = $('<input/>').attr('type', 'text');
             var lbl = $('<label/>').append($('<span/>').text(name));
             lbl.append(text);
             text.attr("value", getter(cell));
 
             text.keyup(function(){
                 setter(cell, text.val());
             });
             button_container.append($('<span/>').append(lbl));
             IPython.keyboard_manager.register_events(text);
         };
     };
 
     /**
      * A utility function to generate bindings between a dropdown list cell
      * @method utils.select_ui_generator
      * @static
      *
      * @param list_list {list_of_sublist} List of sublist of metadata value and name in the dropdown list.
      *        subslit shoud contain 2 element each, first a string that woul be displayed in the dropdown list,
      *        and second the corresponding value to  be passed to setter/return by getter. the corresponding value 
      *        should not be "undefined" or behavior can be unexpected.
      * @param setter {function( cell, newValue )}
      *        A setter method to set the newValue
      * @param getter {function( cell )}
      *        A getter methods which return the current value of the metadata.
      * @param [label=""] {String} optionnal label for the dropdown menu
      *
      * @return callback {function( div, cell )} Callback to be passed to `register_callback`
      *
      * @example
      *
      *      var select_type = CellToolbar.utils.select_ui_generator([
      *              ["<None>"       , "None"      ],
      *              ["Header Slide" , "header_slide" ],
      *              ["Slide"        , "slide"        ],
      *              ["Fragment"     , "fragment"     ],
      *              ["Skip"         , "skip"         ],
      *              ],
      *              // setter
      *              function(cell, value){
      *                  // we check that the slideshow namespace exist and create it if needed
      *                  if (cell.metadata.slideshow == undefined){cell.metadata.slideshow = {}}
      *                  // set the value
      *                  cell.metadata.slideshow.slide_type = value
      *                  },
      *              //geter
      *              function(cell){ var ns = cell.metadata.slideshow;
      *                  // if the slideshow namespace does not exist return `undefined`
      *                  // (will be interpreted as `false` by checkbox) otherwise
      *                  // return the value
      *                  return (ns == undefined)? undefined: ns.slide_type
      *                  }
      *      CellToolbar.register_callback('slideshow.select', select_type);
      *
      */
     CellToolbar.utils.select_ui_generator = function(list_list, setter, getter, label) {
         label = label || "";
         return function(div, cell, celltoolbar) {
             var button_container = $(div);
             var lbl = $("<label/>").append($('<span/>').text(label));
             var select = $('<select/>');
             for(var i=0; i < list_list.length; i++){
                 var opt = $('<option/>')
                     .attr('value', list_list[i][1])
                     .text(list_list[i][0]);
                 select.append(opt);
             }
             select.val(getter(cell));
             select.change(function(){
                         setter(cell, select.val());
                     });
             button_container.append($('<span/>').append(lbl).append(select));
         };
     };
 
     // Backwards compatability.
     IPython.CellToolbar = CellToolbar;
 
     return {'CellToolbar': CellToolbar};
 });

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

@@ -1,148 +1,150 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 // Example Use for the CellToolbar library
 // add the following to your custom.js to load
 // Celltoolbar UI for slideshow
 
 // ```
 // $.getScript('/static/js/celltoolbarpresets/example.js');
 // ```
 define([
     'jquery',
     'notebook/js/celltoolbar',
 ], function($, celltoolbar) {
     "use strict";
 
     var CellToolbar = celltoolbar.CellToolbar;
 
     var example_preset = [];
 
     var simple_button = function(div, cell) {
         var button_container = $(div);
         var button = $('<div/>').button({icons:{primary:'ui-icon-locked'}});
         var fun = function(value){
                 try{
                     if(value){
                         cell.code_mirror.setOption('readOnly','nocursor');
                         button.button('option','icons',{primary:'ui-icon-locked'});
                     } else {
                         cell.code_mirror.setOption('readOnly',false);
                         button.button('option','icons',{primary:'ui-icon-unlocked'});
                     }
                 } catch(e){}
 
         };
             fun(cell.metadata.ro);
             button.click(function(){
                     var v = cell.metadata.ro;
                     var locked = !v;
                     cell.metadata.ro = locked;
                     fun(locked);
                     })
                 .css('height','16px')
                 .css('width','35px');
         button_container.append(button);
     };
 
     CellToolbar.register_callback('example.lock',simple_button);
     example_preset.push('example.lock');
 
     var toggle_test =  function(div, cell) {
         var button_container = $(div);
         var button = $('<div/>')
             .button({label:String(cell.metadata.foo)}).
             css('width','65px');
         button.click(function(){
                     var v = cell.metadata.foo;
                     cell.metadata.foo = !v;
                     button.button("option","label",String(!v));
                 });
        button_container.append(button);
     };
 
     CellToolbar.register_callback('example.toggle',toggle_test);
     example_preset.push('example.toggle');
 
     var checkbox_test = CellToolbar.utils.checkbox_ui_generator('Yes/No',
          // setter
          function(cell, value){
              // we check that the slideshow namespace exist and create it if needed
              if (cell.metadata.yn_test === undefined){cell.metadata.yn_test = {};}
              // set the value
              cell.metadata.yn_test.value = value;
              },
          //geter
          function(cell){ var ns = cell.metadata.yn_test;
              // if the slideshow namespace does not exist return `undefined`
              // (will be interpreted as `false` by checkbox) otherwise
              // return the value
              return (ns === undefined)? undefined: ns.value;
              }
     );
 
 
     CellToolbar.register_callback('example.checkbox',checkbox_test);
     example_preset.push('example.checkbox');
 
     var select_test = CellToolbar.utils.select_ui_generator([
             ["-"            ,undefined      ],
             ["Header Slide" ,"header_slide" ],
             ["Slide"        ,"slide"        ],
             ["Fragment"     ,"fragment"     ],
             ["Skip"         ,"skip"         ],
             ],
             // setter
             function(cell,value){
                 // we check that the slideshow namespace exist and create it if needed
                 if (cell.metadata.test === undefined){cell.metadata.test = {};}
                 // set the value
                 cell.metadata.test.slide_type = value;
                 },
             //geter
             function(cell){ var ns = cell.metadata.test;
                 // if the slideshow namespace does not exist return `undefined`
                 // (will be interpreted as `false` by checkbox) otherwise
                 // return the value
                 return (ns === undefined)? undefined: ns.slide_type;
                 });
 
     CellToolbar.register_callback('example.select',select_test);
     example_preset.push('example.select');
 
     var simple_dialog = function(title,text){
         var dlg = $('<div/>').attr('title',title)
             .append($('<p/>').text(text));
         $(dlg).dialog({
                 autoOpen: true,
                 height: 300,
                 width: 650,
                 modal: true,
                 close: function() {
-                    //cleanup on close
+                    /**
+                     *cleanup on close
+                     */
                     $(this).remove();
                 }
         });
     };
 
     var add_simple_dialog_button = function(div, cell) {
         var help_text = ["This is the Metadata editting UI.",
                          "It heavily rely on plugin to work ",
                          "and is still under developpement. You shouldn't wait too long before",
                          " seeing some customisable buttons in those toolbar."
                         ].join('\n');
         var button_container = $(div);
         var button = $('<div/>').button({label:'?'})
                 .click(function(){simple_dialog('help',help_text); return false;});
         button_container.append(button);
     };
 
     var register = function (notebook) {
         CellToolbar.register_callback('example.help',add_simple_dialog_button);
         example_preset.push('example.help');
 
         CellToolbar.register_preset('Example',example_preset, notebook);
         console.log('Example extension for metadata editing loaded.');
     };
     return {'register': register};
 });

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

@@ -1,571 +1,573 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 /**
  *
  *
  * @module codecell
  * @namespace codecell
  * @class CodeCell
  */
 
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
     'base/js/keyboard',
     'notebook/js/cell',
     'notebook/js/outputarea',
     'notebook/js/completer',
     'notebook/js/celltoolbar',
     'codemirror/lib/codemirror',
     'codemirror/mode/python/python',
     'notebook/js/codemirror-ipython'
 ], function(IPython, $, utils, keyboard, cell, outputarea, completer, celltoolbar, CodeMirror, cmpython, cmip) {
     "use strict";
     
     var Cell = cell.Cell;
 
     /* local util for codemirror */
     var posEq = function(a, b) {return a.line == b.line && a.ch == b.ch;};
 
     /**
      *
      * function to delete until previous non blanking space character
      * or first multiple of 4 tabstop.
      * @private
      */
     CodeMirror.commands.delSpaceToPrevTabStop = function(cm){
         var from = cm.getCursor(true), to = cm.getCursor(false), sel = !posEq(from, to);
         if (!posEq(from, to)) { cm.replaceRange("", from, to); return; }
         var cur = cm.getCursor(), line = cm.getLine(cur.line);
         var tabsize = cm.getOption('tabSize');
         var chToPrevTabStop = cur.ch-(Math.ceil(cur.ch/tabsize)-1)*tabsize;
         from = {ch:cur.ch-chToPrevTabStop,line:cur.line};
         var select = cm.getRange(from,cur);
         if( select.match(/^\ +$/) !== null){
             cm.replaceRange("",from,cur);
         } else {
             cm.deleteH(-1,"char");
         }
     };
 
     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;
         this.events = options.events;
         this.tooltip = options.tooltip;
         this.config = options.config;
 
         // create all attributed in constructor function
         // even if null for V8 VM optimisation
         this.input_prompt_number = null;
         this.celltoolbar = null;
         this.output_area = null;
         // Keep a stack of the 'active' output areas (where active means the 
         // output area that recieves output).  When a user activates an output
         // area, it gets pushed to the stack.  Then, when the output area is
         // deactivated, it's popped from the stack.  When the stack is empty,
         // the cell's output area is used.
         this.active_output_areas = [];
         var that = this;
         Object.defineProperty(this, 'active_output_area', {
             get: function() {
                 if (that.active_output_areas && that.active_output_areas.length > 0) {
                     return that.active_output_areas[that.active_output_areas.length-1];
                 } else {
                     return that.output_area;
                 }
             },
         });
 
         this.last_msg_id = null;
         this.completer = null;
 
 
         var config = utils.mergeopt(CodeCell, this.config);
         Cell.apply(this,[{
             config: config, 
             keyboard_manager: options.keyboard_manager, 
             events: this.events}]);
 
         // Attributes we want to override in this subclass.
         this.cell_type = "code";
         this.element.focusout(
             function() { that.auto_highlight(); }
         );
     };
 
     CodeCell.options_default = {
         cm_config : {
             extraKeys: {
                 "Tab" :  "indentMore",
                 "Shift-Tab" : "indentLess",
                 "Backspace" : "delSpaceToPrevTabStop",
                 "Cmd-/" : "toggleComment",
                 "Ctrl-/" : "toggleComment"
             },
             mode: 'ipython',
             theme: 'ipython',
             matchBrackets: true
         }
     };
 
     CodeCell.msg_cells = {};
 
     CodeCell.prototype = Object.create(Cell.prototype);
 
     /**
      * @method push_output_area
      */
     CodeCell.prototype.push_output_area = function (output_area) {
         this.active_output_areas.push(output_area);
     };
 
     /**
      * @method pop_output_area
      */
     CodeCell.prototype.pop_output_area = function (output_area) {
         var index = this.active_output_areas.lastIndexOf(output_area);
         if (index > -1) {
             this.active_output_areas.splice(index, 1);
         }
     };
 
     /**
      * @method auto_highlight
      */
     CodeCell.prototype.auto_highlight = function () {
         this._auto_highlight(this.config.cell_magic_highlight);
     };
 
     /** @method create_element */
     CodeCell.prototype.create_element = function () {
         Cell.prototype.create_element.apply(this, arguments);
 
         var cell =  $('<div></div>').addClass('cell code_cell');
         cell.attr('tabindex','2');
 
         var input = $('<div></div>').addClass('input');
         var prompt = $('<div/>').addClass('prompt input_prompt');
         var inner_cell = $('<div/>').addClass('inner_cell');
         this.celltoolbar = new celltoolbar.CellToolbar({
             cell: this, 
             notebook: this.notebook});
         inner_cell.append(this.celltoolbar.element);
         var input_area = $('<div/>').addClass('input_area');
         this.code_mirror = new CodeMirror(input_area.get(0), this.cm_config);
         this.code_mirror.on('keydown', $.proxy(this.handle_keyevent,this))
         $(this.code_mirror.getInputField()).attr("spellcheck", "false");
         inner_cell.append(input_area);
         input.append(prompt).append(inner_cell);
 
         var widget_area = $('<div/>')
             .addClass('widget-area')
             .hide();
         this.widget_area = widget_area;
         var widget_prompt = $('<div/>')
             .addClass('prompt')
             .appendTo(widget_area);
         var widget_subarea = $('<div/>')
             .addClass('widget-subarea')
             .appendTo(widget_area);
         this.widget_subarea = widget_subarea;
         var widget_clear_buton = $('<button />')
             .addClass('close')
             .html('&times;')
             .click(function() {
                 widget_area.slideUp('', function(){ widget_subarea.html(''); });
                 })
             .appendTo(widget_prompt);
 
         var output = $('<div></div>');
         cell.append(input).append(widget_area).append(output);
         this.element = cell;
         this.output_area = new outputarea.OutputArea({
             selector: output, 
             prompt_area: true, 
             events: this.events, 
             keyboard_manager: this.keyboard_manager});
         this.completer = new completer.Completer(this, this.events);
     };
 
     /** @method bind_events */
     CodeCell.prototype.bind_events = function () {
         Cell.prototype.bind_events.apply(this);
         var that = this;
 
         this.element.focusout(
             function() { that.auto_highlight(); }
         );
     };
 
 
     /**
      *  This method gets called in CodeMirror's onKeyDown/onKeyPress
      *  handlers and is used to provide custom key handling. Its return
      *  value is used to determine if CodeMirror should ignore the event:
      *  true = ignore, false = don't ignore.
      *  @method handle_codemirror_keyevent
      */
 
     CodeCell.prototype.handle_codemirror_keyevent = function (editor, event) {
 
         var that = this;
         // whatever key is pressed, first, cancel the tooltip request before
         // they are sent, and remove tooltip if any, except for tab again
         var tooltip_closed = null;
         if (event.type === 'keydown' && event.which != keycodes.tab ) {
             tooltip_closed = this.tooltip.remove_and_cancel_tooltip();
         }
 
         var cur = editor.getCursor();
         if (event.keyCode === keycodes.enter){
             this.auto_highlight();
         }
 
         if (event.which === keycodes.down && event.type === 'keypress' && this.tooltip.time_before_tooltip >= 0) {
             // triger on keypress (!) otherwise inconsistent event.which depending on plateform
             // browser and keyboard layout !
             // Pressing '(' , request tooltip, don't forget to reappend it
             // The second argument says to hide the tooltip if the docstring
             // is actually empty
             this.tooltip.pending(that, true);
         } else if ( tooltip_closed && event.which === keycodes.esc && event.type === 'keydown') {
             // If tooltip is active, cancel it.  The call to
             // remove_and_cancel_tooltip above doesn't pass, force=true.
             // Because of this it won't actually close the tooltip
             // if it is in sticky mode. Thus, we have to check again if it is open
             // and close it with force=true.
             if (!this.tooltip._hidden) {
                 this.tooltip.remove_and_cancel_tooltip(true);
             }
             // If we closed the tooltip, don't let CM or the global handlers
             // handle this event.
             event.codemirrorIgnore = true;
             event.preventDefault();
             return true;
         } else if (event.keyCode === keycodes.tab && event.type === 'keydown' && event.shiftKey) {
                 if (editor.somethingSelected() || editor.getSelections().length !== 1){
                     var anchor = editor.getCursor("anchor");
                     var head = editor.getCursor("head");
                     if( anchor.line != head.line){
                         return false;
                     }
                 }
                 this.tooltip.request(that);
                 event.codemirrorIgnore = true;
                 event.preventDefault();
                 return true;
         } else if (event.keyCode === keycodes.tab && event.type == 'keydown') {
             // Tab completion.
             this.tooltip.remove_and_cancel_tooltip();
 
             // completion does not work on multicursor, it might be possible though in some cases
             if (editor.somethingSelected() || editor.getSelections().length > 1) {
                 return false;
             }
             var pre_cursor = editor.getRange({line:cur.line,ch:0},cur);
             if (pre_cursor.trim() === "") {
                 // Don't autocomplete if the part of the line before the cursor
                 // is empty.  In this case, let CodeMirror handle indentation.
                 return false;
             } else {
                 event.codemirrorIgnore = true;
                 event.preventDefault();
                 this.completer.startCompletion();
                 return true;
             }
         } 
         
         // keyboard event wasn't one of those unique to code cells, let's see
         // if it's one of the generic ones (i.e. check edit mode shortcuts)
         return Cell.prototype.handle_codemirror_keyevent.apply(this, [editor, event]);
     };
 
     // Kernel related calls.
 
     CodeCell.prototype.set_kernel = function (kernel) {
         this.kernel = kernel;
     };
 
     /**
      * Execute current code cell to the kernel
      * @method execute
      */
     CodeCell.prototype.execute = function () {
         if (!this.kernel || !this.kernel.is_connected()) {
             console.log("Can't execute, kernel is not connected.");
             return;
         }
 
         this.active_output_area.clear_output();
         
         // Clear widget area
         this.widget_subarea.html('');
         this.widget_subarea.height('');
         this.widget_area.height('');
         this.widget_area.hide();
 
         this.set_input_prompt('*');
         this.element.addClass("running");
         if (this.last_msg_id) {
             this.kernel.clear_callbacks_for_msg(this.last_msg_id);
         }
         var callbacks = this.get_callbacks();
         
         var old_msg_id = this.last_msg_id;
         this.last_msg_id = this.kernel.execute(this.get_text(), callbacks, {silent: false, store_history: true});
         if (old_msg_id) {
             delete CodeCell.msg_cells[old_msg_id];
         }
         CodeCell.msg_cells[this.last_msg_id] = this;
         this.render();
         this.events.trigger('execute.CodeCell', {cell: this});
     };
     
     /**
      * Construct the default callbacks for
      * @method get_callbacks
      */
     CodeCell.prototype.get_callbacks = function () {
         var that = this;
         return {
             shell : {
                 reply : $.proxy(this._handle_execute_reply, this),
                 payload : {
                     set_next_input : $.proxy(this._handle_set_next_input, this),
                     page : $.proxy(this._open_with_pager, this)
                 }
             },
             iopub : {
                 output : function() { 
                     that.active_output_area.handle_output.apply(that.active_output_area, arguments);
                 }, 
                 clear_output : function() { 
                     that.active_output_area.handle_clear_output.apply(that.active_output_area, arguments);
                 }, 
             },
             input : $.proxy(this._handle_input_request, this)
         };
     };
     
     CodeCell.prototype._open_with_pager = function (payload) {
         this.events.trigger('open_with_text.Pager', payload);
     };
 
     /**
      * @method _handle_execute_reply
      * @private
      */
     CodeCell.prototype._handle_execute_reply = function (msg) {
         this.set_input_prompt(msg.content.execution_count);
         this.element.removeClass("running");
         this.events.trigger('set_dirty.Notebook', {value: true});
     };
 
     /**
      * @method _handle_set_next_input
      * @private
      */
     CodeCell.prototype._handle_set_next_input = function (payload) {
         var data = {'cell': this, 'text': payload.text};
         this.events.trigger('set_next_input.Notebook', data);
     };
 
     /**
      * @method _handle_input_request
      * @private
      */
     CodeCell.prototype._handle_input_request = function (msg) {
         this.active_output_area.append_raw_input(msg);
     };
 
 
     // Basic cell manipulation.
 
     CodeCell.prototype.select = function () {
         var cont = Cell.prototype.select.apply(this);
         if (cont) {
             this.code_mirror.refresh();
             this.auto_highlight();
         }
         return cont;
     };
 
     CodeCell.prototype.render = function () {
         var cont = Cell.prototype.render.apply(this);
         // Always execute, even if we are already in the rendered state
         return cont;
     };
     
     CodeCell.prototype.select_all = function () {
         var start = {line: 0, ch: 0};
         var nlines = this.code_mirror.lineCount();
         var last_line = this.code_mirror.getLine(nlines-1);
         var end = {line: nlines-1, ch: last_line.length};
         this.code_mirror.setSelection(start, end);
     };
 
 
     CodeCell.prototype.collapse_output = function () {
         this.output_area.collapse();
     };
 
 
     CodeCell.prototype.expand_output = function () {
         this.output_area.expand();
         this.output_area.unscroll_area();
     };
 
     CodeCell.prototype.scroll_output = function () {
         this.output_area.expand();
         this.output_area.scroll_if_long();
     };
 
     CodeCell.prototype.toggle_output = function () {
         this.output_area.toggle_output();
     };
 
     CodeCell.prototype.toggle_output_scroll = function () {
         this.output_area.toggle_scroll();
     };
 
 
     CodeCell.input_prompt_classical = function (prompt_value, lines_number) {
         var ns;
         if (prompt_value === undefined || prompt_value === null) {
             ns = "&nbsp;";
         } else {
             ns = encodeURIComponent(prompt_value);
         }
         return 'In&nbsp;[' + ns + ']:';
     };
 
     CodeCell.input_prompt_continuation = function (prompt_value, lines_number) {
         var html = [CodeCell.input_prompt_classical(prompt_value, lines_number)];
         for(var i=1; i < lines_number; i++) {
             html.push(['...:']);
         }
         return html.join('<br/>');
     };
 
     CodeCell.input_prompt_function = CodeCell.input_prompt_classical;
 
 
     CodeCell.prototype.set_input_prompt = function (number) {
         var nline = 1;
         if (this.code_mirror !== undefined) {
            nline = this.code_mirror.lineCount();
         }
         this.input_prompt_number = number;
         var prompt_html = CodeCell.input_prompt_function(this.input_prompt_number, nline);
         // This HTML call is okay because the user contents are escaped.
         this.element.find('div.input_prompt').html(prompt_html);
     };
 
 
     CodeCell.prototype.clear_input = function () {
         this.code_mirror.setValue('');
     };
 
 
     CodeCell.prototype.get_text = function () {
         return this.code_mirror.getValue();
     };
 
 
     CodeCell.prototype.set_text = function (code) {
         return this.code_mirror.setValue(code);
     };
 
 
     CodeCell.prototype.clear_output = function (wait) {
         this.active_output_area.clear_output(wait);
         this.set_input_prompt();
     };
 
 
     // JSON serialization
 
     CodeCell.prototype.fromJSON = function (data) {
         Cell.prototype.fromJSON.apply(this, arguments);
         if (data.cell_type === 'code') {
             if (data.source !== undefined) {
                 this.set_text(data.source);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 this.code_mirror.clearHistory();
                 this.auto_highlight();
             }
             this.set_input_prompt(data.execution_count);
             this.output_area.trusted = data.metadata.trusted || false;
             this.output_area.fromJSON(data.outputs);
             if (data.metadata.collapsed !== undefined) {
                 if (data.metadata.collapsed) {
                     this.collapse_output();
                 } else {
                     this.expand_output();
                 }
             }
         }
     };
 
 
     CodeCell.prototype.toJSON = function () {
         var data = Cell.prototype.toJSON.apply(this);
         data.source = this.get_text();
         // is finite protect against undefined and '*' value
         if (isFinite(this.input_prompt_number)) {
             data.execution_count = this.input_prompt_number;
         } else {
             data.execution_count = null;
         }
         var outputs = this.output_area.toJSON();
         data.outputs = outputs;
         data.metadata.trusted = this.output_area.trusted;
         data.metadata.collapsed = this.output_area.collapsed;
         return data;
     };
 
     /**
      * handle cell level logic when a cell is unselected
      * @method unselect
      * @return is the action being taken
      */
     CodeCell.prototype.unselect = function () {
         var cont = Cell.prototype.unselect.apply(this);
         if (cont) {
             // When a code cell is usnelected, make sure that the corresponding
             // tooltip and completer to that cell is closed.
             this.tooltip.remove_and_cancel_tooltip(true);
             if (this.completer !== null) {
                 this.completer.close();
             }
         }
         return cont;
     };
 
     // Backwards compatability.
     IPython.CodeCell = CodeCell;
 
     return {'CodeCell': CodeCell};
 });

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

@@ -1,406 +1,414 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
     'base/js/keyboard',
     'notebook/js/contexthint',
     'codemirror/lib/codemirror',
 ], function(IPython, $, utils, keyboard, CodeMirror) {
     "use strict";
 
     // easier key mapping
     var keycodes = keyboard.keycodes;
 
     var prepend_n_prc = function(str, n) {
         for( var i =0 ; i< n ; i++){
             str = '%'+str ;
         }
         return str;
     };
 
     var _existing_completion = function(item, completion_array){
         for( var i=0; i < completion_array.length; i++) {
             if (completion_array[i].trim().substr(-item.length) == item) {
                 return true;
             }
         }
         return false;
     };
 
     // what is the common start of all completions
     function shared_start(B, drop_prct) {
         if (B.length == 1) {
             return B[0];
         }
         var A = [];
         var common;
         var min_lead_prct = 10;
         for (var i = 0; i < B.length; i++) {
             var str = B[i].str;
             var localmin = 0;
             if(drop_prct === true){
                 while ( str.substr(0, 1) == '%') {
                     localmin = localmin+1;
                     str = str.substring(1);
                 }
             }
             min_lead_prct = Math.min(min_lead_prct, localmin);
             A.push(str);
         }
 
         if (A.length > 1) {
             var tem1, tem2, s;
             A = A.slice(0).sort();
             tem1 = A[0];
             s = tem1.length;
             tem2 = A.pop();
             while (s && tem2.indexOf(tem1) == -1) {
                 tem1 = tem1.substring(0, --s);
             }
             if (tem1 === "" || tem2.indexOf(tem1) !== 0) {
                 return {
                     str:prepend_n_prc('', min_lead_prct),
                     type: "computed",
                     from: B[0].from,
                     to: B[0].to
                     };
             }
             return {
                 str: prepend_n_prc(tem1, min_lead_prct),
                 type: "computed",
                 from: B[0].from,
                 to: B[0].to
             };
         }
         return null;
     }
 
 
     var Completer = function (cell, events) {
         this.cell = cell;
         this.editor = cell.code_mirror;
         var that = this;
         events.on('kernel_busy.Kernel', function () {
             that.skip_kernel_completion = true;
         });
         events.on('kernel_idle.Kernel', function () {
             that.skip_kernel_completion = false;
         });
     };
 
     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
         this.carry_on_completion(true);
     };
 
 
     // easy access for julia to monkeypatch
     //
     Completer.reinvoke_re = /[%0-9a-z._/\\:~-]/i;
 
     Completer.prototype.reinvoke= function(pre_cursor, block, cursor){
         return Completer.reinvoke_re.test(pre_cursor);
     };
 
     /**
      *
      * pass true as parameter if this is the first invocation of the completer
      * this will prevent the completer to dissmiss itself if it is not on a
      * word boundary like pressing tab after a space, and make it autopick the
      * only choice if there is only one which prevent from popping the UI.  as
      * well as fast-forwarding the typing if all completion have a common
      * 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({
             line: cur.line,
             ch: cur.ch - 1
         }, cur);
 
         // we need to check that we are still on a word boundary
         // because while typing the completer is still reinvoking itself
         // so dismiss if we are on a "bad" caracter
         if (!this.reinvoke(pre_cursor) && !first_invocation) {
             this.close();
             return;
         }
 
         this.autopick = false;
         if (first_invocation) {
             this.autopick = true;
         }
 
         // We want a single cursor position.
         if (this.editor.somethingSelected()|| this.editor.getSelections().length > 1) {
             return;
         }
 
         // one kernel completion came back, finish_completing will be called with the results
         // we fork here and directly call finish completing if kernel is busy
         var cursor_pos = utils.to_absolute_cursor_pos(this.editor, cur);
         if (this.skip_kernel_completion) {
             this.finish_completing({ content: {
                 matches: [],
                 cursor_start: cursor_pos,
                 cursor_end: cursor_pos,
             }});
         } else {
             this.cell.kernel.complete(this.editor.getValue(), cursor_pos,
                 $.proxy(this.finish_completing, this)
             );
         }
     };
 
     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;
         var matches = content.matches;
 
         var cur = this.editor.getCursor();
         if (end === null) {
             // adapted message spec replies don't have cursor position info,
             // interpret end=null as current position,
             // and negative start relative to that
             end = utils.to_absolute_cursor_pos(this.editor, cur);
             if (start < 0) {
                 start = end + start;
             }
         }
         var results = CodeMirror.contextHint(this.editor);
         var filtered_results = [];
         //remove results from context completion
         //that are already in kernel completion
         var i;
         for (i=0; i < results.length; i++) {
             if (!_existing_completion(results[i].str, matches)) {
                 filtered_results.push(results[i]);
             }
         }
 
         // append the introspection result, in order, at at the beginning of
         // the table and compute the replacement range from current cursor
         // positon and matched_text length.
         for (i = matches.length - 1; i >= 0; --i) {
             filtered_results.unshift({
                 str: matches[i],
                 type: "introspection",
                 from: utils.from_absolute_cursor_pos(this.editor, start),
                 to: utils.from_absolute_cursor_pos(this.editor, end)
             });
         }
 
         // one the 2 sources results have been merge, deal with it
         this.raw_result = filtered_results;
 
         // if empty result return
         if (!this.raw_result || !this.raw_result.length) return;
 
         // When there is only one completion, use it directly.
         if (this.autopick && this.raw_result.length == 1) {
             this.insert(this.raw_result[0]);
             return;
         }
 
         if (this.raw_result.length == 1) {
             // test if first and only completion totally matches
             // what is typed, in this case dismiss
             var str = this.raw_result[0].str;
             var pre_cursor = this.editor.getRange({
                 line: cur.line,
                 ch: cur.ch - str.length
             }, cur);
             if (pre_cursor == str) {
                 this.close();
                 return;
             }
         }
 
         if (!this.visible) {
             this.complete = $('<div/>').addClass('completions');
             this.complete.attr('id', 'complete');
 
             // Currently webkit doesn't use the size attr correctly. See:
             // https://code.google.com/p/chromium/issues/detail?id=4579
             this.sel = $('<select/>')
                 .attr('tabindex', -1)
                 .attr('multiple', 'true');
             this.complete.append(this.sel);
             this.visible = true;
             $('body').append(this.complete);
 
             //build the container
             var that = this;
             this.sel.dblclick(function () {
                 that.pick();
             });
             this.sel.focus(function () {
                 that.editor.focus();
             });
             this._handle_keydown = function (cm, event) {
                 that.keydown(event);
             };
             this.editor.on('keydown', this._handle_keydown);
             this._handle_keypress = function (cm, event) {
                 that.keypress(event);
             };
             this.editor.on('keypress', this._handle_keypress);
         }
         this.sel.attr('size', Math.min(10, this.raw_result.length));
 
         // After everything is on the page, compute the postion.
         // We put it above the code if it is too close to the bottom of the page.
         var pos = this.editor.cursorCoords(
             utils.from_absolute_cursor_pos(this.editor, start)
         );
         var left = pos.left-3;
         var top;
         var cheight = this.complete.height();
         var wheight = $(window).height();
         if (pos.bottom+cheight+5 > wheight) {
             top = pos.top-cheight-4;
         } else {
             top = pos.bottom+1;
         }
         this.complete.css('left', left + 'px');
         this.complete.css('top', top + 'px');
 
         // Clear and fill the list.
         this.sel.text('');
         this.build_gui_list(this.raw_result);
         return true;
     };
 
     Completer.prototype.insert = function (completion) {
         this.editor.replaceRange(completion.str, completion.from, completion.to);
     };
 
     Completer.prototype.build_gui_list = function (completions) {
         for (var i = 0; i < completions.length; ++i) {
             var opt = $('<option/>').text(completions[i].str).addClass(completions[i].type);
             this.sel.append(opt);
         }
         this.sel.children().first().attr('selected', 'true');
         this.sel.scrollTop(0);
     };
 
     Completer.prototype.close = function () {
         this.done = true;
         $('#complete').remove();
         this.editor.off('keydown', this._handle_keydown);
         this.editor.off('keypress', this._handle_keypress);
         this.visible = false;
     };
 
     Completer.prototype.pick = function () {
         this.insert(this.raw_result[this.sel[0].selectedIndex]);
         this.close();
     };
 
     Completer.prototype.keydown = function (event) {
         var code = event.keyCode;
         var that = this;
 
         // Enter
         if (code == keycodes.enter) {
             event.codemirrorIgnore = true;
             event._ipkmIgnore = true;
             event.preventDefault();
             this.pick();
         // Escape or backspace
         } else if (code == keycodes.esc || code == keycodes.backspace) {
             event.codemirrorIgnore = true;
             event._ipkmIgnore = true;
             event.preventDefault();
             this.close();
         } else if (code == keycodes.tab) {
             //all the fastforwarding operation,
             //Check that shared start is not null which can append with prefixed completion
             // like %pylab , pylab have no shred start, and ff will result in py<tab><tab>
             // to erase py
             var sh = shared_start(this.raw_result, true);
             if (sh) {
                 this.insert(sh);
             }
             this.close();
             //reinvoke self
             setTimeout(function () {
                 that.carry_on_completion();
             }, 50);
         } else if (code == keycodes.up || code == keycodes.down) {
             // need to do that to be able to move the arrow
             // when on the first or last line ofo a code cell
             event.codemirrorIgnore = true;
             event._ipkmIgnore = true;
             event.preventDefault();
 
             var options = this.sel.find('option');
             var index = this.sel[0].selectedIndex;
             if (code == keycodes.up) {
                 index--;
             }
             if (code == keycodes.down) {
                 index++;
             }
             index = Math.min(Math.max(index, 0), options.length-1);
             this.sel[0].selectedIndex = index;
         } else if (code == keycodes.pageup || code == keycodes.pagedown) {
             event._ipkmIgnore = true;
 
             var options = this.sel.find('option');
             var index = this.sel[0].selectedIndex;
             if (code == keycodes.pageup) {
                 index -= 10; // As 10 is the hard coded size of the drop down menu
             } else {
                 index += 10;
             }
             index = Math.min(Math.max(index, 0), options.length-1);
             this.sel[0].selectedIndex = index;
         } else if (code == keycodes.left || code == keycodes.right) {
             this.close();
         }
     };
 
     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;
         
         // don't handle keypress if it's not a character (arrows on FF)
         // or ENTER/TAB
         if (event.charCode === 0 ||
             code == keycodes.tab ||
             code == keycodes.enter
         ) return;
         
         this.close();
         this.editor.focus();
         setTimeout(function () {
             that.carry_on_completion();
         }, 50);
     };
 
     // For backwards compatability.
     IPython.Completer = Completer;
 
     return {'Completer': Completer};
 });

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

@@ -1,220 +1,224 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'notebook/js/toolbar',
     'notebook/js/celltoolbar',
 ], function(IPython, $, toolbar, celltoolbar) {
     "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;
         this.construct();
         this.add_celltype_list();
         this.add_celltoolbar_list();
         this.bind_events();
     };
 
     MainToolBar.prototype = Object.create(toolbar.ToolBar.prototype);
 
     MainToolBar.prototype.construct = function () {
         var that = this;
         this.add_buttons_group([
                 {
                     id : 'save_b',
                     label : 'Save and Checkpoint',
                     icon : 'fa-save',
                     callback : function () {
                         that.notebook.save_checkpoint();
                         }
                 }
             ]);
 
         this.add_buttons_group([
                 {
                     id : 'insert_below_b',
                     label : 'Insert Cell Below',
                     icon : 'fa-plus',
                     callback : function () {
                         that.notebook.insert_cell_below('code');
                         that.notebook.select_next();
                         that.notebook.focus_cell();
                         }
                 }
             ],'insert_above_below');
 
         this.add_buttons_group([
                 {
                     id : 'cut_b',
                     label : 'Cut Cell',
                     icon : 'fa-cut',
                     callback : function () {
                         that.notebook.cut_cell();
                         }
                 },
                 {
                     id : 'copy_b',
                     label : 'Copy Cell',
                     icon : 'fa-copy',
                     callback : function () {
                         that.notebook.copy_cell();
                         }
                 },
                 {
                     id : 'paste_b',
                     label : 'Paste Cell Below',
                     icon : 'fa-paste',
                     callback : function () {
                         that.notebook.paste_cell_below();
                         }
                 }
             ],'cut_copy_paste');
 
         this.add_buttons_group([
                 {
                     id : 'move_up_b',
                     label : 'Move Cell Up',
                     icon : 'fa-arrow-up',
                     callback : function () {
                         that.notebook.move_cell_up();
                         }
                 },
                 {
                     id : 'move_down_b',
                     label : 'Move Cell Down',
                     icon : 'fa-arrow-down',
                     callback : function () {
                         that.notebook.move_cell_down();
                         }
                 }
             ],'move_up_down');
         
 
         this.add_buttons_group([
                 {
                     id : 'run_b',
                     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();
                     }
                 },
                 {
                     id : 'interrupt_b',
                     label : 'Interrupt',
                     icon : 'fa-stop',
                     callback : function () {
                         that.notebook.kernel.interrupt();
                         }
                 },
                 {
                     id : 'repeat_b',
                     label : 'Restart Kernel',
                     icon : 'fa-repeat',
                     callback : function () {
                         that.notebook.restart_kernel();
                         }
                 }
             ],'run_int');
     };
     
     MainToolBar.prototype.add_celltype_list = function () {
         this.element
             .append($('<select/>')
                 .attr('id','cell_type')
                 .addClass('form-control select-xs')
                 .append($('<option/>').attr('value','code').text('Code'))
                 .append($('<option/>').attr('value','markdown').text('Markdown'))
                 .append($('<option/>').attr('value','raw').text('Raw NBConvert'))
                 .append($('<option/>').attr('value','heading').text('Heading'))
             );
     };
 
     MainToolBar.prototype.add_celltoolbar_list = function () {
         var label = $('<span/>').addClass("navbar-text").text('Cell Toolbar:');
         var select = $('<select/>')
             .attr('id', 'ctb_select')
             .addClass('form-control select-xs')
             .append($('<option/>').attr('value', '').text('None'));
         this.element.append(label).append(select);
         var that = this;
         select.change(function() {
                 var val = $(this).val();
                 if (val ==='') {
                     celltoolbar.CellToolbar.global_hide();
                     delete that.notebook.metadata.celltoolbar;
                 } else {
                     celltoolbar.CellToolbar.global_show();
                     celltoolbar.CellToolbar.activate_preset(val, that.events);
                     that.notebook.metadata.celltoolbar = val;
                 }
             });
         // Setup the currently registered presets.
         var presets = celltoolbar.CellToolbar.list_presets();
         for (var i=0; i<presets.length; i++) {
             var name = presets[i];
             select.append($('<option/>').attr('value', name).text(name));
         }
         // Setup future preset registrations.
         this.events.on('preset_added.CellToolbar', function (event, data) {
             var name = data.name;
             select.append($('<option/>').attr('value', name).text(name));
         });
         // Update select value when a preset is activated.
         this.events.on('preset_activated.CellToolbar', function (event, data) {
             if (select.val() !== data.name)
                 select.val(data.name);
         });
     };
 
     MainToolBar.prototype.bind_events = function () {
         var that = this;
         
         this.element.find('#cell_type').change(function () {
             var cell_type = $(this).val();
             switch (cell_type) {
             case 'code':
                 that.notebook.to_code();
                 break;
             case 'markdown':
                 that.notebook.to_markdown();
                 break;
             case 'raw':
                 that.notebook.to_raw();
                 break;
             case 'heading':
                 that.notebook._warn_heading();
                 that.notebook.to_heading();
                 that.element.find('#cell_type').val("markdown");
                 break;
             default:
                 console.log("unrecognized cell type:", cell_type);
             }
         });
         this.events.on('selected_cell_type_changed.Notebook', function (event, data) {
             if (data.cell_type === 'heading') {
                 that.element.find('#cell_type').val(data.cell_type+data.level);
             } else {
                 that.element.find('#cell_type').val(data.cell_type);
             }
         });
     };
 
     // Backwards compatability.
     IPython.MainToolBar = MainToolBar;
 
     return {'MainToolBar': MainToolBar};
 });

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

@@ -1,383 +1,391 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'jquery',
     'base/js/namespace',
     'base/js/dialog',
     'base/js/utils',
     'notebook/js/tour',
     'bootstrap',
     'moment',
 ], function($, IPython, dialog, utils, tour, bootstrap, moment) {
     "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;
         this.notebook = options.notebook;
         this.contents = options.contents;
         this.layout_manager = options.layout_manager;
         this.events = options.events;
         this.save_widget = options.save_widget;
         this.quick_help = options.quick_help;
 
         try {
             this.tour = new tour.Tour(this.notebook, this.events);
         } catch (e) {
             this.tour = undefined;
             console.log("Failed to instantiate Notebook Tour", e);
         }
 
         if (this.selector !== undefined) {
             this.element = $(selector);
             this.style();
             this.bind_events();
         }
     };
 
     // TODO: This has definitively nothing to do with style ...
     MenuBar.prototype.style = function () {
         var that = this;
         this.element.find("li").click(function (event, ui) {
                 // The selected cell loses focus when the menu is entered, so we
                 // re-select it upon selection.
                 var i = that.notebook.get_selected_index();
                 that.notebook.select(i);
             }
         );
     };
 
     MenuBar.prototype._nbconvert = function (format, download) {
         download = download || false;
         var notebook_path = this.notebook.notebook_path;
         var url = utils.url_join_encode(
             this.base_url,
             'nbconvert',
             format,
             notebook_path
         ) + "?download=" + download.toString();
         
         var w = window.open()
         if (this.notebook.dirty) {
             this.notebook.save_notebook().then(function() {
                 w.location = url;
             });
         } else {
             w.location = url;
         }
     };
 
     MenuBar.prototype.bind_events = function () {
-        //  File
+        /**
+         *  File
+         */
         var that = this;
         this.element.find('#new_notebook').click(function () {
             var w = window.open();
             // Create a new notebook in the same path as the current
             // notebook's path.
             var parent = utils.url_path_split(that.notebook.notebook_path)[0];
             that.contents.new_untitled(parent, {type: "notebook"}).then(
                     function (data) {
                         w.location = utils.url_join_encode(
                                 that.base_url, 'notebooks', data.path
                             );
                     },
                     function(error) {
                         w.close();
                         dialog.modal({
                             title : 'Creating Notebook Failed',
                             body : "The error was: " + error.message,
                             buttons : {'OK' : {'class' : 'btn-primary'}}
                         });
                     }
                 );
         });
         this.element.find('#open_notebook').click(function () {
             var parent = utils.url_path_split(that.notebook.notebook_path)[0];
             window.open(utils.url_join_encode(that.base_url, 'tree', parent));
         });
         this.element.find('#copy_notebook').click(function () {
             that.notebook.copy_notebook();
             return false;
         });
         this.element.find('#download_ipynb').click(function () {
             var base_url = that.notebook.base_url;
             var notebook_path = that.notebook.notebook_path;
             if (that.notebook.dirty) {
                 that.notebook.save_notebook({async : false});
             }
             
             var url = utils.url_join_encode(base_url, 'files', notebook_path);
             window.open(url + '?download=1');
         });
         
         this.element.find('#print_preview').click(function () {
             that._nbconvert('html', false);
         });
 
         this.element.find('#download_html').click(function () {
             that._nbconvert('html', true);
         });
 
         this.element.find('#download_rst').click(function () {
             that._nbconvert('rst', true);
         });
 
         this.element.find('#download_pdf').click(function () {
             that._nbconvert('pdf', true);
         });
 
         this.element.find('#rename_notebook').click(function () {
             that.save_widget.rename_notebook({notebook: that.notebook});
         });
         this.element.find('#save_checkpoint').click(function () {
             that.notebook.save_checkpoint();
         });
         this.element.find('#restore_checkpoint').click(function () {
         });
         this.element.find('#trust_notebook').click(function () {
             that.notebook.trust_notebook();
         });
         this.events.on('trust_changed.Notebook', function (event, trusted) {
             if (trusted) {
                 that.element.find('#trust_notebook')
                     .addClass("disabled")
                     .find("a").text("Trusted Notebook");
             } else {
                 that.element.find('#trust_notebook')
                     .removeClass("disabled")
                     .find("a").text("Trust Notebook");
             }
         });
         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();
             };
             // finish with close on success or failure
             that.notebook.session.delete(close_window, close_window);
         });
         // Edit
         this.element.find('#cut_cell').click(function () {
             that.notebook.cut_cell();
         });
         this.element.find('#copy_cell').click(function () {
             that.notebook.copy_cell();
         });
         this.element.find('#delete_cell').click(function () {
             that.notebook.delete_cell();
         });
         this.element.find('#undelete_cell').click(function () {
             that.notebook.undelete_cell();
         });
         this.element.find('#split_cell').click(function () {
             that.notebook.split_cell();
         });
         this.element.find('#merge_cell_above').click(function () {
             that.notebook.merge_cell_above();
         });
         this.element.find('#merge_cell_below').click(function () {
             that.notebook.merge_cell_below();
         });
         this.element.find('#move_cell_up').click(function () {
             that.notebook.move_cell_up();
         });
         this.element.find('#move_cell_down').click(function () {
             that.notebook.move_cell_down();
         });
         this.element.find('#edit_nb_metadata').click(function () {
             that.notebook.edit_metadata({
                 notebook: that.notebook,
                 keyboard_manager: that.notebook.keyboard_manager});
         });
         
         // View
         this.element.find('#toggle_header').click(function () {
             $('div#header').toggle();
             that.layout_manager.do_resize();
         });
         this.element.find('#toggle_toolbar').click(function () {
             $('div#maintoolbar').toggle();
             that.layout_manager.do_resize();
         });
         // Insert
         this.element.find('#insert_cell_above').click(function () {
             that.notebook.insert_cell_above('code');
             that.notebook.select_prev();
         });
         this.element.find('#insert_cell_below').click(function () {
             that.notebook.insert_cell_below('code');
             that.notebook.select_next();
         });
         // Cell
         this.element.find('#run_cell').click(function () {
             that.notebook.execute_cell();
         });
         this.element.find('#run_cell_select_below').click(function () {
             that.notebook.execute_cell_and_select_below();
         });
         this.element.find('#run_cell_insert_below').click(function () {
             that.notebook.execute_cell_and_insert_below();
         });
         this.element.find('#run_all_cells').click(function () {
             that.notebook.execute_all_cells();
         });
         this.element.find('#run_all_cells_above').click(function () {
             that.notebook.execute_cells_above();
         });
         this.element.find('#run_all_cells_below').click(function () {
             that.notebook.execute_cells_below();
         });
         this.element.find('#to_code').click(function () {
             that.notebook.to_code();
         });
         this.element.find('#to_markdown').click(function () {
             that.notebook.to_markdown();
         });
         this.element.find('#to_raw').click(function () {
             that.notebook.to_raw();
         });
         
         this.element.find('#toggle_current_output').click(function () {
             that.notebook.toggle_output();
         });
         this.element.find('#toggle_current_output_scroll').click(function () {
             that.notebook.toggle_output_scroll();
         });
         this.element.find('#clear_current_output').click(function () {
             that.notebook.clear_output();
         });
         
         this.element.find('#toggle_all_output').click(function () {
             that.notebook.toggle_all_output();
         });
         this.element.find('#toggle_all_output_scroll').click(function () {
             that.notebook.toggle_all_output_scroll();
         });
         this.element.find('#clear_all_output').click(function () {
             that.notebook.clear_all_output();
         });
         
         // Kernel
         this.element.find('#int_kernel').click(function () {
             that.notebook.kernel.interrupt();
         });
         this.element.find('#restart_kernel').click(function () {
             that.notebook.restart_kernel();
         });
         this.element.find('#reconnect_kernel').click(function () {
             that.notebook.kernel.reconnect();
         });
         // Help
         if (this.tour) {
             this.element.find('#notebook_tour').click(function () {
                 that.tour.start();
             });
         } else {
             this.element.find('#notebook_tour').addClass("disabled");
         }
         this.element.find('#keyboard_shortcuts').click(function () {
             that.quick_help.show_keyboard_shortcuts();
         });
         
         this.update_restore_checkpoint(null);
         
         this.events.on('checkpoints_listed.Notebook', function (event, data) {
             that.update_restore_checkpoint(that.notebook.checkpoints);
         });
         
         this.events.on('checkpoint_created.Notebook', function (event, data) {
             that.update_restore_checkpoint(that.notebook.checkpoints);
         });
         
         this.events.on('notebook_loaded.Notebook', function() {
             var langinfo = that.notebook.metadata.language_info || {};
             that.update_nbconvert_script(langinfo);
         });
         
         this.events.on('kernel_ready.Kernel', function(event, data) {
             var langinfo = data.kernel.info_reply.language_info || {};
             that.update_nbconvert_script(langinfo);
         });
     };
 
     MenuBar.prototype.update_restore_checkpoint = function(checkpoints) {
         var ul = this.element.find("#restore_checkpoint").find("ul");
         ul.empty();
         if (!checkpoints || checkpoints.length === 0) {
             ul.append(
                 $("<li/>")
                 .addClass("disabled")
                 .append(
                     $("<a/>")
                     .text("No checkpoints")
                 )
             );
             return;
         }
         
         var that = this;
         checkpoints.map(function (checkpoint) {
             var d = new Date(checkpoint.last_modified);
             ul.append(
                 $("<li/>").append(
                     $("<a/>")
                     .attr("href", "#")
                     .text(moment(d).format("LLLL"))
                     .click(function () {
                         that.notebook.restore_checkpoint_dialog(checkpoint);
                     })
                 )
             );
         });
     };
     
     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;
         
         // Set menu entry text to e.g. "Python (.py)"
         var langname = (langinfo.name || 'Script')
         langname = langname.charAt(0).toUpperCase()+langname.substr(1) // Capitalise
         el.find('a').text(langname + ' ('+(langinfo.file_extension || 'txt')+')');
         
         // Unregister any previously registered handlers
         el.off('click');
         if (langinfo.nbconvert_exporter) {
             // Metadata specifies a specific exporter, e.g. 'python'
             el.click(function() {
                 that._nbconvert(langinfo.nbconvert_exporter, true);
             });
         } else {
             // Use generic 'script' exporter
             el.click(function() {
                 that._nbconvert('script', true);
             });
         }
     };
 
     // Backwards compatability.
     IPython.MenuBar = MenuBar;
 
     return {'MenuBar': MenuBar};
 });

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

@@ -1,2508 +1,2518 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
     'base/js/dialog',
     'notebook/js/cell',
     'notebook/js/textcell',
     'notebook/js/codecell',
     'services/sessions/session',
     'notebook/js/celltoolbar',
     'components/marked/lib/marked',
     'codemirror/lib/codemirror',
     'codemirror/addon/runmode/runmode',
     'notebook/js/mathjaxutils',
     'base/js/keyboard',
     'notebook/js/tooltip',
     'notebook/js/celltoolbarpresets/default',
     'notebook/js/celltoolbarpresets/rawcell',
     'notebook/js/celltoolbarpresets/slideshow',
     'notebook/js/scrollmanager'
 ], function (
     IPython, 
     $,
     utils,
     dialog,
     cellmod,
     textcell,
     codecell,
     session, 
     celltoolbar,
     marked,
     CodeMirror,
     runMode,
     mathjaxutils,
     keyboard,
     tooltip,
     default_celltoolbar,
     rawcell_celltoolbar,
     slideshow_celltoolbar,
     scrollmanager
     ) {
     "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;
         this.notebook_name = options.notebook_name;
         this.events = options.events;
         this.keyboard_manager = options.keyboard_manager;
         this.contents = options.contents;
         this.save_widget = options.save_widget;
         this.tooltip = new tooltip.Tooltip(this.events);
         this.ws_url = options.ws_url;
         this._session_starting = false;
         this.default_cell_type = this.config.default_cell_type || 'code';
 
         //  Create default scroll manager.
         this.scroll_manager = new scrollmanager.ScrollManager(this);
 
         // TODO: This code smells (and the other `= this` line a couple lines down)
         // We need a better way to deal with circular instance references.
         this.keyboard_manager.notebook = this;
         this.save_widget.notebook = this;
         
         mathjaxutils.init();
 
         if (marked) {
             marked.setOptions({
                 gfm : true,
                 tables: true,
                 // FIXME: probably want central config for CodeMirror theme when we have js config
                 langPrefix: "cm-s-ipython language-",
                 highlight: function(code, lang, callback) {
                     if (!lang) {
                         // no language, no highlight
                         if (callback) {
                             callback(null, code);
                             return;
                         } else {
                             return code;
                         }
                     }
                     utils.requireCodeMirrorMode(lang, function () {
                         var el = document.createElement("div");
                         var mode = CodeMirror.getMode({}, lang);
                         if (!mode) {
                             console.log("No CodeMirror mode: " + lang);
                             callback(null, code);
                             return;
                         }
                         try {
                             CodeMirror.runMode(code, mode, el);
                             callback(null, el.innerHTML);
                         } catch (err) {
                             console.log("Failed to highlight " + lang + " code", err);
                             callback(err, code);
                         }
                     }, function (err) {
                         console.log("No CodeMirror mode: " + lang);
                         callback(err, code);
                     });
                 }
             });
         }
 
         this.element = $(selector);
         this.element.scroll();
         this.element.data("notebook", this);
         this.next_prompt_number = 1;
         this.session = null;
         this.kernel = null;
         this.clipboard = null;
         this.undelete_backup = null;
         this.undelete_index = null;
         this.undelete_below = false;
         this.paste_enabled = false;
         this.writable = false;
         // It is important to start out in command mode to match the intial mode
         // of the KeyboardManager.
         this.mode = 'command';
         this.set_dirty(false);
         this.metadata = {};
         this._checkpoint_after_save = false;
         this.last_checkpoint = null;
         this.checkpoints = [];
         this.autosave_interval = 0;
         this.autosave_timer = null;
         // autosave *at most* every two minutes
         this.minimum_autosave_interval = 120000;
         this.notebook_name_blacklist_re = /[\/\\:]/;
         this.nbformat = 4; // Increment this when changing the nbformat
         this.nbformat_minor = this.current_nbformat_minor = 0; // Increment this when changing the nbformat
         this.codemirror_mode = 'ipython';
         this.create_elements();
         this.bind_events();
         this.kernel_selector = null;
         this.dirty = null;
         this.trusted = null;
         this._fully_loaded = false;
 
         // Trigger cell toolbar registration.
         default_celltoolbar.register(this);
         rawcell_celltoolbar.register(this);
         slideshow_celltoolbar.register(this);
 
         // prevent assign to miss-typed properties.
         Object.seal(this);
     };
 
     Notebook.options_default = {
         // can be any cell type, or the special values of
         // 'above', 'below', or 'selected' to get the value from another cell.
         Notebook: {
             default_cell_type: 'code'
         }
     };
 
 
     /**
      * Create an HTML and CSS representation of the notebook.
      * 
      * @method create_elements
      */
     Notebook.prototype.create_elements = function () {
         var that = this;
         this.element.attr('tabindex','-1');
         this.container = $("<div/>").addClass("container").attr("id", "notebook-container");
         // We add this end_space div to the end of the notebook div to:
         // i) provide a margin between the last cell and the end of the notebook
         // ii) to prevent the div from scrolling up when the last cell is being
         // edited, but is too low on the page, which browsers will do automatically.
         var end_space = $('<div/>').addClass('end_space');
         end_space.dblclick(function (e) {
             var ncells = that.ncells();
             that.insert_cell_below('code',ncells-1);
         });
         this.element.append(this.container);
         this.container.append(end_space);
     };
 
     /**
      * Bind JavaScript events: key presses and custom IPython events.
      * 
      * @method bind_events
      */
     Notebook.prototype.bind_events = function () {
         var that = this;
 
         this.events.on('set_next_input.Notebook', function (event, data) {
             var index = that.find_cell_index(data.cell);
             var new_cell = that.insert_cell_below('code',index);
             new_cell.set_text(data.text);
             that.dirty = true;
         });
 
         this.events.on('unrecognized_cell.Cell', function () {
             that.warn_nbformat_minor();
         });
 
         this.events.on('unrecognized_output.OutputArea', function () {
             that.warn_nbformat_minor();
         });
 
         this.events.on('set_dirty.Notebook', function (event, data) {
             that.dirty = data.value;
         });
 
         this.events.on('trust_changed.Notebook', function (event, trusted) {
             that.trusted = trusted;
         });
 
         this.events.on('select.Cell', function (event, data) {
             var index = that.find_cell_index(data.cell);
             that.select(index);
         });
 
         this.events.on('edit_mode.Cell', function (event, data) {
             that.handle_edit_mode(data.cell);
         });
 
         this.events.on('command_mode.Cell', function (event, data) {
             that.handle_command_mode(data.cell);
         });
         
         this.events.on('spec_changed.Kernel', function(event, data) {
             that.metadata.kernelspec = 
                 {name: data.name, display_name: data.display_name};
         });
 
         this.events.on('kernel_ready.Kernel', function(event, data) {
             var kinfo = data.kernel.info_reply;
             var langinfo = kinfo.language_info || {};
             that.metadata.language_info = langinfo;
             // Mode 'null' should be plain, unhighlighted text.
             var cm_mode = langinfo.codemirror_mode || langinfo.name || 'null';
             that.set_codemirror_mode(cm_mode);
         });
 
         var collapse_time = function (time) {
             var app_height = $('#ipython-main-app').height(); // content height
             var splitter_height = $('div#pager_splitter').outerHeight(true);
             var new_height = app_height - splitter_height;
             that.element.animate({height : new_height + 'px'}, time);
         };
 
         this.element.bind('collapse_pager', function (event, extrap) {
             var time = (extrap !== undefined) ? ((extrap.duration !== undefined ) ? extrap.duration : 'fast') : 'fast';
             collapse_time(time);
         });
 
         var expand_time = function (time) {
             var app_height = $('#ipython-main-app').height(); // content height
             var splitter_height = $('div#pager_splitter').outerHeight(true);
             var pager_height = $('div#pager').outerHeight(true);
             var new_height = app_height - pager_height - splitter_height;
             that.element.animate({height : new_height + 'px'}, time);
         };
 
         this.element.bind('expand_pager', function (event, extrap) {
             var time = (extrap !== undefined) ? ((extrap.duration !== undefined ) ? extrap.duration : 'fast') : 'fast';
             expand_time(time);
         });
         
         // Firefox 22 broke $(window).on("beforeunload")
         // I'm not sure why or how.
         window.onbeforeunload = function (e) {
             // TODO: Make killing the kernel configurable.
             var kill_kernel = false;
             if (kill_kernel) {
                 that.session.delete();
             }
             // if we are autosaving, trigger an autosave on nav-away.
             // still warn, because if we don't the autosave may fail.
             if (that.dirty) {
                 if ( that.autosave_interval ) {
                     // schedule autosave in a timeout
                     // this gives you a chance to forcefully discard changes
                     // by reloading the page if you *really* want to.
                     // the timer doesn't start until you *dismiss* the dialog.
                     setTimeout(function () {
                         if (that.dirty) {
                             that.save_notebook();
                         }
                     }, 1000);
                     return "Autosave in progress, latest changes may be lost.";
                 } else {
                     return "Unsaved changes will be lost.";
                 }
             }
             // Null is the *only* return value that will make the browser not
             // pop up the "don't leave" dialog.
             return null;
         };
     };
     
     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;
         var msg = "This notebook is version " + orig_vs + ", but we only fully support up to " +
         this_vs + ".  You can still work with this notebook, but cell and output types " +
         "introduced in later notebook versions will not be available.";
 
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title : "Newer Notebook",
             body : msg,
             buttons : {
                 OK : {
                     "class" : "btn-danger"
                 }
             }
         });
     }
 
     /**
      * Set the dirty flag, and trigger the set_dirty.Notebook event
      * 
      * @method set_dirty
      */
     Notebook.prototype.set_dirty = function (value) {
         if (value === undefined) {
             value = true;
         }
         if (this.dirty == value) {
             return;
         }
         this.events.trigger('set_dirty.Notebook', {value: value});
     };
 
     /**
      * Scroll the top of the page to a given cell.
      * 
      * @method scroll_to_cell
      * @param {Number} cell_number An index of the cell to view
      * @param {Number} time Animation time in milliseconds
      * @return {Number} Pixel offset from the top of the container
      */
     Notebook.prototype.scroll_to_cell = function (cell_number, time) {
         var cells = this.get_cells();
         time = time || 0;
         cell_number = Math.min(cells.length-1,cell_number);
         cell_number = Math.max(0             ,cell_number);
         var scroll_value = cells[cell_number].element.position().top-cells[0].element.position().top ;
         this.element.animate({scrollTop:scroll_value}, time);
         return scroll_value;
     };
 
     /**
      * Scroll to the bottom of the page.
      * 
      * @method scroll_to_bottom
      */
     Notebook.prototype.scroll_to_bottom = function () {
         this.element.animate({scrollTop:this.element.get(0).scrollHeight}, 0);
     };
 
     /**
      * Scroll to the top of the page.
      * 
      * @method scroll_to_top
      */
     Notebook.prototype.scroll_to_top = function () {
         this.element.animate({scrollTop:0}, 0);
     };
 
     // Edit Notebook metadata
 
     Notebook.prototype.edit_metadata = function () {
         var that = this;
         dialog.edit_metadata({
             md: this.metadata, 
             callback: function (md) {
                 that.metadata = md;
             },
             name: 'Notebook',
             notebook: this,
             keyboard_manager: this.keyboard_manager});
     };
 
     // Cell indexing, retrieval, etc.
 
     /**
      * Get all cell elements in the notebook.
      * 
      * @method get_cell_elements
      * @return {jQuery} A selector of all cell elements
      */
     Notebook.prototype.get_cell_elements = function () {
         return this.container.find(".cell").not('.cell .cell');
     };
 
     /**
      * Get a particular cell element.
      * 
      * @method get_cell_element
      * @param {Number} index An index of a cell to select
      * @return {jQuery} A selector of the given cell.
      */
     Notebook.prototype.get_cell_element = function (index) {
         var result = null;
         var e = this.get_cell_elements().eq(index);
         if (e.length !== 0) {
             result = e;
         }
         return result;
     };
 
     /**
      * Try to get a particular cell by msg_id.
      * 
      * @method get_msg_cell
      * @param {String} msg_id A message UUID
      * @return {Cell} Cell or null if no cell was found.
      */
     Notebook.prototype.get_msg_cell = function (msg_id) {
         return codecell.CodeCell.msg_cells[msg_id] || null;
     };
 
     /**
      * Count the cells in this notebook.
      * 
      * @method ncells
      * @return {Number} The number of cells in this notebook
      */
     Notebook.prototype.ncells = function () {
         return this.get_cell_elements().length;
     };
 
     /**
      * Get all Cell objects in this notebook.
      * 
      * @method get_cells
      * @return {Array} This notebook's Cell objects
      */
     // TODO: we are often calling cells as cells()[i], which we should optimize
     // to cells(i) or a new method.
     Notebook.prototype.get_cells = function () {
         return this.get_cell_elements().toArray().map(function (e) {
             return $(e).data("cell");
         });
     };
 
     /**
      * Get a Cell object from this notebook.
      * 
      * @method get_cell
      * @param {Number} index An index of a cell to retrieve
      * @return {Cell} Cell or null if no cell was found.
      */
     Notebook.prototype.get_cell = function (index) {
         var result = null;
         var ce = this.get_cell_element(index);
         if (ce !== null) {
             result = ce.data('cell');
         }
         return result;
     };
 
     /**
      * Get the cell below a given cell.
      * 
      * @method get_next_cell
      * @param {Cell} cell The provided cell
      * @return {Cell} the next cell or null if no cell was found.
      */
     Notebook.prototype.get_next_cell = function (cell) {
         var result = null;
         var index = this.find_cell_index(cell);
         if (this.is_valid_cell_index(index+1)) {
             result = this.get_cell(index+1);
         }
         return result;
     };
 
     /**
      * Get the cell above a given cell.
      * 
      * @method get_prev_cell
      * @param {Cell} cell The provided cell
      * @return {Cell} The previous cell or null if no cell was found.
      */
     Notebook.prototype.get_prev_cell = function (cell) {
         var result = null;
         var index = this.find_cell_index(cell);
         if (index !== null && index > 0) {
             result = this.get_cell(index-1);
         }
         return result;
     };
     
     /**
      * Get the numeric index of a given cell.
      * 
      * @method find_cell_index
      * @param {Cell} cell The provided cell
      * @return {Number} The cell's numeric index or null if no cell was found.
      */
     Notebook.prototype.find_cell_index = function (cell) {
         var result = null;
         this.get_cell_elements().filter(function (index) {
             if ($(this).data("cell") === cell) {
                 result = index;
             }
         });
         return result;
     };
 
     /**
      * Get a given index , or the selected index if none is provided.
      * 
      * @method index_or_selected
      * @param {Number} index A cell's index
      * @return {Number} The given index, or selected index if none is provided.
      */
     Notebook.prototype.index_or_selected = function (index) {
         var i;
         if (index === undefined || index === null) {
             i = this.get_selected_index();
             if (i === null) {
                 i = 0;
             }
         } else {
             i = index;
         }
         return i;
     };
 
     /**
      * Get the currently selected cell.
      * @method get_selected_cell
      * @return {Cell} The selected cell
      */
     Notebook.prototype.get_selected_cell = function () {
         var index = this.get_selected_index();
         return this.get_cell(index);
     };
 
     /**
      * Check whether a cell index is valid.
      * 
      * @method is_valid_cell_index
      * @param {Number} index A cell index
      * @return True if the index is valid, false otherwise
      */
     Notebook.prototype.is_valid_cell_index = function (index) {
         if (index !== null && index >= 0 && index < this.ncells()) {
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * Get the index of the currently selected cell.
      
      * @method get_selected_index
      * @return {Number} The selected cell's numeric index
      */
     Notebook.prototype.get_selected_index = function () {
         var result = null;
         this.get_cell_elements().filter(function (index) {
             if ($(this).data("cell").selected === true) {
                 result = index;
             }
         });
         return result;
     };
 
 
     // Cell selection.
 
     /**
      * Programmatically select a cell.
      * 
      * @method select
      * @param {Number} index A cell's index
      * @return {Notebook} This notebook
      */
     Notebook.prototype.select = function (index) {
         if (this.is_valid_cell_index(index)) {
             var sindex = this.get_selected_index();
             if (sindex !== null && index !== sindex) {
                 // If we are about to select a different cell, make sure we are
                 // first in command mode.
                 if (this.mode !== 'command') {
                     this.command_mode();
                 }
                 this.get_cell(sindex).unselect();
             }
             var cell = this.get_cell(index);
             cell.select();
             if (cell.cell_type === 'heading') {
                 this.events.trigger('selected_cell_type_changed.Notebook',
                     {'cell_type':cell.cell_type,level:cell.level}
                 );
             } else {
                 this.events.trigger('selected_cell_type_changed.Notebook',
                     {'cell_type':cell.cell_type}
                 );
             }
         }
         return this;
     };
 
     /**
      * Programmatically select the next cell.
      *
      * @method select_next
      * @return {Notebook} This notebook
      */
     Notebook.prototype.select_next = function () {
         var index = this.get_selected_index();
         this.select(index+1);
         return this;
     };
 
     /**
      * Programmatically select the previous cell.
      *
      * @method select_prev
      * @return {Notebook} This notebook
      */
     Notebook.prototype.select_prev = function () {
         var index = this.get_selected_index();
         this.select(index-1);
         return this;
     };
 
 
     // Edit/Command mode
 
     /**
      * Gets the index of the cell that is in edit mode.
      *
      * @method get_edit_index
      *
      * @return index {int}
      **/
     Notebook.prototype.get_edit_index = function () {
         var result = null;
         this.get_cell_elements().filter(function (index) {
             if ($(this).data("cell").mode === 'edit') {
                 result = index;
             }
         });
         return result;
     };
 
     /**
      * Handle when a a cell blurs and the notebook should enter command mode.
      *
      * @method handle_command_mode
      * @param [cell] {Cell} Cell to enter command mode on.
      **/
     Notebook.prototype.handle_command_mode = function (cell) {
         if (this.mode !== 'command') {
             cell.command_mode();
             this.mode = 'command';
             this.events.trigger('command_mode.Notebook');
             this.keyboard_manager.command_mode();
         }
     };
 
     /**
      * Make the notebook enter command mode.
      *
      * @method command_mode
      **/
     Notebook.prototype.command_mode = function () {
         var cell = this.get_cell(this.get_edit_index());
         if (cell && this.mode !== 'command') {
             // We don't call cell.command_mode, but rather call cell.focus_cell()
             // which will blur and CM editor and trigger the call to
             // handle_command_mode.
             cell.focus_cell();
         }
     };
 
     /**
      * Handle when a cell fires it's edit_mode event.
      *
      * @method handle_edit_mode
      * @param [cell] {Cell} Cell to enter edit mode on.
      **/
     Notebook.prototype.handle_edit_mode = function (cell) {
         if (cell && this.mode !== 'edit') {
             cell.edit_mode();
             this.mode = 'edit';
             this.events.trigger('edit_mode.Notebook');
             this.keyboard_manager.edit_mode();
         }
     };
 
     /**
      * Make a cell enter edit mode.
      *
      * @method edit_mode
      **/
     Notebook.prototype.edit_mode = function () {
         var cell = this.get_selected_cell();
         if (cell && this.mode !== 'edit') {
             cell.unrender();
             cell.focus_editor();
         }
     };
 
     /**
      * Focus the currently selected cell.
      *
      * @method focus_cell
      **/
     Notebook.prototype.focus_cell = function () {
         var cell = this.get_selected_cell();
         if (cell === null) {return;}  // No cell is selected
         cell.focus_cell();
     };
 
     // Cell movement
 
     /**
      * Move given (or selected) cell up and select it.
      * 
      * @method move_cell_up
      * @param [index] {integer} cell index
      * @return {Notebook} This notebook
      **/
     Notebook.prototype.move_cell_up = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i) && i > 0) {
             var pivot = this.get_cell_element(i-1);
             var tomove = this.get_cell_element(i);
             if (pivot !== null && tomove !== null) {
                 tomove.detach();
                 pivot.before(tomove);
                 this.select(i-1);
                 var cell = this.get_selected_cell();
                 cell.focus_cell();
             }
             this.set_dirty(true);
         }
         return this;
     };
 
 
     /**
      * Move given (or selected) cell down and select it
      * 
      * @method move_cell_down
      * @param [index] {integer} cell index
      * @return {Notebook} This notebook
      **/
     Notebook.prototype.move_cell_down = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i) && this.is_valid_cell_index(i+1)) {
             var pivot = this.get_cell_element(i+1);
             var tomove = this.get_cell_element(i);
             if (pivot !== null && tomove !== null) {
                 tomove.detach();
                 pivot.after(tomove);
                 this.select(i+1);
                 var cell = this.get_selected_cell();
                 cell.focus_cell();
             }
         }
         this.set_dirty();
         return this;
     };
 
 
     // Insertion, deletion.
 
     /**
      * Delete a cell from the notebook.
      * 
      * @method delete_cell
      * @param [index] A cell's numeric index
      * @return {Notebook} This notebook
      */
     Notebook.prototype.delete_cell = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (!cell.is_deletable()) {
             return this;
         }
 
         this.undelete_backup = cell.toJSON();
         $('#undelete_cell').removeClass('disabled');
         if (this.is_valid_cell_index(i)) {
             var old_ncells = this.ncells();
             var ce = this.get_cell_element(i);
             ce.remove();
             if (i === 0) {
                 // Always make sure we have at least one cell.
                 if (old_ncells === 1) {
                     this.insert_cell_below('code');
                 }
                 this.select(0);
                 this.undelete_index = 0;
                 this.undelete_below = false;
             } else if (i === old_ncells-1 && i !== 0) {
                 this.select(i-1);
                 this.undelete_index = i - 1;
                 this.undelete_below = true;
             } else {
                 this.select(i);
                 this.undelete_index = i;
                 this.undelete_below = false;
             }
             this.events.trigger('delete.Cell', {'cell': cell, 'index': i});
             this.set_dirty(true);
         }
         return this;
     };
 
     /**
      * Restore the most recently deleted cell.
      * 
      * @method undelete
      */
     Notebook.prototype.undelete_cell = function() {
         if (this.undelete_backup !== null && this.undelete_index !== null) {
             var current_index = this.get_selected_index();
             if (this.undelete_index < current_index) {
                 current_index = current_index + 1;
             }
             if (this.undelete_index >= this.ncells()) {
                 this.select(this.ncells() - 1);
             }
             else {
                 this.select(this.undelete_index);
             }
             var cell_data = this.undelete_backup;
             var new_cell = null;
             if (this.undelete_below) {
                 new_cell = this.insert_cell_below(cell_data.cell_type);
             } else {
                 new_cell = this.insert_cell_above(cell_data.cell_type);
             }
             new_cell.fromJSON(cell_data);
             if (this.undelete_below) {
                 this.select(current_index+1);
             } else {
                 this.select(current_index);
             }
             this.undelete_backup = null;
             this.undelete_index = null;
         }
         $('#undelete_cell').addClass('disabled');
     };
 
     /**
      * Insert a cell so that after insertion the cell is at given index.
      *
      * If cell type is not provided, it will default to the type of the
      * currently active cell.
      *
      * Similar to insert_above, but index parameter is mandatory
      *
      * Index will be brought back into the accessible range [0,n]
      *
      * @method insert_cell_at_index
      * @param [type] {string} in ['code','markdown', 'raw'], defaults to 'code'
      * @param [index] {int} a valid index where to insert cell
      *
      * @return cell {cell|null} created cell or null
      **/
     Notebook.prototype.insert_cell_at_index = function(type, index){
 
         var ncells = this.ncells();
         index = Math.min(index, ncells);
         index = Math.max(index, 0);
         var cell = null;
         type = type || this.default_cell_type;
         if (type === 'above') {
             if (index > 0) {
                 type = this.get_cell(index-1).cell_type;
             } else {
                 type = 'code';
             }
         } else if (type === 'below') {
             if (index < ncells) {
                 type = this.get_cell(index).cell_type;
             } else {
                 type = 'code';
             }
         } else if (type === 'selected') {
             type = this.get_selected_cell().cell_type;
         }
 
         if (ncells === 0 || this.is_valid_cell_index(index) || index === ncells) {
             var cell_options = {
                 events: this.events, 
                 config: this.config, 
                 keyboard_manager: this.keyboard_manager, 
                 notebook: this,
                 tooltip: this.tooltip
             };
             switch(type) {
             case 'code':
                 cell = new codecell.CodeCell(this.kernel, cell_options);
                 cell.set_input_prompt();
                 break;
             case 'markdown':
                 cell = new textcell.MarkdownCell(cell_options);
                 break;
             case 'raw':
                 cell = new textcell.RawCell(cell_options);
                 break;
             default:
                 console.log("Unrecognized cell type: ", type, cellmod);
                 cell = new cellmod.UnrecognizedCell(cell_options);
             }
 
             if(this._insert_element_at_index(cell.element,index)) {
                 cell.render();
                 this.events.trigger('create.Cell', {'cell': cell, 'index': index});
                 cell.refresh();
                 // We used to select the cell after we refresh it, but there
                 // are now cases were this method is called where select is
                 // not appropriate. The selection logic should be handled by the
                 // caller of the the top level insert_cell methods.
                 this.set_dirty(true);
             }
         }
         return cell;
 
     };
 
     /**
      * Insert an element at given cell index.
      *
      * @method _insert_element_at_index
      * @param element {dom_element} a cell element
      * @param [index] {int} a valid index where to inser cell
      * @private
      *
      * return true if everything whent fine.
      **/
     Notebook.prototype._insert_element_at_index = function(element, index){
         if (element === undefined){
             return false;
         }
 
         var ncells = this.ncells();
 
         if (ncells === 0) {
             // special case append if empty
             this.element.find('div.end_space').before(element);
         } else if ( ncells === index ) {
             // special case append it the end, but not empty
             this.get_cell_element(index-1).after(element);
         } else if (this.is_valid_cell_index(index)) {
             // otherwise always somewhere to append to
             this.get_cell_element(index).before(element);
         } else {
             return false;
         }
 
         if (this.undelete_index !== null && index <= this.undelete_index) {
             this.undelete_index = this.undelete_index + 1;
             this.set_dirty(true);
         }
         return true;
     };
 
     /**
      * Insert a cell of given type above given index, or at top
      * of notebook if index smaller than 0.
      *
      * default index value is the one of currently selected cell
      *
      * @method insert_cell_above
      * @param [type] {string} cell type
      * @param [index] {integer}
      *
      * @return handle to created cell or null
      **/
     Notebook.prototype.insert_cell_above = function (type, index) {
         index = this.index_or_selected(index);
         return this.insert_cell_at_index(type, index);
     };
 
     /**
      * Insert a cell of given type below given index, or at bottom
      * of notebook if index greater than number of cells
      *
      * default index value is the one of currently selected cell
      *
      * @method insert_cell_below
      * @param [type] {string} cell type
      * @param [index] {integer}
      *
      * @return handle to created cell or null
      *
      **/
     Notebook.prototype.insert_cell_below = function (type, index) {
         index = this.index_or_selected(index);
         return this.insert_cell_at_index(type, index+1);
     };
 
 
     /**
      * Insert cell at end of notebook
      *
      * @method insert_cell_at_bottom
      * @param {String} type cell type
      *
      * @return the added cell; or null
      **/
     Notebook.prototype.insert_cell_at_bottom = function (type){
         var len = this.ncells();
         return this.insert_cell_below(type,len-1);
     };
 
     /**
      * Turn a cell into a code cell.
      * 
      * @method to_code
      * @param {Number} [index] A cell's index
      */
     Notebook.prototype.to_code = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i)) {
             var source_cell = this.get_cell(i);
             if (!(source_cell instanceof codecell.CodeCell)) {
                 var target_cell = this.insert_cell_below('code',i);
                 var text = source_cell.get_text();
                 if (text === source_cell.placeholder) {
                     text = '';
                 }
                 //metadata
                 target_cell.metadata = source_cell.metadata;
 
                 target_cell.set_text(text);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 target_cell.code_mirror.clearHistory();
                 source_cell.element.remove();
                 this.select(i);
                 var cursor = source_cell.code_mirror.getCursor();
                 target_cell.code_mirror.setCursor(cursor);
                 this.set_dirty(true);
             }
         }
     };
 
     /**
      * Turn a cell into a Markdown cell.
      * 
      * @method to_markdown
      * @param {Number} [index] A cell's index
      */
     Notebook.prototype.to_markdown = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i)) {
             var source_cell = this.get_cell(i);
 
             if (!(source_cell instanceof textcell.MarkdownCell)) {
                 var target_cell = this.insert_cell_below('markdown',i);
                 var text = source_cell.get_text();
 
                 if (text === source_cell.placeholder) {
                     text = '';
                 }
                 // metadata
                 target_cell.metadata = source_cell.metadata;
                 // We must show the editor before setting its contents
                 target_cell.unrender();
                 target_cell.set_text(text);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 target_cell.code_mirror.clearHistory();
                 source_cell.element.remove();
                 this.select(i);
                 if ((source_cell instanceof textcell.TextCell) && source_cell.rendered) {
                     target_cell.render();
                 }
                 var cursor = source_cell.code_mirror.getCursor();
                 target_cell.code_mirror.setCursor(cursor);
                 this.set_dirty(true);
             }
         }
     };
 
     /**
      * Turn a cell into a raw text cell.
      * 
      * @method to_raw
      * @param {Number} [index] A cell's index
      */
     Notebook.prototype.to_raw = function (index) {
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i)) {
             var target_cell = null;
             var source_cell = this.get_cell(i);
 
             if (!(source_cell instanceof textcell.RawCell)) {
                 target_cell = this.insert_cell_below('raw',i);
                 var text = source_cell.get_text();
                 if (text === source_cell.placeholder) {
                     text = '';
                 }
                 //metadata
                 target_cell.metadata = source_cell.metadata;
                 // We must show the editor before setting its contents
                 target_cell.unrender();
                 target_cell.set_text(text);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 target_cell.code_mirror.clearHistory();
                 source_cell.element.remove();
                 this.select(i);
                 var cursor = source_cell.code_mirror.getCursor();
                 target_cell.code_mirror.setCursor(cursor);
                 this.set_dirty(true);
             }
         }
     };
     
     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,
             title : "Use markdown headings",
             body : $("<p/>").text(
                 'IPython no longer uses special heading cells. ' + 
                 'Instead, write your headings in Markdown cells using # characters:'
             ).append($('<pre/>').text(
                 '## This is a level 2 heading'
             )),
             buttons : {
                 "OK" : {}
             }
         });
     };
     
     /**
      * Turn a cell into a markdown cell with a heading.
      * 
      * @method to_heading
      * @param {Number} [index] A cell's index
      * @param {Number} [level] A heading level (e.g., 1 for h1)
      */
     Notebook.prototype.to_heading = function (index, level) {
         this.to_markdown(index);
         level = level || 1;
         var i = this.index_or_selected(index);
         if (this.is_valid_cell_index(i)) {
             var cell = this.get_cell(i);
             cell.set_heading_level(level);
             this.set_dirty(true);
         }
     };
 
 
     // Cut/Copy/Paste
 
     /**
      * Enable UI elements for pasting cells.
      * 
      * @method enable_paste
      */
     Notebook.prototype.enable_paste = function () {
         var that = this;
         if (!this.paste_enabled) {
             $('#paste_cell_replace').removeClass('disabled')
                 .on('click', function () {that.paste_cell_replace();});
             $('#paste_cell_above').removeClass('disabled')
                 .on('click', function () {that.paste_cell_above();});
             $('#paste_cell_below').removeClass('disabled')
                 .on('click', function () {that.paste_cell_below();});
             this.paste_enabled = true;
         }
     };
 
     /**
      * Disable UI elements for pasting cells.
      * 
      * @method disable_paste
      */
     Notebook.prototype.disable_paste = function () {
         if (this.paste_enabled) {
             $('#paste_cell_replace').addClass('disabled').off('click');
             $('#paste_cell_above').addClass('disabled').off('click');
             $('#paste_cell_below').addClass('disabled').off('click');
             this.paste_enabled = false;
         }
     };
 
     /**
      * Cut a cell.
      * 
      * @method cut_cell
      */
     Notebook.prototype.cut_cell = function () {
         this.copy_cell();
         this.delete_cell();
     };
 
     /**
      * Copy a cell.
      * 
      * @method copy_cell
      */
     Notebook.prototype.copy_cell = function () {
         var cell = this.get_selected_cell();
         this.clipboard = cell.toJSON();
         // remove undeletable status from the copied cell
         if (this.clipboard.metadata.deletable !== undefined) {
             delete this.clipboard.metadata.deletable;
         }
         this.enable_paste();
     };
 
     /**
      * Replace the selected cell with a cell in the clipboard.
      * 
      * @method paste_cell_replace
      */
     Notebook.prototype.paste_cell_replace = function () {
         if (this.clipboard !== null && this.paste_enabled) {
             var cell_data = this.clipboard;
             var new_cell = this.insert_cell_above(cell_data.cell_type);
             new_cell.fromJSON(cell_data);
             var old_cell = this.get_next_cell(new_cell);
             this.delete_cell(this.find_cell_index(old_cell));
             this.select(this.find_cell_index(new_cell));
         }
     };
 
     /**
      * Paste a cell from the clipboard above the selected cell.
      * 
      * @method paste_cell_above
      */
     Notebook.prototype.paste_cell_above = function () {
         if (this.clipboard !== null && this.paste_enabled) {
             var cell_data = this.clipboard;
             var new_cell = this.insert_cell_above(cell_data.cell_type);
             new_cell.fromJSON(cell_data);
             new_cell.focus_cell();
         }
     };
 
     /**
      * Paste a cell from the clipboard below the selected cell.
      * 
      * @method paste_cell_below
      */
     Notebook.prototype.paste_cell_below = function () {
         if (this.clipboard !== null && this.paste_enabled) {
             var cell_data = this.clipboard;
             var new_cell = this.insert_cell_below(cell_data.cell_type);
             new_cell.fromJSON(cell_data);
             new_cell.focus_cell();
         }
     };
 
     // Split/merge
 
     /**
      * Split the selected cell into two, at the cursor.
      * 
      * @method split_cell
      */
     Notebook.prototype.split_cell = function () {
         var cell = this.get_selected_cell();
         if (cell.is_splittable()) {
             var texta = cell.get_pre_cursor();
             var textb = cell.get_post_cursor();
             cell.set_text(textb);
             var new_cell = this.insert_cell_above(cell.cell_type);
             // Unrender the new cell so we can call set_text.
             new_cell.unrender();
             new_cell.set_text(texta);
         }
     };
 
     /**
      * Combine the selected cell into the cell above it.
      * 
      * @method merge_cell_above
      */
     Notebook.prototype.merge_cell_above = function () {
         var index = this.get_selected_index();
         var cell = this.get_cell(index);
         var render = cell.rendered;
         if (!cell.is_mergeable()) {
             return;
         }
         if (index > 0) {
             var upper_cell = this.get_cell(index-1);
             if (!upper_cell.is_mergeable()) {
                 return;
             }
             var upper_text = upper_cell.get_text();
             var text = cell.get_text();
             if (cell instanceof codecell.CodeCell) {
                 cell.set_text(upper_text+'\n'+text);
             } else {
                 cell.unrender(); // Must unrender before we set_text.
                 cell.set_text(upper_text+'\n\n'+text);
                 if (render) {
                     // The rendered state of the final cell should match
                     // that of the original selected cell;
                     cell.render();
                 }
             }
             this.delete_cell(index-1);
             this.select(this.find_cell_index(cell));
         }
     };
 
     /**
      * Combine the selected cell into the cell below it.
      * 
      * @method merge_cell_below
      */
     Notebook.prototype.merge_cell_below = function () {
         var index = this.get_selected_index();
         var cell = this.get_cell(index);
         var render = cell.rendered;
         if (!cell.is_mergeable()) {
             return;
         }
         if (index < this.ncells()-1) {
             var lower_cell = this.get_cell(index+1);
             if (!lower_cell.is_mergeable()) {
                 return;
             }
             var lower_text = lower_cell.get_text();
             var text = cell.get_text();
             if (cell instanceof codecell.CodeCell) {
                 cell.set_text(text+'\n'+lower_text);
             } else {
                 cell.unrender(); // Must unrender before we set_text.
                 cell.set_text(text+'\n\n'+lower_text);
                 if (render) {
                     // The rendered state of the final cell should match
                     // that of the original selected cell;
                     cell.render();
                 }
             }
             this.delete_cell(index+1);
             this.select(this.find_cell_index(cell));
         }
     };
 
 
     // Cell collapsing and output clearing
 
     /**
      * Hide a cell's output.
      * 
      * @method collapse_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.collapse_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.collapse_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Hide each code cell's output area.
      * 
      * @method collapse_all_output
      */
     Notebook.prototype.collapse_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.collapse_output();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     /**
      * Show a cell's output.
      * 
      * @method expand_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.expand_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.expand_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Expand each code cell's output area, and remove scrollbars.
      * 
      * @method expand_all_output
      */
     Notebook.prototype.expand_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.expand_output();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     /**
      * Clear the selected CodeCell's output area.
      * 
      * @method clear_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.clear_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.clear_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Clear each code cell's output area.
      * 
      * @method clear_all_output
      */
     Notebook.prototype.clear_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.clear_output();
             }
         });
         this.set_dirty(true);
     };
 
     /**
      * Scroll the selected CodeCell's output area.
      * 
      * @method scroll_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.scroll_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.scroll_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Expand each code cell's output area, and add a scrollbar for long output.
      * 
      * @method scroll_all_output
      */
     Notebook.prototype.scroll_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.scroll_output();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     /** Toggle whether a cell's output is collapsed or expanded.
      * 
      * @method toggle_output
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.toggle_output = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.toggle_output();
             this.set_dirty(true);
         }
     };
 
     /**
      * Hide/show the output of all cells.
      * 
      * @method toggle_all_output
      */
     Notebook.prototype.toggle_all_output = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.toggle_output();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     /**
      * Toggle a scrollbar for long cell outputs.
      * 
      * @method toggle_output_scroll
      * @param {Number} index A cell's numeric index
      */
     Notebook.prototype.toggle_output_scroll = function (index) {
         var i = this.index_or_selected(index);
         var cell = this.get_cell(i);
         if (cell !== null && (cell instanceof codecell.CodeCell)) {
             cell.toggle_output_scroll();
             this.set_dirty(true);
         }
     };
 
     /**
      * Toggle the scrolling of long output on all cells.
      * 
      * @method toggle_all_output_scrolling
      */
     Notebook.prototype.toggle_all_output_scroll = function () {
         this.get_cells().map(function (cell, i) {
             if (cell instanceof codecell.CodeCell) {
                 cell.toggle_output_scroll();
             }
         });
         // this should not be set if the `collapse` key is removed from nbformat
         this.set_dirty(true);
     };
 
     // Other cell functions: line numbers, ...
 
     /**
      * Toggle line numbers in the selected cell's input area.
      * 
      * @method cell_toggle_line_numbers
      */
     Notebook.prototype.cell_toggle_line_numbers = function() {
         this.get_selected_cell().toggle_line_numbers();
     };
     
     /**
      * Set the codemirror mode for all code cells, including the default for
      * new code cells.
      * 
      * @method set_codemirror_mode
      */
     Notebook.prototype.set_codemirror_mode = function(newmode){
         if (newmode === this.codemirror_mode) {
             return;
         }
         this.codemirror_mode = newmode;
         codecell.CodeCell.options_default.cm_config.mode = newmode;
         var modename = newmode.mode || newmode.name || newmode;
         
         var that = this;
         utils.requireCodeMirrorMode(modename, function () {
             that.get_cells().map(function(cell, i) {
                 if (cell.cell_type === 'code'){
                     cell.code_mirror.setOption('mode', newmode);
                     // This is currently redundant, because cm_config ends up as
                     // codemirror's own .options object, but I don't want to
                     // rely on that.
                     cell.cm_config.mode = newmode;
                 }
             });
         });
     };
 
     // Session related things
 
     /**
      * Start a new session and set it on each code cell.
      * 
      * @method start_session
      */
     Notebook.prototype.start_session = function (kernel_name) {
         if (this._session_starting) {
             throw new session.SessionAlreadyStarting();
         }
         this._session_starting = true;
 
         var options = {
             base_url: this.base_url,
             ws_url: this.ws_url,
             notebook_path: this.notebook_path,
             notebook_name: this.notebook_name,
             kernel_name: kernel_name,
             notebook: this
         };
 
         var success = $.proxy(this._session_started, this);
         var failure = $.proxy(this._session_start_failed, this);
 
         if (this.session !== null) {
             this.session.restart(options, success, failure);
         } else {
             this.session = new session.Session(options);
             this.session.start(success, failure);
         }
     };
 
 
     /**
      * Once a session is started, link the code cells to the kernel and pass the 
      * comm manager to the widget manager
      *
      */
     Notebook.prototype._session_started = function (){
         this._session_starting = false;
         this.kernel = this.session.kernel;
         var ncells = this.ncells();
         for (var i=0; i<ncells; i++) {
             var cell = this.get_cell(i);
             if (cell instanceof codecell.CodeCell) {
                 cell.set_kernel(this.session.kernel);
             }
         }
     };
     Notebook.prototype._session_start_failed = function (jqxhr, status, error){
         this._session_starting = false;
         utils.log_ajax_error(jqxhr, status, error);
     };
     
     /**
      * Prompt the user to restart the IPython kernel.
      * 
      * @method restart_kernel
      */
     Notebook.prototype.restart_kernel = function () {
         var that = this;
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title : "Restart kernel or continue running?",
             body : $("<p/>").text(
                 'Do you want to restart the current kernel?  You will lose all variables defined in it.'
             ),
             buttons : {
                 "Continue running" : {},
                 "Restart" : {
                     "class" : "btn-danger",
                     "click" : function() {
                         that.kernel.restart();
                     }
                 }
             }
         });
     };
     
     /**
      * Execute or render cell outputs and go into command mode.
      * 
      * @method execute_cell
      */
     Notebook.prototype.execute_cell = function () {
-        // mode = shift, ctrl, alt
+        /**
+         * mode = shift, ctrl, alt
+         */
         var cell = this.get_selected_cell();
         
         cell.execute();
         this.command_mode();
         this.set_dirty(true);
     };
 
     /**
      * Execute or render cell outputs and insert a new cell below.
      * 
      * @method execute_cell_and_insert_below
      */
     Notebook.prototype.execute_cell_and_insert_below = function () {
         var cell = this.get_selected_cell();
         var cell_index = this.find_cell_index(cell);
         
         cell.execute();
 
         // If we are at the end always insert a new cell and return
         if (cell_index === (this.ncells()-1)) {
             this.command_mode();
             this.insert_cell_below();
             this.select(cell_index+1);
             this.edit_mode();
             this.scroll_to_bottom();
             this.set_dirty(true);
             return;
         }
 
         this.command_mode();
         this.insert_cell_below();
         this.select(cell_index+1);
         this.edit_mode();
         this.set_dirty(true);
     };
 
     /**
      * Execute or render cell outputs and select the next cell.
      * 
      * @method execute_cell_and_select_below
      */
     Notebook.prototype.execute_cell_and_select_below = function () {
 
         var cell = this.get_selected_cell();
         var cell_index = this.find_cell_index(cell);
         
         cell.execute();
 
         // If we are at the end always insert a new cell and return
         if (cell_index === (this.ncells()-1)) {
             this.command_mode();
             this.insert_cell_below();
             this.select(cell_index+1);
             this.edit_mode();
             this.scroll_to_bottom();
             this.set_dirty(true);
             return;
         }
 
         this.command_mode();
         this.select(cell_index+1);
         this.focus_cell();
         this.set_dirty(true);
     };
 
     /**
      * Execute all cells below the selected cell.
      * 
      * @method execute_cells_below
      */
     Notebook.prototype.execute_cells_below = function () {
         this.execute_cell_range(this.get_selected_index(), this.ncells());
         this.scroll_to_bottom();
     };
 
     /**
      * Execute all cells above the selected cell.
      * 
      * @method execute_cells_above
      */
     Notebook.prototype.execute_cells_above = function () {
         this.execute_cell_range(0, this.get_selected_index());
     };
 
     /**
      * Execute all cells.
      * 
      * @method execute_all_cells
      */
     Notebook.prototype.execute_all_cells = function () {
         this.execute_cell_range(0, this.ncells());
         this.scroll_to_bottom();
     };
 
     /**
      * Execute a contiguous range of cells.
      * 
      * @method execute_cell_range
      * @param {Number} start Index of the first cell to execute (inclusive)
      * @param {Number} end Index of the last cell to execute (exclusive)
      */
     Notebook.prototype.execute_cell_range = function (start, end) {
         this.command_mode();
         for (var i=start; i<end; i++) {
             this.select(i);
             this.execute_cell();
         }
     };
 
     // Persistance and loading
 
     /**
      * Getter method for this notebook's name.
      * 
      * @method get_notebook_name
      * @return {String} This notebook's name (excluding file extension)
      */
     Notebook.prototype.get_notebook_name = function () {
         var nbname = this.notebook_name.substring(0,this.notebook_name.length-6);
         return nbname;
     };
 
     /**
      * Setter method for this notebook's name.
      *
      * @method set_notebook_name
      * @param {String} name A new name for this notebook
      */
     Notebook.prototype.set_notebook_name = function (name) {
         var parent = utils.url_path_split(this.notebook_path)[0];
         this.notebook_name = name;
         this.notebook_path = utils.url_path_join(parent, name);
     };
 
     /**
      * Check that a notebook's name is valid.
      * 
      * @method test_notebook_name
      * @param {String} nbname A name for this notebook
      * @return {Boolean} True if the name is valid, false if invalid
      */
     Notebook.prototype.test_notebook_name = function (nbname) {
         nbname = nbname || '';
         if (nbname.length>0 && !this.notebook_name_blacklist_re.test(nbname)) {
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * Load a notebook from JSON (.ipynb).
      * 
      * @method fromJSON
      * @param {Object} data JSON representation of a notebook
      */
     Notebook.prototype.fromJSON = function (data) {
 
         var content = data.content;
         var ncells = this.ncells();
         var i;
         for (i=0; i<ncells; i++) {
             // Always delete cell 0 as they get renumbered as they are deleted.
             this.delete_cell(0);
         }
         // Save the metadata and name.
         this.metadata = content.metadata;
         this.notebook_name = data.name;
         this.notebook_path = data.path;
         var trusted = true;
         
         // Trigger an event changing the kernel spec - this will set the default
         // codemirror mode
         if (this.metadata.kernelspec !== undefined) {
             this.events.trigger('spec_changed.Kernel', this.metadata.kernelspec);
         }
         
         // Set the codemirror mode from language_info metadata
         if (this.metadata.language_info !== undefined) {
             var langinfo = this.metadata.language_info;
             // Mode 'null' should be plain, unhighlighted text.
             var cm_mode = langinfo.codemirror_mode || langinfo.name || 'null';
             this.set_codemirror_mode(cm_mode);
         }
         
         var new_cells = content.cells;
         ncells = new_cells.length;
         var cell_data = null;
         var new_cell = null;
         for (i=0; i<ncells; i++) {
             cell_data = new_cells[i];
             new_cell = this.insert_cell_at_index(cell_data.cell_type, i);
             new_cell.fromJSON(cell_data);
             if (new_cell.cell_type == 'code' && !new_cell.output_area.trusted) {
                 trusted = false;
             }
         }
         if (trusted !== this.trusted) {
             this.trusted = trusted;
             this.events.trigger("trust_changed.Notebook", trusted);
         }
     };
 
     /**
      * Dump this notebook into a JSON-friendly object.
      * 
      * @method toJSON
      * @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;
 
         var cells = this.get_cells();
         var ncells = cells.length;
         var cell_array = new Array(ncells);
         var trusted = true;
         for (var i=0; i<ncells; i++) {
             var cell = cells[i];
             if (cell.cell_type == 'code' && !cell.output_area.trusted) {
                 trusted = false;
             }
             cell_array[i] = cell.toJSON();
         }
         var data = {
             cells: cell_array,
             metadata: this.metadata,
             nbformat: this.nbformat,
             nbformat_minor: this.nbformat_minor
         };
         if (trusted != this.trusted) {
             this.trusted = trusted;
             this.events.trigger("trust_changed.Notebook", trusted);
         }
         return data;
     };
 
     /**
      * Start an autosave timer, for periodically saving the notebook.
      * 
      * @method set_autosave_interval
      * @param {Integer} interval the autosave interval in milliseconds
      */
     Notebook.prototype.set_autosave_interval = function (interval) {
         var that = this;
         // clear previous interval, so we don't get simultaneous timers
         if (this.autosave_timer) {
             clearInterval(this.autosave_timer);
         }
         if (!this.writable) {
             // disable autosave if not writable
             interval = 0;
         }
         
         this.autosave_interval = this.minimum_autosave_interval = interval;
         if (interval) {
             this.autosave_timer = setInterval(function() {
                 if (that.dirty) {
                     that.save_notebook();
                 }
             }, interval);
             this.events.trigger("autosave_enabled.Notebook", interval);
         } else {
             this.autosave_timer = null;
             this.events.trigger("autosave_disabled.Notebook");
         }
     };
     
     /**
      * Save this notebook on the server. This becomes a notebook instance's
      * .save_notebook method *after* the entire notebook has been loaded.
      * 
      * @method save_notebook
      */
     Notebook.prototype.save_notebook = function () {
         if (!this._fully_loaded) {
             this.events.trigger('notebook_save_failed.Notebook',
                 new Error("Load failed, save is disabled")
             );
             return;
         } else if (!this.writable) {
             this.events.trigger('notebook_save_failed.Notebook',
                 new Error("Notebook is read-only")
             );
             return;
         }
 
         // Create a JSON model to be sent to the server.
         var model = {
             type : "notebook",
             content : this.toJSON()
         };
         // time the ajax call for autosave tuning purposes.
         var start =  new Date().getTime();
 
         var that = this;
         return this.contents.save(this.notebook_path, model).then(
                 $.proxy(this.save_notebook_success, this, start),
                 function (error) {
                     that.events.trigger('notebook_save_failed.Notebook', error);
                 }
             );
     };
     
     /**
      * Success callback for saving a notebook.
      * 
      * @method save_notebook_success
      * @param {Integer} start Time when the save request start
      * @param {Object} data JSON representation of a notebook
      */
     Notebook.prototype.save_notebook_success = function (start, data) {
         this.set_dirty(false);
         if (data.message) {
             // save succeeded, but validation failed.
             var body = $("<div>");
             var title = "Notebook validation failed";
 
             body.append($("<p>").text(
                 "The save operation succeeded," +
                 " but the notebook does not appear to be valid." +
                 " The validation error was:"
             )).append($("<div>").addClass("validation-error").append(
                 $("<pre>").text(data.message)
             ));
             dialog.modal({
                 notebook: this,
                 keyboard_manager: this.keyboard_manager,
                 title: title,
                 body: body,
                 buttons : {
                     OK : {
                         "class" : "btn-primary"
                     }
                 }
             });
         }
         this.events.trigger('notebook_saved.Notebook');
         this._update_autosave_interval(start);
         if (this._checkpoint_after_save) {
             this.create_checkpoint();
             this._checkpoint_after_save = false;
         }
     };
     
     /**
      * update the autosave interval based on how long the last save took
      * 
      * @method _update_autosave_interval
      * @param {Integer} timestamp when the save request started
      */
     Notebook.prototype._update_autosave_interval = function (start) {
         var duration = (new Date().getTime() - start);
         if (this.autosave_interval) {
             // new save interval: higher of 10x save duration or parameter (default 30 seconds)
             var interval = Math.max(10 * duration, this.minimum_autosave_interval);
             // round to 10 seconds, otherwise we will be setting a new interval too often
             interval = 10000 * Math.round(interval / 10000);
             // set new interval, if it's changed
             if (interval != this.autosave_interval) {
                 this.set_autosave_interval(interval);
             }
         }
     };
 
     /**
      * Explicitly trust the output of this notebook.
      *
      * @method trust_notebook
      */
     Notebook.prototype.trust_notebook = function () {
         var body = $("<div>").append($("<p>")
             .text("A trusted IPython notebook may execute hidden malicious code ")
             .append($("<strong>")
                 .append(
                     $("<em>").text("when you open it")
                 )
             ).append(".").append(
                 " Selecting trust will immediately reload this notebook in a trusted state."
             ).append(
                 " For more information, see the "
             ).append($("<a>").attr("href", "http://ipython.org/ipython-doc/2/notebook/security.html")
                 .text("IPython security documentation")
             ).append(".")
         );
 
         var nb = this;
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title: "Trust this notebook?",
             body: body,
 
             buttons: {
                 Cancel : {},
                 Trust : {
                     class : "btn-danger",
                     click : function () {
                         var cells = nb.get_cells();
                         for (var i = 0; i < cells.length; i++) {
                             var cell = cells[i];
                             if (cell.cell_type == 'code') {
                                 cell.output_area.trusted = true;
                             }
                         }
                         nb.events.on('notebook_saved.Notebook', function () {
                             window.location.reload();
                         });
                         nb.save_notebook();
                     }
                 }
             }
         });
     };
 
     Notebook.prototype.copy_notebook = function () {
         var that = this;
         var base_url = this.base_url;
         var w = window.open();
         var parent = utils.url_path_split(this.notebook_path)[0];
         this.contents.copy(this.notebook_path, parent).then(
             function (data) {
                 w.location = utils.url_join_encode(
                     base_url, 'notebooks', data.path
                 );
             },
             function(error) {
                 w.close();
                 that.events.trigger('notebook_copy_failed', error);
             }
         );
     };
 
     Notebook.prototype.rename = function (new_name) {
         if (!new_name.match(/\.ipynb$/)) {
             new_name = new_name + ".ipynb";
         }
 
         var that = this;
         var parent = utils.url_path_split(this.notebook_path)[0];
         var new_path = utils.url_path_join(parent, new_name);
         return this.contents.rename(this.notebook_path, new_path).then(
             function (json) {
                 that.notebook_name = json.name;
                 that.notebook_path = json.path;
                 that.session.rename_notebook(json.path);
                 that.events.trigger('notebook_renamed.Notebook', json);
             }
         );
     };
 
     Notebook.prototype.delete = function () {
         this.contents.delete(this.notebook_path);
     };
 
     /**
      * Request a notebook's data from the server.
      * 
      * @method load_notebook
      * @param {String} notebook_path A notebook to load
      */
     Notebook.prototype.load_notebook = function (notebook_path) {
         this.notebook_path = notebook_path;
         this.notebook_name = utils.url_path_split(this.notebook_path)[1];
         this.events.trigger('notebook_loading.Notebook');
         this.contents.get(notebook_path, {type: 'notebook'}).then(
             $.proxy(this.load_notebook_success, this),
             $.proxy(this.load_notebook_error, this)
         );
     };
 
     /**
      * Success callback for loading a notebook from the server.
      * 
      * Load notebook data from the JSON response.
      * 
      * @method load_notebook_success
      * @param {Object} data JSON representation of a notebook
      */
     Notebook.prototype.load_notebook_success = function (data) {
         var failed, msg;
         try {
             this.fromJSON(data);
         } catch (e) {
             failed = e;
             console.log("Notebook failed to load from JSON:", e);
         }
         if (failed || data.message) {
             // *either* fromJSON failed or validation failed
             var body = $("<div>");
             var title;
             if (failed) {
                 title = "Notebook failed to load";
                 body.append($("<p>").text(
                     "The error was: "
                 )).append($("<div>").addClass("js-error").text(
                     failed.toString()
                 )).append($("<p>").text(
                     "See the error console for details."
                 ));
             } else {
                 title = "Notebook validation failed";
             }
 
             if (data.message) {
                 if (failed) {
                     msg = "The notebook also failed validation:";
                 } else {
                     msg = "An invalid notebook may not function properly." +
                     " The validation error was:";
                 }
                 body.append($("<p>").text(
                     msg
                 )).append($("<div>").addClass("validation-error").append(
                     $("<pre>").text(data.message)
                 ));
             }
 
             dialog.modal({
                 notebook: this,
                 keyboard_manager: this.keyboard_manager,
                 title: title,
                 body: body,
                 buttons : {
                     OK : {
                         "class" : "btn-primary"
                     }
                 }
             });
         }
         if (this.ncells() === 0) {
             this.insert_cell_below('code');
             this.edit_mode(0);
         } else {
             this.select(0);
             this.handle_command_mode(this.get_cell(0));
         }
         this.set_dirty(false);
         this.scroll_to_top();
         this.writable = data.writable || false;
         var nbmodel = data.content;
         var orig_nbformat = nbmodel.metadata.orig_nbformat;
         var orig_nbformat_minor = nbmodel.metadata.orig_nbformat_minor;
         if (orig_nbformat !== undefined && nbmodel.nbformat !== orig_nbformat) {
             var src;
             if (nbmodel.nbformat > orig_nbformat) {
                 src = " an older notebook format ";
             } else {
                 src = " a newer notebook format ";
             }
             
             msg = "This notebook has been converted from" + src +
             "(v"+orig_nbformat+") to the current notebook " +
             "format (v"+nbmodel.nbformat+"). The next time you save this notebook, the " +
             "current notebook format will be used.";
             
             if (nbmodel.nbformat > orig_nbformat) {
                 msg += " Older versions of IPython may not be able to read the new format.";
             } else {
                 msg += " Some features of the original notebook may not be available.";
             }
             msg += " To preserve the original version, close the " +
                 "notebook without saving it.";
             dialog.modal({
                 notebook: this,
                 keyboard_manager: this.keyboard_manager,
                 title : "Notebook converted",
                 body : msg,
                 buttons : {
                     OK : {
                         class : "btn-primary"
                     }
                 }
             });
         } else if (this.nbformat_minor < nbmodel.nbformat_minor) {
             this.nbformat_minor = nbmodel.nbformat_minor;
         }
         
         // Create the session after the notebook is completely loaded to prevent
         // code execution upon loading, which is a security risk.
         if (this.session === null) {
             var kernelspec = this.metadata.kernelspec || {};
             var kernel_name = kernelspec.name;
 
             this.start_session(kernel_name);
         }
         // load our checkpoint list
         this.list_checkpoints();
         
         // load toolbar state
         if (this.metadata.celltoolbar) {
             celltoolbar.CellToolbar.global_show();
             celltoolbar.CellToolbar.activate_preset(this.metadata.celltoolbar);
         } else {
             celltoolbar.CellToolbar.global_hide();
         }
         
         if (!this.writable) {
             this.set_autosave_interval(0);
             this.events.trigger('notebook_read_only.Notebook');
         }
         
         // now that we're fully loaded, it is safe to restore save functionality
         this._fully_loaded = true;
         this.events.trigger('notebook_loaded.Notebook');
     };
 
     /**
      * Failure callback for loading a notebook from the server.
      * 
      * @method load_notebook_error
      * @param {Error} error
      */
     Notebook.prototype.load_notebook_error = function (error) {
         this.events.trigger('notebook_load_failed.Notebook', error);
         var msg;
         if (error.name === utils.XHR_ERROR && error.xhr.status === 500) {
             utils.log_ajax_error(error.xhr, error.xhr_status, error.xhr_error);
             msg = "An unknown error occurred while loading this notebook. " +
             "This version can load notebook formats " +
             "v" + this.nbformat + " or earlier. See the server log for details.";
         } else {
             msg = error.message;
         }
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title: "Error loading notebook",
             body : msg,
             buttons : {
                 "OK": {}
             }
         });
     };
 
     /*********************  checkpoint-related  *********************/
     
     /**
      * Save the notebook then immediately create a checkpoint.
      * 
      * @method save_checkpoint
      */
     Notebook.prototype.save_checkpoint = function () {
         this._checkpoint_after_save = true;
         this.save_notebook();
     };
     
     /**
      * Add a checkpoint for this notebook.
      * for use as a callback from checkpoint creation.
      * 
      * @method add_checkpoint
      */
     Notebook.prototype.add_checkpoint = function (checkpoint) {
         var found = false;
         for (var i = 0; i < this.checkpoints.length; i++) {
             var existing = this.checkpoints[i];
             if (existing.id == checkpoint.id) {
                 found = true;
                 this.checkpoints[i] = checkpoint;
                 break;
             }
         }
         if (!found) {
             this.checkpoints.push(checkpoint);
         }
         this.last_checkpoint = this.checkpoints[this.checkpoints.length - 1];
     };
     
     /**
      * List checkpoints for this notebook.
      * 
      * @method list_checkpoints
      */
     Notebook.prototype.list_checkpoints = function () {
         var that = this;
         this.contents.list_checkpoints(this.notebook_path).then(
             $.proxy(this.list_checkpoints_success, this),
             function(error) {
                 that.events.trigger('list_checkpoints_failed.Notebook', error);
             }
         );
     };
 
     /**
      * Success callback for listing checkpoints.
      * 
      * @method list_checkpoint_success
      * @param {Object} data JSON representation of a checkpoint
      */
     Notebook.prototype.list_checkpoints_success = function (data) {
         this.checkpoints = data;
         if (data.length) {
             this.last_checkpoint = data[data.length - 1];
         } else {
             this.last_checkpoint = null;
         }
         this.events.trigger('checkpoints_listed.Notebook', [data]);
     };
 
     /**
      * Create a checkpoint of this notebook on the server from the most recent save.
      * 
      * @method create_checkpoint
      */
     Notebook.prototype.create_checkpoint = function () {
         var that = this;
         this.contents.create_checkpoint(this.notebook_path).then(
             $.proxy(this.create_checkpoint_success, this),
             function (error) {
                 that.events.trigger('checkpoint_failed.Notebook', error);
             }
         );
     };
 
     /**
      * Success callback for creating a checkpoint.
      * 
      * @method create_checkpoint_success
      * @param {Object} data JSON representation of a checkpoint
      */
     Notebook.prototype.create_checkpoint_success = function (data) {
         this.add_checkpoint(data);
         this.events.trigger('checkpoint_created.Notebook', data);
     };
 
     Notebook.prototype.restore_checkpoint_dialog = function (checkpoint) {
         var that = this;
         checkpoint = checkpoint || this.last_checkpoint;
         if ( ! checkpoint ) {
             console.log("restore dialog, but no checkpoint to restore to!");
             return;
         }
         var body = $('<div/>').append(
             $('<p/>').addClass("p-space").text(
                 "Are you sure you want to revert the notebook to " +
                 "the latest checkpoint?"
             ).append(
                 $("<strong/>").text(
                     " This cannot be undone."
                 )
             )
         ).append(
             $('<p/>').addClass("p-space").text("The checkpoint was last updated at:")
         ).append(
             $('<p/>').addClass("p-space").text(
                 Date(checkpoint.last_modified)
             ).css("text-align", "center")
         );
         
         dialog.modal({
             notebook: this,
             keyboard_manager: this.keyboard_manager,
             title : "Revert notebook to checkpoint",
             body : body,
             buttons : {
                 Revert : {
                     class : "btn-danger",
                     click : function () {
                         that.restore_checkpoint(checkpoint.id);
                     }
                 },
                 Cancel : {}
                 }
         });
     };
     
     /**
      * Restore the notebook to a checkpoint state.
      * 
      * @method restore_checkpoint
      * @param {String} checkpoint ID
      */
     Notebook.prototype.restore_checkpoint = function (checkpoint) {
         this.events.trigger('notebook_restoring.Notebook', checkpoint);
         var that = this;
         this.contents.restore_checkpoint(this.notebook_path, checkpoint).then(
             $.proxy(this.restore_checkpoint_success, this),
             function (error) {
                 that.events.trigger('checkpoint_restore_failed.Notebook', error);
             }
         );
     };
     
     /**
      * Success callback for restoring a notebook to a checkpoint.
      * 
      * @method restore_checkpoint_success
      */
     Notebook.prototype.restore_checkpoint_success = function () {
         this.events.trigger('checkpoint_restored.Notebook');
         this.load_notebook(this.notebook_path);
     };
 
     /**
      * Delete a notebook checkpoint.
      * 
      * @method delete_checkpoint
      * @param {String} checkpoint ID
      */
     Notebook.prototype.delete_checkpoint = function (checkpoint) {
         this.events.trigger('notebook_restoring.Notebook', checkpoint);
         var that = this;
         this.contents.delete_checkpoint(this.notebook_path, checkpoint).then(
             $.proxy(this.delete_checkpoint_success, this),
             function (error) {
                 that.events.trigger('checkpoint_delete_failed.Notebook', error);
             }
         );
     };
     
     /**
      * Success callback for deleting a notebook checkpoint
      * 
      * @method delete_checkpoint_success
      */
     Notebook.prototype.delete_checkpoint_success = function () {
         this.events.trigger('checkpoint_deleted.Notebook');
         this.load_notebook(this.notebook_path);
     };
 
 
     // For backwards compatability.
     IPython.Notebook = Notebook;
 
     return {'Notebook': Notebook};
 });

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

@@ -1,962 +1,980 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jqueryui',
     'base/js/utils',
     'base/js/security',
     'base/js/keyboard',
     'notebook/js/mathjaxutils',
     'components/marked/lib/marked',
 ], function(IPython, $, utils, security, keyboard, mathjaxutils, marked) {
     "use strict";
 
     /**
      * @class OutputArea
      *
      * @constructor
      */
 
     var OutputArea = function (options) {
         this.selector = options.selector;
         this.events = options.events;
         this.keyboard_manager = options.keyboard_manager;
         this.wrapper = $(options.selector);
         this.outputs = [];
         this.collapsed = false;
         this.scrolled = false;
         this.trusted = true;
         this.clear_queued = null;
         if (options.prompt_area === undefined) {
             this.prompt_area = true;
         } else {
             this.prompt_area = options.prompt_area;
         }
         this.create_elements();
         this.style();
         this.bind_events();
     };
 
 
     /**
      * Class prototypes
      **/
 
     OutputArea.prototype.create_elements = function () {
         this.element = $("<div/>");
         this.collapse_button = $("<div/>");
         this.prompt_overlay = $("<div/>");
         this.wrapper.append(this.prompt_overlay);
         this.wrapper.append(this.element);
         this.wrapper.append(this.collapse_button);
     };
 
 
     OutputArea.prototype.style = function () {
         this.collapse_button.hide();
         this.prompt_overlay.hide();
         
         this.wrapper.addClass('output_wrapper');
         this.element.addClass('output');
         
         this.collapse_button.addClass("btn btn-default output_collapsed");
         this.collapse_button.attr('title', 'click to expand output');
         this.collapse_button.text('. . .');
         
         this.prompt_overlay.addClass('out_prompt_overlay prompt');
         this.prompt_overlay.attr('title', 'click to expand output; double click to hide output');
         
         this.collapse();
     };
 
     /**
      * Should the OutputArea scroll?
      * Returns whether the height (in lines) exceeds a threshold.
      *
      * @private
      * @method _should_scroll
      * @param [lines=100]{Integer}
      * @return {Bool}
      *
      */
     OutputArea.prototype._should_scroll = function (lines) {
         if (lines <=0 ){ return; }
         if (!lines) {
             lines = 100;
         }
         // line-height from http://stackoverflow.com/questions/1185151
         var fontSize = this.element.css('font-size');
         var lineHeight = Math.floor(parseInt(fontSize.replace('px','')) * 1.5);
         
         return (this.element.height() > lines * lineHeight);
     };
 
 
     OutputArea.prototype.bind_events = function () {
         var that = this;
         this.prompt_overlay.dblclick(function () { that.toggle_output(); });
         this.prompt_overlay.click(function () { that.toggle_scroll(); });
 
         this.element.resize(function () {
             // FIXME: Firefox on Linux misbehaves, so automatic scrolling is disabled
             if ( utils.browser[0] === "Firefox" ) {
                 return;
             }
             // maybe scroll output,
             // if it's grown large enough and hasn't already been scrolled.
             if ( !that.scrolled && that._should_scroll(OutputArea.auto_scroll_threshold)) {
                 that.scroll_area();
             }
         });
         this.collapse_button.click(function () {
             that.expand();
         });
     };
 
 
     OutputArea.prototype.collapse = function () {
         if (!this.collapsed) {
             this.element.hide();
             this.prompt_overlay.hide();
             if (this.element.html()){
                 this.collapse_button.show();
             }
             this.collapsed = true;
         }
     };
 
 
     OutputArea.prototype.expand = function () {
         if (this.collapsed) {
             this.collapse_button.hide();
             this.element.show();
             this.prompt_overlay.show();
             this.collapsed = false;
         }
     };
 
 
     OutputArea.prototype.toggle_output = function () {
         if (this.collapsed) {
             this.expand();
         } else {
             this.collapse();
         }
     };
 
 
     OutputArea.prototype.scroll_area = function () {
         this.element.addClass('output_scroll');
         this.prompt_overlay.attr('title', 'click to unscroll output; double click to hide');
         this.scrolled = true;
     };
 
 
     OutputArea.prototype.unscroll_area = function () {
         this.element.removeClass('output_scroll');
         this.prompt_overlay.attr('title', 'click to scroll output; double click to hide');
         this.scrolled = false;
     };
 
     /**
      *
      * Scroll OutputArea if height supperior than a threshold (in lines).
      *
      * Threshold is a maximum number of lines. If unspecified, defaults to
      * OutputArea.minimum_scroll_threshold.
      *
      * Negative threshold will prevent the OutputArea from ever scrolling.
      *
      * @method scroll_if_long
      *
      * @param [lines=20]{Number} Default to 20 if not set,
      * behavior undefined for value of `0`.
      *
      **/
     OutputArea.prototype.scroll_if_long = function (lines) {
         var n = lines | OutputArea.minimum_scroll_threshold;
         if(n <= 0){
             return;
         }
 
         if (this._should_scroll(n)) {
             // only allow scrolling long-enough output
             this.scroll_area();
         }
     };
 
 
     OutputArea.prototype.toggle_scroll = function () {
         if (this.scrolled) {
             this.unscroll_area();
         } else {
             // only allow scrolling long-enough output
             this.scroll_if_long();
         }
     };
 
 
     // typeset with MathJax if MathJax is available
     OutputArea.prototype.typeset = function () {
         if (window.MathJax){
             MathJax.Hub.Queue(["Typeset",MathJax.Hub]);
         }
     };
 
 
     OutputArea.prototype.handle_output = function (msg) {
         var json = {};
         var msg_type = json.output_type = msg.header.msg_type;
         var content = msg.content;
         if (msg_type === "stream") {
             json.text = content.text;
             json.name = content.name;
         } else if (msg_type === "display_data") {
             json.data = content.data;
             json.output_type = msg_type;
             json.metadata = content.metadata;
         } else if (msg_type === "execute_result") {
             json.data = content.data;
             json.output_type = msg_type;
             json.metadata = content.metadata;
             json.execution_count = content.execution_count;
         } else if (msg_type === "error") {
             json.ename = content.ename;
             json.evalue = content.evalue;
             json.traceback = content.traceback;
         } else {
             console.log("unhandled output message", msg);
             return;
         }
         this.append_output(json);
     };
     
     
     OutputArea.output_types = [
         'application/javascript',
         'text/html',
         'text/markdown',
         'text/latex',
         'image/svg+xml',
         'image/png',
         'image/jpeg',
         'application/pdf',
         'text/plain'
     ];
 
     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' &&
                 data[key] !== undefined &&
                 typeof data[key] !== 'string'
             ) {
                 console.log("Invalid type for " + key, data[key]);
                 delete data[key];
             }
         });
         return json;
     };
     
     OutputArea.prototype.append_output = function (json) {
         this.expand();
         
         // Clear the output if clear is queued.
         var needs_height_reset = false;
         if (this.clear_queued) {
             this.clear_output(false);
             needs_height_reset = true;
         }
 
         var record_output = true;
         switch(json.output_type) {
             case 'execute_result':
                 json = this.validate_mimebundle(json);
                 this.append_execute_result(json);
                 break;
             case 'stream':
                 // append_stream might have merged the output with earlier stream output
                 record_output = this.append_stream(json);
                 break;
             case 'error':
                 this.append_error(json);
                 break;
             case 'display_data':
                 // append handled below
                 json = this.validate_mimebundle(json);
                 break;
             default:
                 console.log("unrecognized output type: " + json.output_type);
                 this.append_unrecognized(json);
         }
 
         // We must release the animation fixed height in a callback since Gecko
         // (FireFox) doesn't render the image immediately as the data is 
         // 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('');
             }
             that.element.trigger('resize');
         };
         if (json.output_type === 'display_data') {
             this.append_display_data(json, handle_appended);
         } else {
             handle_appended();
         }
         
         if (record_output) {
             this.outputs.push(json);
         }
     };
 
 
     OutputArea.prototype.create_output_area = function () {
         var oa = $("<div/>").addClass("output_area");
         if (this.prompt_area) {
             oa.append($('<div/>').addClass('prompt'));
         }
         return oa;
     };
 
 
     function _get_metadata_key(metadata, key, mime) {
         var mime_md = metadata[mime];
         // mime-specific higher priority
         if (mime_md && mime_md[key] !== undefined) {
             return mime_md[key];
         }
         // fallback on global
         return metadata[key];
     }
 
     OutputArea.prototype.create_output_subarea = function(md, classes, mime) {
         var subarea = $('<div/>').addClass('output_subarea').addClass(classes);
         if (_get_metadata_key(md, 'isolated', mime)) {
             // Create an iframe to isolate the subarea from the rest of the
             // document
             var iframe = $('<iframe/>').addClass('box-flex1');
             iframe.css({'height':1, 'width':'100%', 'display':'block'});
             iframe.attr('frameborder', 0);
             iframe.attr('scrolling', 'auto');
 
             // Once the iframe is loaded, the subarea is dynamically inserted
             iframe.on('load', function() {
                 // Workaround needed by Firefox, to properly render svg inside
                 // iframes, see http://stackoverflow.com/questions/10177190/
                 // svg-dynamically-added-to-iframe-does-not-render-correctly
                 this.contentDocument.open();
 
                 // Insert the subarea into the iframe
                 // We must directly write the html. When using Jquery's append
                 // method, javascript is evaluated in the parent document and
                 // not in the iframe document.  At this point, subarea doesn't
                 // contain any user content.
                 this.contentDocument.write(subarea.html());
 
                 this.contentDocument.close();
 
                 var body = this.contentDocument.body;
                 // Adjust the iframe height automatically
                 iframe.height(body.scrollHeight + 'px');
             });
 
             // Elements should be appended to the inner subarea and not to the
             // iframe
             iframe.append = function(that) {
                 subarea.append(that);
             };
 
             return iframe;
         } else {
             return subarea;
         }
     };
 
 
     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
             .append($('<div/>').text(msg).addClass('js-error'))
             .append($('<div/>').text(err.toString()).addClass('js-error'))
             .append($('<div/>').text('See your browser Javascript console for more details.').addClass('js-error'));
     };
     
     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) {
             console.log(err);
             // Create an actual output_area and output_subarea, which creates
             // the prompt area and the proper indentation.
             var toinsert = this.create_output_area();
             var subarea = $('<div/>').addClass('output_subarea');
             toinsert.append(subarea);
             this._append_javascript_error(err, subarea);
             this.element.append(toinsert);
         }
 
         // Notify others of changes.
         this.element.trigger('changed');
     };
 
 
     OutputArea.prototype.append_execute_result = function (json) {
         var n = json.execution_count || ' ';
         var toinsert = this.create_output_area();
         if (this.prompt_area) {
             toinsert.find('div.prompt').addClass('output_prompt').text('Out[' + n + ']:');
         }
         var inserted = this.append_mime_type(json, toinsert);
         if (inserted) {
             inserted.addClass('output_result');
         }
         this._safe_append(toinsert);
         // If we just output latex, typeset it.
         if ((json.data['text/latex'] !== undefined) ||
             (json.data['text/html'] !== undefined) ||
             (json.data['text/markdown'] !== undefined)) {
             this.typeset();
         }
     };
 
 
     OutputArea.prototype.append_error = function (json) {
         var tb = json.traceback;
         if (tb !== undefined && tb.length > 0) {
             var s = '';
             var len = tb.length;
             for (var i=0; i<len; i++) {
                 s = s + tb[i] + '\n';
             }
             s = s + '\n';
             var toinsert = this.create_output_area();
             var append_text = OutputArea.append_map['text/plain'];
             if (append_text) {
                 append_text.apply(this, [s, {}, toinsert]).addClass('output_error');
             }
             this._safe_append(toinsert);
         }
     };
 
 
     OutputArea.prototype.append_stream = function (json) {
         var text = json.text;
         var subclass = "output_"+json.name;
         if (this.outputs.length > 0){
             // have at least one output to consider
             var last = this.outputs[this.outputs.length-1];
             if (last.output_type == 'stream' && json.name == last.name){
                 // latest output was in the same stream,
                 // so append directly into its pre tag
                 // escape ANSI & HTML specials:
                 last.text = utils.fixCarriageReturn(last.text + json.text);
                 var pre = this.element.find('div.'+subclass).last().find('pre');
                 var html = utils.fixConsole(last.text);
                 // The only user content injected with this HTML call is
                 // escaped by the fixConsole() method.
                 pre.html(html);
                 // return false signals that we merged this output with the previous one,
                 // and the new output shouldn't be recorded.
                 return false;
             }
         }
 
         if (!text.replace("\r", "")) {
             // text is nothing (empty string, \r, etc.)
             // so don't append any elements, which might add undesirable space
             // return true to indicate the output should be recorded.
             return true;
         }
 
         // If we got here, attach a new div
         var toinsert = this.create_output_area();
         var append_text = OutputArea.append_map['text/plain'];
         if (append_text) {
             append_text.apply(this, [text, {}, toinsert]).addClass("output_stream " + subclass);
         }
         this._safe_append(toinsert);
         return true;
     };
 
 
     OutputArea.prototype.append_unrecognized = function (json) {
         var that = this;
         var toinsert = this.create_output_area();
         var subarea = $('<div/>').addClass('output_subarea output_unrecognized');
         toinsert.append(subarea);
         subarea.append(
             $("<a>")
                 .attr("href", "#")
                 .text("Unrecognized output: " + json.output_type)
                 .click(function () {
                     that.events.trigger('unrecognized_output.OutputArea', {output: json})
                 })
         );
         this._safe_append(toinsert);
     };
 
 
     OutputArea.prototype.append_display_data = function (json, handle_inserted) {
         var toinsert = this.create_output_area();
         if (this.append_mime_type(json, toinsert, handle_inserted)) {
             this._safe_append(toinsert);
             // If we just output latex, typeset it.
             if ((json.data['text/latex'] !== undefined) ||
                 (json.data['text/html'] !== undefined) ||
                 (json.data['text/markdown'] !== undefined)) {
                 this.typeset();
             }
         }
     };
 
 
     OutputArea.safe_outputs = {
         'text/plain' : true,
         'text/latex' : true,
         'image/png' : true,
         'image/jpeg' : true
     };
     
     OutputArea.prototype.append_mime_type = function (json, element, handle_inserted) {
         for (var i=0; i < OutputArea.display_order.length; i++) {
             var type = OutputArea.display_order[i];
             var append = OutputArea.append_map[type];
             if ((json.data[type] !== undefined) && append) {
                 var value = json.data[type];
                 if (!this.trusted && !OutputArea.safe_outputs[type]) {
                     // not trusted, sanitize HTML
                     if (type==='text/html' || type==='text/svg') {
                         value = security.sanitize_html(value);
                     } else {
                         // don't display if we don't know how to sanitize it
                         console.log("Ignoring untrusted " + type + " output.");
                         continue;
                     }
                 }
                 var md = json.metadata || {};
                 var toinsert = append.apply(this, [value, md, element, handle_inserted]);
                 // Since only the png and jpeg mime types call the inserted
                 // callback, if the mime type is something other we must call the 
                 // inserted callback only when the element is actually inserted
                 // into the DOM.  Use a timeout of 0 to do this.
                 if (['image/png', 'image/jpeg'].indexOf(type) < 0 && handle_inserted !== undefined) {
                     setTimeout(handle_inserted, 0);
                 }
                 this.events.trigger('output_appended.OutputArea', [type, value, md, toinsert]);
                 return toinsert;
             }
         }
         return null;
     };
 
 
     var append_html = function (html, md, element) {
         var type = 'text/html';
         var toinsert = this.create_output_subarea(md, "output_html rendered_html", type);
         this.keyboard_manager.register_events(toinsert);
         toinsert.append(html);
         element.append(toinsert);
         return toinsert;
     };
 
 
     var append_markdown = function(markdown, md, element) {
         var type = 'text/markdown';
         var toinsert = this.create_output_subarea(md, "output_markdown", type);
         var text_and_math = mathjaxutils.remove_math(markdown);
         var text = text_and_math[0];
         var math = text_and_math[1];
         marked(text, function (err, html) {
             html = mathjaxutils.replace_math(html, math);
             toinsert.append(html);
         });
         element.append(toinsert);
         return toinsert;
     };
 
 
     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);
         element.append(toinsert);
 
         // Fix for ipython/issues/5293, make sure `element` is the area which
         // output can be inserted into at the time of JS execution.
         element = toinsert;
         try {
             eval(js);
         } catch(err) {
             console.log(err);
             this._append_javascript_error(err, toinsert);
         }
         return toinsert;
     };
 
 
     var append_text = function (data, md, element) {
         var type = 'text/plain';
         var toinsert = this.create_output_subarea(md, "output_text", type);
         // escape ANSI & HTML specials in plaintext:
         data = utils.fixConsole(data);
         data = utils.fixCarriageReturn(data);
         data = utils.autoLinkUrls(data);
         // The only user content injected with this HTML call is
         // escaped by the fixConsole() method.
         toinsert.append($("<pre/>").html(data));
         element.append(toinsert);
         return toinsert;
     };
 
 
     var append_svg = function (svg_html, md, element) {
         var type = 'image/svg+xml';
         var toinsert = this.create_output_subarea(md, "output_svg", type);
 
         // Get the svg element from within the HTML.
         var svg = $('<div />').html(svg_html).find('svg');
         var svg_area = $('<div />');
         var width = svg.attr('width');
         var height = svg.attr('height');
         svg
             .width('100%')
             .height('100%');
         svg_area
             .width(width)
             .height(height);
 
         // The jQuery resize handlers don't seem to work on the svg element.
         // When the svg renders completely, measure it's size and set the parent
         // div to that size.  Then set the svg to 100% the size of the parent
         // div and make the parent div resizable.  
         this._dblclick_to_reset_size(svg_area, true, false);
 
         svg_area.append(svg);
         toinsert.append(svg_area);
         element.append(toinsert);
 
         return toinsert;
     };
 
     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();
             if (!(h0 && w0)) {
                 // zero size, don't make it resizable
                 return;
             }
             img.resizable({
                 aspectRatio: true,
                 autoHide: true
             });
             img.dblclick(function () {
                 // resize wrapper & image together for some reason:
                 img.height(h0);
                 img.width(w0);
                 if (resize_parent === undefined || resize_parent) {
                     img.parent().height(h0);
                     img.parent().width(w0);
                 }
             });
         };
 
         if (immediately) {
             callback();
         } else {
             img.on("load", callback);
         }
     };
     
     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);
         if (width !== undefined) img.attr('width', width);
     };
     
     var append_png = function (png, md, element, handle_inserted) {
         var type = 'image/png';
         var toinsert = this.create_output_subarea(md, "output_png", type);
         var img = $("<img/>");
         if (handle_inserted !== undefined) {
             img.on('load', function(){
                 handle_inserted(img);
             });
         }
         img[0].src = 'data:image/png;base64,'+ png;
         set_width_height(img, md, 'image/png');
         this._dblclick_to_reset_size(img);
         toinsert.append(img);
         element.append(toinsert);
         return toinsert;
     };
 
 
     var append_jpeg = function (jpeg, md, element, handle_inserted) {
         var type = 'image/jpeg';
         var toinsert = this.create_output_subarea(md, "output_jpeg", type);
         var img = $("<img/>");
         if (handle_inserted !== undefined) {
             img.on('load', function(){
                 handle_inserted(img);
             });
         }
         img[0].src = 'data:image/jpeg;base64,'+ jpeg;
         set_width_height(img, md, 'image/jpeg');
         this._dblclick_to_reset_size(img);
         toinsert.append(img);
         element.append(toinsert);
         return toinsert;
     };
 
 
     var append_pdf = function (pdf, md, element) {
         var type = 'application/pdf';
         var toinsert = this.create_output_subarea(md, "output_pdf", type);
         var a = $('<a/>').attr('href', 'data:application/pdf;base64,'+pdf);
         a.attr('target', '_blank');
         a.text('View PDF');
         toinsert.append(a);
         element.append(toinsert);
         return toinsert;
      };
 
     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);
         element.append(toinsert);
         return toinsert;
     };
 
 
     OutputArea.prototype.append_raw_input = function (msg) {
         var that = this;
         this.expand();
         var content = msg.content;
         var area = this.create_output_area();
         
         // disable any other raw_inputs, if they are left around
         $("div.output_subarea.raw_input_container").remove();
         
         var input_type = content.password ? 'password' : 'text';
         
         area.append(
             $("<div/>")
             .addClass("box-flex1 output_subarea raw_input_container")
             .append(
                 $("<span/>")
                 .addClass("raw_input_prompt")
                 .text(content.prompt)
             )
             .append(
                 $("<input/>")
                 .addClass("raw_input")
                 .attr('type', input_type)
                 .attr("size", 47)
                 .keydown(function (event, ui) {
                     // make sure we submit on enter,
                     // and don't re-execute the *cell* on shift-enter
                     if (event.which === keyboard.keycodes.enter) {
                         that._submit_raw_input();
                         return false;
                     }
                 })
             )
         );
         
         this.element.append(area);
         var raw_input = area.find('input.raw_input');
         // Register events that enable/disable the keyboard manager while raw
         // input is focused.
         this.keyboard_manager.register_events(raw_input);
         // Note, the following line used to read raw_input.focus().focus().
         // This seemed to be needed otherwise only the cell would be focused.
         // But with the modal UI, this seems to work fine with one call to focus().
         raw_input.focus();
     };
 
     OutputArea.prototype._submit_raw_input = function (evt) {
         var container = this.element.find("div.raw_input_container");
         var theprompt = container.find("span.raw_input_prompt");
         var theinput = container.find("input.raw_input");
         var value = theinput.val();
         var echo  = value;
         // don't echo if it's a password
         if (theinput.attr('type') == 'password') {
             echo = '········';
         }
         var content = {
             output_type : 'stream',
             name : 'stdout',
             text : theprompt.text() + echo + '\n'
         };
         // remove form container
         container.parent().remove();
         // replace with plaintext version in stdout
         this.append_output(content, false);
         this.events.trigger('send_input_reply.Kernel', value);
     };
 
 
     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);
     };
 
 
     OutputArea.prototype.clear_output = function(wait) {
         if (wait) {
 
             // If a clear is queued, clear before adding another to the queue.
             if (this.clear_queued) {
                 this.clear_output(false);
             }
 
             this.clear_queued = true;
         } else {
 
             // Fix the output div's height if the clear_output is waiting for
             // new output (it is being used in an animation).
             if (this.clear_queued) {
                 var height = this.element.height();
                 this.element.height(height);
                 this.clear_queued = false;
             }
             
             // Clear all
             // Remove load event handlers from img tags because we don't want
             // them to fire if the image is never added to the page.
             this.element.find('img').off('load');
             this.element.html("");
 
             // Notify others of changes.
             this.element.trigger('changed');
             
             this.outputs = [];
             this.trusted = true;
             this.unscroll_area();
             return;
         }
     };
 
 
     // JSON serialization
 
     OutputArea.prototype.fromJSON = function (outputs, metadata) {
         var len = outputs.length;
         metadata = metadata || {};
 
         for (var i=0; i<len; i++) {
             this.append_output(outputs[i]);
         }
 
         if (metadata.collapsed !== undefined) {
             this.collapsed = metadata.collapsed;
             if (metadata.collapsed) {
                 this.collapse_output();
             }
         }
         if (metadata.autoscroll !== undefined) {
             this.collapsed = metadata.collapsed;
             if (metadata.collapsed) {
                 this.collapse_output();
             } else {
                 this.expand_output();
             }
         }
     };
 
 
     OutputArea.prototype.toJSON = function () {
         return this.outputs;
     };
 
     /**
      * Class properties
      **/
 
     /**
      * Threshold to trigger autoscroll when the OutputArea is resized,
      * typically when new outputs are added.
      *
      * Behavior is undefined if autoscroll is lower than minimum_scroll_threshold,
      * unless it is < 0, in which case autoscroll will never be triggered
      *
      * @property auto_scroll_threshold
      * @type Number
      * @default 100
      *
      **/
     OutputArea.auto_scroll_threshold = 100;
 
     /**
      * Lower limit (in lines) for OutputArea to be made scrollable. OutputAreas
      * shorter than this are never scrolled.
      *
      * @property minimum_scroll_threshold
      * @type Number
      * @default 20
      *
      **/
     OutputArea.minimum_scroll_threshold = 20;
 
 
     OutputArea.display_order = [
         'application/javascript',
         'text/html',
         'text/markdown',
         'text/latex',
         'image/svg+xml',
         'image/png',
         'image/jpeg',
         'application/pdf',
         'text/plain'
     ];
 
     OutputArea.append_map = {
         "text/plain" : append_text,
         "text/html" : append_html,
         "text/markdown": append_markdown,
         "image/svg+xml" : append_svg,
         "image/png" : append_png,
         "image/jpeg" : append_jpeg,
         "text/latex" : append_latex,
         "application/javascript" : append_javascript,
         "application/pdf" : append_pdf
     };
 
     // For backwards compatability.
     IPython.OutputArea = OutputArea;
 
     return {'OutputArea': OutputArea};
 });

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

@@ -1,185 +1,191 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jqueryui',
     'base/js/utils',
 ], function(IPython, $, utils) {
     "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');
         var that = this;
         this.percentage_height = 0.40;
         options.layout_manager.pager = this;
         this.pager_splitter_element = $(pager_splitter_selector)
             .draggable({
                         containment: 'window',
                         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);
                             if (downprct < 0.1) {
                                 that.percentage_height = 0.1;
                                 that.collapse({'duration':0});
                             } else if (downprct > 0.2) {
                                 that.percentage_height = downprct;
                                 that.expand({'duration':0});
                             }
                             options.layout_manager.do_resize();
                        }
             });
         this.expanded = false;
         this.style();
         this.create_button_area();
         this.bind_events();
     };
 
     Pager.prototype.create_button_area = function(){
         var that = this;
         this.pager_button_area.append(
             $('<a>').attr('role', "button")
                     .attr('title',"Open the pager in an external window")
                     .addClass('ui-button')
                     .click(function(){that.detach();})
                     .attr('style','position: absolute; right: 20px;')
                     .append(
                         $('<span>').addClass("ui-icon ui-icon-extlink")
                     )
         );
         this.pager_button_area.append(
             $('<a>').attr('role', "button")
                     .attr('title',"Close the pager")
                     .addClass('ui-button')
                     .click(function(){that.collapse();})
                     .attr('style','position: absolute; right: 5px;')
                     .append(
                         $('<span>').addClass("ui-icon ui-icon-close")
                     )
         );
     };
 
     Pager.prototype.style = function () {
         this.pager_splitter_element.addClass('ui-widget ui-state-default');
         this.pager_splitter_element.attr('title', 'Click to Show/Hide pager area, drag to Resize');
     };
 
 
     Pager.prototype.bind_events = function () {
         var that = this;
 
         this.pager_element.bind('collapse_pager', function (event, extrap) {
             var time = 'fast';
             if (extrap && extrap.duration) {
                 time = extrap.duration;
             }
             that.pager_element.hide(time);
         });
 
         this.pager_element.bind('expand_pager', function (event, extrap) {
             var time = 'fast';
             if (extrap && extrap.duration) {
                 time = extrap.duration;
             }
             that.pager_element.show(time);
         });
 
         this.pager_splitter_element.hover(
             function () {
                 that.pager_splitter_element.addClass('ui-state-hover');
             },
             function () {
                 that.pager_splitter_element.removeClass('ui-state-hover');
             }
         );
 
         this.pager_splitter_element.click(function () {
             that.toggle();
         });
 
         this.events.on('open_with_text.Pager', function (event, payload) {
             // FIXME: support other mime types
             if (payload.data['text/plain'] && payload.data['text/plain'] !== "") {
                 that.clear();
                 that.expand();
                 that.append_text(payload.data['text/plain']);
             }
         });
     };
 
 
     Pager.prototype.collapse = function (extrap) {
         if (this.expanded === true) {
             this.expanded = false;
             this.pager_element.add($('div#notebook')).trigger('collapse_pager', extrap);
         }
     };
 
 
     Pager.prototype.expand = function (extrap) {
         if (this.expanded !== true) {
             this.expanded = true;
             this.pager_element.add($('div#notebook')).trigger('expand_pager', extrap);
         }
     };
 
 
     Pager.prototype.toggle = function () {
         if (this.expanded === true) {
             this.collapse();
         } else {
             this.expand();
         }
     };
 
 
     Pager.prototype.clear = function (text) {
         this.pager_element.find(".container").empty();
     };
 
     Pager.prototype.detach = function(){
         var w = window.open("","_blank");
         $(w.document.head)
         .append(
                 $('<link>')
                 .attr('rel',"stylesheet")
                 .attr('href',"/static/css/notebook.css")
                 .attr('type',"text/css")
         )
         .append(
                 $('<title>').text("IPython Pager")
         );
         var pager_body = $(w.document.body);
         pager_body.css('overflow','scroll');
 
         pager_body.append(this.pager_element.clone().children());
         w.document.close();
         this.collapse();
     };
 
     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))));
     };
 
     // Backwards compatability.
     IPython.Pager = Pager;
 
     return {'Pager': Pager};
 });

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

@@ -1,182 +1,186 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
     'base/js/dialog',
 ], function(IPython, $, utils, dialog) {
     "use strict";
     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;
         this.events = options.events;
     };
 
     var cmd_ctrl = 'Ctrl-';
     var platform_specific;
 
     if (platform === 'MacOS') {
         // Mac OS X specific
         cmd_ctrl = 'Cmd-';
         platform_specific = [
             { shortcut: "Cmd-Up",     help:"go to cell start"  },
             { shortcut: "Cmd-Down",   help:"go to cell end"  },
             { shortcut: "Alt-Left",   help:"go one word left"  },
             { shortcut: "Alt-Right",  help:"go one word right"  },
             { shortcut: "Alt-Backspace",      help:"del word before"  },
             { shortcut: "Alt-Delete",         help:"del word after"  },
         ];
     } else {
         // PC specific
         platform_specific = [
             { shortcut: "Ctrl-Home",  help:"go to cell start"  },
             { shortcut: "Ctrl-Up",     help:"go to cell start"  },
             { shortcut: "Ctrl-End",   help:"go to cell end"  },
             { shortcut: "Ctrl-Down",  help:"go to cell end"  },
             { shortcut: "Ctrl-Left",  help:"go one word left"  },
             { shortcut: "Ctrl-Right", help:"go one word right"  },
             { shortcut: "Ctrl-Backspace", help:"del word before"  },
             { shortcut: "Ctrl-Delete",    help:"del word after"  },
         ];
     }
 
     var cm_shortcuts = [
         { shortcut:"Tab",   help:"code completion or indent" },
         { shortcut:"Shift-Tab",   help:"tooltip" },
         { shortcut: cmd_ctrl + "]",   help:"indent"  },
         { shortcut: cmd_ctrl + "[",   help:"dedent"  },
         { shortcut: cmd_ctrl + "a",   help:"select all"  },
         { shortcut: cmd_ctrl + "z",   help:"undo"  },
         { shortcut: cmd_ctrl + "Shift-z",   help:"redo"  },
         { shortcut: cmd_ctrl + "y",   help:"redo"  },
     ].concat( platform_specific );
 
 
     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();
             delete(this.shortcut_dialog);
             this.force_rebuild = false;
         }
         if ( this.shortcut_dialog ){
             // if dialog is already shown, close it
             $(this.shortcut_dialog).modal("toggle");
             return;
         }
         var command_shortcuts = this.keyboard_manager.command_shortcuts.help();
         var edit_shortcuts = this.keyboard_manager.edit_shortcuts.help();
         var help, shortcut;
         var i, half, n;
         var element = $('<div/>');
 
         // The documentation
         var doc = $('<div/>').addClass('alert alert-warning');
         doc.append(
             $('<button/>').addClass('close').attr('data-dismiss','alert').html('&times;')
         ).append(
             'The IPython Notebook has two different keyboard input modes. <b>Edit mode</b> '+
             'allows you to type code/text into a cell and is indicated by a green cell '+
             'border. <b>Command mode</b> binds the keyboard to notebook level actions '+
             'and is indicated by a grey cell border.'
         );
         element.append(doc);
 
         // Command mode
         var cmd_div = this.build_command_help();
         element.append(cmd_div);
 
         // Edit mode
         var edit_div = this.build_edit_help(cm_shortcuts);
         element.append(edit_div);
 
         this.shortcut_dialog = dialog.modal({
             title : "Keyboard shortcuts",
             body : element,
             destroy : false,
             buttons : {
                 Close : {}
             },
             notebook: this.notebook,
             keyboard_manager: this.keyboard_manager,
         });
         this.shortcut_dialog.addClass("modal_stretch");
         
         this.events.on('rebuild.QuickHelp', function() { that.force_rebuild = true;});
     };
 
     QuickHelp.prototype.build_command_help = function () {
         var command_shortcuts = this.keyboard_manager.command_shortcuts.help();
         return build_div('<h4>Command Mode (press <code>Esc</code> to enable)</h4>', command_shortcuts);
     };
 
     var special_case = { pageup: "PageUp", pagedown: "Page Down", 'minus': '-' };
     var prettify = function (s) {
         s = s.replace(/-$/, 'minus'); // catch shortcuts using '-' key
         var keys = s.split('-');
         var k, i;
         for (i=0; i < keys.length; i++) {
             k = keys[i];
             if ( k.length == 1 ) {
                 keys[i] = "<code><strong>" + k + "</strong></code>";
                 continue; // leave individual keys lower-cased
             }
             if (k.indexOf(',') === -1){
                 keys[i] = ( special_case[k] ? special_case[k] : k.charAt(0).toUpperCase() + k.slice(1) );
             }
             keys[i] = "<code><strong>" + keys[i] + "</strong></code>";
         }
         return keys.join('-');
 
 
     };
 
     QuickHelp.prototype.build_edit_help = function (cm_shortcuts) {
         var edit_shortcuts = this.keyboard_manager.edit_shortcuts.help();
         jQuery.merge(cm_shortcuts, edit_shortcuts);
         return build_div('<h4>Edit Mode (press <code>Enter</code> to enable)</h4>', cm_shortcuts);
     };
 
     var build_one = function (s) {
         var help = s.help;
         var shortcut = prettify(s.shortcut);
         return $('<div>').addClass('quickhelp').
             append($('<span/>').addClass('shortcut_key').append($(shortcut))).
             append($('<span/>').addClass('shortcut_descr').text(' : ' + help));
 
     };
 
     var build_div = function (title, shortcuts) {
         var i, half, n;
         var div = $('<div/>').append($(title));
         var sub_div = $('<div/>').addClass('hbox');
         var col1 = $('<div/>').addClass('box-flex1');
         var col2 = $('<div/>').addClass('box-flex1');
         n = shortcuts.length;
         half = ~~(n/2);  // Truncate :)
         for (i=0; i<half; i++) { col1.append( build_one(shortcuts[i]) ); }
         for (i=half; i<n; i++) { col2.append( build_one(shortcuts[i]) ); }
         sub_div.append(col1).append(col2);
         div.append(sub_div);
         return div;
     };
 
     // Backwards compatability.
     IPython.QuickHelp = QuickHelp;
 
     return {'QuickHelp': QuickHelp};
 });

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

@@ -1,254 +1,260 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
     'base/js/dialog',
     'base/js/keyboard',
     'moment',
 ], function(IPython, $, utils, dialog, keyboard, moment) {
     "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;
         this._checkpoint_date = undefined;
         this.keyboard_manager = options.keyboard_manager;
         if (this.selector !== undefined) {
             this.element = $(selector);
             this.bind_events();
         }
     };
 
 
     SaveWidget.prototype.bind_events = function () {
         var that = this;
         this.element.find('span#notebook_name').click(function () {
             that.rename_notebook({notebook: that.notebook});
         });
         this.events.on('notebook_loaded.Notebook', function () {
             that.update_notebook_name();
             that.update_document_title();
         });
         this.events.on('notebook_saved.Notebook', function () {
             that.update_notebook_name();
             that.update_document_title();
         });
         this.events.on('notebook_renamed.Notebook', function () {
             that.update_notebook_name();
             that.update_document_title();
             that.update_address_bar();
         });
         this.events.on('notebook_save_failed.Notebook', function () {
             that.set_save_status('Autosave Failed!');
         });
         this.events.on('notebook_read_only.Notebook', function () {
             that.set_save_status('(read only)');
             // disable future set_save_status
             that.set_save_status = function () {};
         });
         this.events.on('checkpoints_listed.Notebook', function (event, data) {
             that._set_last_checkpoint(data[0]);
         });
 
         this.events.on('checkpoint_created.Notebook', function (event, data) {
             that._set_last_checkpoint(data);
         });
         this.events.on('set_dirty.Notebook', function (event, data) {
             that.set_autosaved(data.value);
         });
     };
 
 
     SaveWidget.prototype.rename_notebook = function (options) {
         options = options || {};
         var that = this;
         var dialog_body = $('<div/>').append(
             $("<p/>").addClass("rename-message")
                 .text('Enter a new notebook name:')
         ).append(
             $("<br/>")
         ).append(
             $('<input/>').attr('type','text').attr('size','25').addClass('form-control')
             .val(options.notebook.get_notebook_name())
         );
         var d = dialog.modal({
             title: "Rename Notebook",
             body: dialog_body,
             notebook: options.notebook,
             keyboard_manager: this.keyboard_manager,
             buttons : {
                 "OK": {
                     class: "btn-primary",
                     click: function () {
                         var new_name = d.find('input').val();
                         if (!options.notebook.test_notebook_name(new_name)) {
                             d.find('.rename-message').text(
                                 "Invalid notebook name. Notebook names must "+
                                 "have 1 or more characters and can contain any characters " +
                                 "except :/\\. Please enter a new notebook name:"
                             );
                             return false;
                         } else {
                             d.find('.rename-message').text("Renaming...");
                             d.find('input[type="text"]').prop('disabled', true);
                             that.notebook.rename(new_name).then(
                                 function () {
                                     d.modal('hide');
                                 }, function (error) {
                                     d.find('.rename-message').text(error.message || 'Unknown error');
                                     d.find('input[type="text"]').prop('disabled', false).focus().select();
                                 }
                             );
                             return false;
                         }
                     }
                 },
                 "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();
                         return false;
                     }
                 });
                 d.find('input[type="text"]').focus().select();
             }
         });
     };
 
 
     SaveWidget.prototype.update_notebook_name = function () {
         var nbname = this.notebook.get_notebook_name();
         this.element.find('span#notebook_name').text(nbname);
     };
 
 
     SaveWidget.prototype.update_document_title = function () {
         var nbname = this.notebook.get_notebook_name();
         document.title = nbname;
     };
 
     SaveWidget.prototype.update_address_bar = function(){
         var base_url = this.notebook.base_url;
         var path = this.notebook.notebook_path;
         var state = {path : path};
         window.history.replaceState(state, "", utils.url_join_encode(
             base_url,
             "notebooks",
             path)
         );
     };
 
 
     SaveWidget.prototype.set_save_status = function (msg) {
         this.element.find('span#autosave_status').text(msg);
     };
 
     SaveWidget.prototype._set_checkpoint_status = function (human_date, iso_date) {
         var el = this.element.find('span#checkpoint_status');
         if(human_date){
             el.text("Last Checkpoint: "+human_date).attr('title',iso_date);
         } else {
             el.text('').attr('title', 'no-checkpoint');
         }
     };
 
     // compute (roughly) the remaining time in millisecond until the next
     // moment.js relative time update of the string, which by default 
     // happend at 
     //  (a few seconds ago) 
     //  - 45sec, 
     //  (a minute ago) 
     //  - 90sec,
     //      ( x minutes ago) 
     //      - then every minutes until
     //  - 45 min,
     //      (an hour ago) 
     //  - 1h45, 
     //      (x hours ago )
     //      - then every hours
     //  - 22 hours ago
     var _next_timeago_update = function(deltatime_ms){
         var s = 1000; 
         var m = 60*s;
         var h = 60*m;
 
         var mtt = moment.relativeTimeThreshold;
 
         if(deltatime_ms < mtt.s*s){
             return mtt.s*s-deltatime_ms;
         } else if (deltatime_ms < (mtt.s*s+m)) {
             return (mtt.s*s+m)-deltatime_ms;
         } else if (deltatime_ms < mtt.m*m){
             return m;
         } else if (deltatime_ms < (mtt.m*m+h)){
             return (mtt.m*m+h)-deltatime_ms;
         } else  {
             return h;
         }
     };
 
     SaveWidget.prototype._regularly_update_checkpoint_date = function(){
        if (!this._checkpoint_date) {
             this._set_checkpoint_status(null);
             console.log('no checkpoint done');
             return;
         }
         var chkd = moment(this._checkpoint_date);
         var longdate = chkd.format('llll');
 
         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
             );
         };
         var tdelta = Math.ceil(new Date()-this._checkpoint_date);
 
         // update regularly for the first 6hours and show
         // <x time> ago
         if(tdelta < tdelta < 6*3600*1000){  
             recall(_next_timeago_update(tdelta));
             this._set_checkpoint_status(chkd.fromNow(), longdate);
         // otherwise update every hour and show
         // <Today | yesterday|...> at hh,mm,ss
         } else  {
             recall(1*3600*1000);
             this._set_checkpoint_status(chkd.calendar(), longdate);
         }
     };
 
     SaveWidget.prototype._set_last_checkpoint = function (checkpoint) {
         if (checkpoint) {
             this._checkpoint_date = new Date(checkpoint.last_modified);
         } else {
             this._checkpoint_date = null;
         }
         this._regularly_update_checkpoint_date();
 
     };
 
     SaveWidget.prototype.set_autosaved = function (dirty) {
         if (dirty) {
             this.set_save_status("(unsaved changes)");
         } else {
             this.set_save_status("(autosaved)");
         }
     };
 
     // Backwards compatibility.
     IPython.SaveWidget = SaveWidget;
 
     return {'SaveWidget': SaveWidget};
 
 });

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

@@ -1,193 +1,215 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 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;
         var avg_cell_height = (last_cell_top - first_cell_top) / cell_count;
         var notebook = $('#notebook');
         var i = Math.ceil(notebook.scrollTop() / avg_cell_height);
         i = Math.min(Math.max(i , 0), cell_count - 1);
 
         while (this.notebook.get_cell(i).element.offset().top - first_cell_top < notebook.scrollTop() && i < cell_count - 1) {
             i += 1;
         } 
 
         while (this.notebook.get_cell(i).element.offset().top - first_cell_top > notebook.scrollTop() - 50 && i >= 0) {
             i -= 1;
         } 
         return Math.min(i + 1, cell_count - 1);
     };
 
 
     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)) {
             selected_index += delta;
         }
 
         if (selected_index < 0 || cell_count <= selected_index) {
             return ScrollManager.prototype.scroll.apply(this, [delta]);
         } else {
             this.scroll_to(this.notebook.get_cell(selected_index).element);
             
             // Cancel browser keyboard scroll.
             return false;
         }
     };
 
 
     var SlideScrollManager = function(notebook, options) {
-        // Public constructor.
+        /**
+         * Public constructor.
+         */
         TargetScrollManager.apply(this, [notebook, options]);
     };
     SlideScrollManager.prototype = Object.create(TargetScrollManager.prototype);
 
     SlideScrollManager.prototype.is_target = function (index) {
         var cell = this.notebook.get_cell(index);
         return cell.metadata && cell.metadata.slideshow && 
             cell.metadata.slideshow.slide_type && 
             (cell.metadata.slideshow.slide_type === "slide" ||
             cell.metadata.slideshow.slide_type === "subslide");
     };
 
 
     var HeadingScrollManager = function(notebook, options) {
-        // Public constructor.
+        /**
+         * Public constructor.
+         */
         ScrollManager.apply(this, [notebook, options]);
         options = options || {};
         this._level = options.heading_level || 1;
     };
     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++) {
             headers = headers.add('#notebook-container h' + i);
         }
 
         // Find the header the user is on or below.
         var first_cell_top = this.notebook.get_cell(0).element.offset().top;
         var notebook = $('#notebook');
         var current_scroll = notebook.scrollTop();
         var header_scroll = 0;
         i = -1;
         while (current_scroll >= header_scroll && i < headers.length) {
             if (++i < headers.length) {
                 header_scroll = $(headers[i]).offset().top - first_cell_top;
             }
         }
         i--;
 
         // Check if the user is below the header.
         if (i < 0 || current_scroll > $(headers[i]).offset().top - first_cell_top + 30) {
             // Below the header, count the header as a target.
             if (delta < 0) {
                 delta += 1;
             }
         }
         i += delta;
 
         // Scroll!
         if (0 <= i && i < headers.length) {
             this.scroll_to(headers[i]);
             return false;
         } else {
             // Default to the base's scroll behavior when target header doesn't
             // exist.
             return ScrollManager.prototype.scroll.apply(this, [delta]);
         }
     };
 
     // Return naemspace for require.js loads
     return {
         'ScrollManager': ScrollManager,
         'SlideScrollManager': SlideScrollManager,
         'HeadingScrollManager': HeadingScrollManager,
         'TargetScrollManager': TargetScrollManager
     };
 });

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

@@ -1,344 +1,352 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'base/js/utils',
     'jquery',
     'notebook/js/cell',
     'base/js/security',
     'notebook/js/mathjaxutils',
     'notebook/js/celltoolbar',
     'components/marked/lib/marked',
     'codemirror/lib/codemirror',
     'codemirror/mode/gfm/gfm',
     'notebook/js/codemirror-ipythongfm'
 ], function(IPython,utils , $, cell, security, mathjaxutils, celltoolbar, marked, CodeMirror, gfm, ipgfm) {
     "use strict";
     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
         // do not assign most of members here, just pass it down
         // in the options dict potentially overwriting what you wish.
         // they will be assigned in the base class.
         this.notebook = options.notebook;
         this.events = options.events;
         this.config = options.config;
         
         // we cannot put this as a class key as it has handle to "this".
         var config = utils.mergeopt(TextCell, this.config);
         Cell.apply(this, [{
                     config: config, 
                     keyboard_manager: options.keyboard_manager, 
                     events: this.events}]);
 
         this.cell_type = this.cell_type || 'text';
         mathjaxutils = mathjaxutils;
         this.rendered = false;
     };
 
     TextCell.prototype = Object.create(Cell.prototype);
 
     TextCell.options_default = {
         cm_config : {
             extraKeys: {"Tab": "indentMore","Shift-Tab" : "indentLess"},
             mode: 'htmlmixed',
             lineWrapping : true,
         }
     };
 
 
     /**
      * Create the DOM element of the TextCell
      * @method create_element
      * @private
      */
     TextCell.prototype.create_element = function () {
         Cell.prototype.create_element.apply(this, arguments);
 
         var cell = $("<div>").addClass('cell text_cell');
         cell.attr('tabindex','2');
 
         var prompt = $('<div/>').addClass('prompt input_prompt');
         cell.append(prompt);
         var inner_cell = $('<div/>').addClass('inner_cell');
         this.celltoolbar = new celltoolbar.CellToolbar({
             cell: this, 
             notebook: this.notebook});
         inner_cell.append(this.celltoolbar.element);
         var input_area = $('<div/>').addClass('input_area');
         this.code_mirror = new CodeMirror(input_area.get(0), this.cm_config);
         this.code_mirror.on('keydown', $.proxy(this.handle_keyevent,this))
         // The tabindex=-1 makes this div focusable.
         var render_area = $('<div/>').addClass('text_cell_render rendered_html')
             .attr('tabindex','-1');
         inner_cell.append(input_area).append(render_area);
         cell.append(inner_cell);
         this.element = cell;
     };
 
 
     // Cell level actions
     
     TextCell.prototype.select = function () {
         var cont = Cell.prototype.select.apply(this);
         if (cont) {
             if (this.mode === 'edit') {
                 this.code_mirror.refresh();
             }
         }
         return cont;
     };
 
     TextCell.prototype.unrender = function () {
         if (this.read_only) return;
         var cont = Cell.prototype.unrender.apply(this);
         if (cont) {
             var text_cell = this.element;
             var output = text_cell.find("div.text_cell_render");
             if (this.get_text() === this.placeholder) {
                 this.set_text('');
             }
             this.refresh();
         }
         return cont;
     };
 
     TextCell.prototype.execute = function () {
         this.render();
     };
 
     /**
      * setter: {{#crossLink "TextCell/set_text"}}{{/crossLink}}
      * @method get_text
      * @retrun {string} CodeMirror current text value
      */
     TextCell.prototype.get_text = function() {
         return this.code_mirror.getValue();
     };
 
     /**
      * @param {string} text - Codemiror text value
      * @see TextCell#get_text
      * @method set_text
      * */
     TextCell.prototype.set_text = function(text) {
         this.code_mirror.setValue(text);
         this.unrender();
         this.code_mirror.refresh();
     };
 
     /**
      * setter :{{#crossLink "TextCell/set_rendered"}}{{/crossLink}}
      * @method get_rendered
      * */
     TextCell.prototype.get_rendered = function() {
         return this.element.find('div.text_cell_render').html();
     };
 
     /**
      * @method set_rendered
      */
     TextCell.prototype.set_rendered = function(text) {
         this.element.find('div.text_cell_render').html(text);
     };
 
 
     /**
      * Create Text cell from JSON
      * @param {json} data - JSON serialized text-cell
      * @method fromJSON
      */
     TextCell.prototype.fromJSON = function (data) {
         Cell.prototype.fromJSON.apply(this, arguments);
         if (data.cell_type === this.cell_type) {
             if (data.source !== undefined) {
                 this.set_text(data.source);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 this.code_mirror.clearHistory();
                 // TODO: This HTML needs to be treated as potentially dangerous
                 // user input and should be handled before set_rendered.         
                 this.set_rendered(data.rendered || '');
                 this.rendered = false;
                 this.render();
             }
         }
     };
 
     /** Generate JSON from cell
      * @return {object} cell data serialised to json
      */
     TextCell.prototype.toJSON = function () {
         var data = Cell.prototype.toJSON.apply(this);
         data.source = this.get_text();
         if (data.source == this.placeholder) {
             data.source = "";
         }
         return data;
     };
 
 
     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})]);
 
         this.cell_type = 'markdown';
     };
 
     MarkdownCell.options_default = {
         cm_config: {
             mode: 'ipythongfm'
         },
         placeholder: "Type *Markdown* and LaTeX: $\\alpha^2$"
     };
 
     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?/,
             new Array(level + 1).join('#') + ' ');
         this.set_text(source);
         this.refresh();
         if (this.rendered) {
             this.render();
         }
     };
 
     /**
      * @method render
      */
     MarkdownCell.prototype.render = function () {
         var cont = TextCell.prototype.render.apply(this);
         if (cont) {
             var that = this;
             var text = this.get_text();
             var math = null;
             if (text === "") { text = this.placeholder; }
             var text_and_math = mathjaxutils.remove_math(text);
             text = text_and_math[0];
             math = text_and_math[1];
             marked(text, function (err, html) {
                 html = mathjaxutils.replace_math(html, math);
                 html = security.sanitize_html(html);
                 html = $($.parseHTML(html));
                 // add anchors to headings
                 html.find(":header").addBack(":header").each(function (i, h) {
                     h = $(h);
                     var hash = h.text().replace(/ /g, '-');
                     h.attr('id', hash);
                     h.append(
                         $('<a/>')
                             .addClass('anchor-link')
                             .attr('href', '#' + hash)
                             .text('¶')
                     );
                 });
                 // links in markdown cells should open in new tabs
                 html.find("a[href]").not('[href^="#"]').attr("target", "_blank");
                 that.set_rendered(html);
                 that.typeset();
                 that.events.trigger("rendered.MarkdownCell", {cell: that});
             });
         }
         return cont;
     };
 
 
     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})]);
 
         this.cell_type = 'raw';
     };
 
     RawCell.options_default = {
         placeholder : "Write raw LaTeX or other formats here, for use with nbconvert. " +
             "It will not be rendered in the notebook. " + 
             "When passing through nbconvert, a Raw Cell's content is added to the output unmodified."
     };
 
     RawCell.prototype = Object.create(TextCell.prototype);
 
     /** @method bind_events **/
     RawCell.prototype.bind_events = function () {
         TextCell.prototype.bind_events.apply(this);
         var that = this;
         this.element.focusout(function() {
             that.auto_highlight();
             that.render();
         });
 
         this.code_mirror.on('focus', function() { that.unrender(); });
     };
 
     /**
      * Trigger autodetection of highlight scheme for current cell
      * @method auto_highlight
      */
     RawCell.prototype.auto_highlight = function () {
         this._auto_highlight(this.config.raw_cell_highlight);
     };
 
     /** @method render **/
     RawCell.prototype.render = function () {
         var cont = TextCell.prototype.render.apply(this);
         if (cont){
             var text = this.get_text();
             if (text === "") { text = this.placeholder; }
             this.set_text(text);
             this.element.removeClass('rendered');
         }
         return cont;
     };
 
     // Backwards compatability.
     IPython.TextCell = TextCell;
     IPython.MarkdownCell = MarkdownCell;
     IPython.RawCell = RawCell;
 
     var textcell = {
         TextCell: TextCell,
         MarkdownCell: MarkdownCell,
         RawCell: RawCell
     };
     return textcell;
 });

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

@@ -1,309 +1,317 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
 ], function(IPython, $, utils) {
     "use strict";
 
     // tooltip constructor
     var Tooltip = function (events) {
         var that = this;
         this.events = events;
         this.time_before_tooltip = 1200;
 
         // handle to html
         this.tooltip = $('#tooltip');
         this._hidden = true;
 
         // variable for consecutive call
         this._old_cell = null;
         this._old_request = null;
         this._consecutive_counter = 0;
 
         // 'sticky ?'
         this._sticky = false;
 
         // display tooltip if the docstring is empty?
         this._hide_if_no_docstring = false;
 
         // contain the button in the upper right corner
         this.buttons = $('<div/>').addClass('tooltipbuttons');
 
         // will contain the docstring
         this.text = $('<div/>').addClass('tooltiptext').addClass('smalltooltip');
 
         // build the buttons menu on the upper right
         // expand the tooltip to see more
         var expandlink = $('<a/>').attr('href', "#").addClass("ui-corner-all") //rounded corner
         .attr('role', "button").attr('id', 'expanbutton').attr('title', 'Grow the tooltip vertically (press shift-tab twice)').click(function () {
             that.expand();
         }).append(
         $('<span/>').text('Expand').addClass('ui-icon').addClass('ui-icon-plus'));
 
         // open in pager
         var morelink = $('<a/>').attr('href', "#").attr('role', "button").addClass('ui-button').attr('title', 'show the current docstring in pager (press shift-tab 4 times)');
         var morespan = $('<span/>').text('Open in Pager').addClass('ui-icon').addClass('ui-icon-arrowstop-l-n');
         morelink.append(morespan);
         morelink.click(function () {
             that.showInPager(that._old_cell);
         });
 
         // close the tooltip
         var closelink = $('<a/>').attr('href', "#").attr('role', "button").addClass('ui-button');
         var closespan = $('<span/>').text('Close').addClass('ui-icon').addClass('ui-icon-close');
         closelink.append(closespan);
         closelink.click(function () {
             that.remove_and_cancel_tooltip(true);
         });
 
         this._clocklink = $('<a/>').attr('href', "#");
         this._clocklink.attr('role', "button");
         this._clocklink.addClass('ui-button');
         this._clocklink.attr('title', 'Tootip is not dismissed while typing for 10 seconds');
         var clockspan = $('<span/>').text('Close');
         clockspan.addClass('ui-icon');
         clockspan.addClass('ui-icon-clock');
         this._clocklink.append(clockspan);
         this._clocklink.click(function () {
             that.cancel_stick();
         });
 
 
 
 
         //construct the tooltip
         // add in the reverse order you want them to appear
         this.buttons.append(closelink);
         this.buttons.append(expandlink);
         this.buttons.append(morelink);
         this.buttons.append(this._clocklink);
         this._clocklink.hide();
 
 
         // we need a phony element to make the small arrow
         // of the tooltip in css
         // we will move the arrow later
         this.arrow = $('<div/>').addClass('pretooltiparrow');
         this.tooltip.append(this.buttons);
         this.tooltip.append(this.arrow);
         this.tooltip.append(this.text);
 
         // function that will be called if you press tab 1, 2, 3... times in a row
         this.tabs_functions = [function (cell, text, cursor) {
             that._request_tooltip(cell, text, cursor);
         }, function () {
             that.expand();
         }, function () {
             that.stick();
         }, function (cell) {
             that.cancel_stick();
             that.showInPager(cell);
         }];
         // call after all the tabs function above have bee call to clean their effects
         // if necessary
         this.reset_tabs_function = function (cell, text) {
             this._old_cell = (cell) ? cell : null;
             this._old_request = (text) ? text : null;
             this._consecutive_counter = 0;
         };
     };
 
     Tooltip.prototype.is_visible = function () {
         return !this._hidden;
     };
 
     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();
     };
 
     // grow the tooltip verticaly
     Tooltip.prototype.expand = function () {
         this.text.removeClass('smalltooltip');
         this.text.addClass('bigtooltip');
         $('#expanbutton').hide('slow');
     };
 
     // deal with all the logic of hiding the tooltip
     // and reset it's status
     Tooltip.prototype._hide = function () {
         this._hidden = true;
         this.tooltip.fadeOut('fast');
         $('#expanbutton').show('slow');
         this.text.removeClass('bigtooltip');
         this.text.addClass('smalltooltip');
         // keep scroll top to be sure to always see the first line
         this.text.scrollTop(0);
         this.code_mirror = null;
     };
 
     // 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) {
               this.cancel_stick();
               this._hide();
           }
           this.reset_tabs_function();
           return true;
         } else {
           return false;
         }
     };
 
     // cancel autocall done after '(' for example.
     Tooltip.prototype.cancel_pending = function () {
         if (this._tooltip_timeout !== null) {
             clearTimeout(this._tooltip_timeout);
             this._tooltip_timeout = null;
         }
     };
 
     // will trigger tooltip after timeout
     Tooltip.prototype.pending = function (cell, hide_if_no_docstring) {
         var that = this;
         this._tooltip_timeout = setTimeout(function () {
             that.request(cell, hide_if_no_docstring);
         }, that.time_before_tooltip);
     };
 
     // easy access for julia monkey patching.
     Tooltip.last_token_re = /[a-z_][0-9a-z._]*$/gi;
 
     Tooltip.prototype._request_tooltip = function (cell, text, cursor_pos) {
         var callbacks = $.proxy(this._show, this);
         var msg_id = cell.kernel.inspect(text, cursor_pos, callbacks);
     };
 
     // 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();
         var cursor_pos = utils.to_absolute_cursor_pos(editor, cursor);
         var text = cell.get_text();
 
         this._hide_if_no_docstring = hide_if_no_docstring;
 
         if(editor.somethingSelected()){
             // get only the most recent selection.
             text = editor.getSelection();
         }
 
         // need a permanent handle to code_mirror for future auto recall
         this.code_mirror = editor;
 
         // now we treat the different number of keypress
         // first if same cell, same text, increment counter by 1
         if (this._old_cell == cell && this._old_request == text && this._hidden === false) {
             this._consecutive_counter++;
         } else {
             // else reset
             this.cancel_stick();
             this.reset_tabs_function (cell, text);
         }
 
         this.tabs_functions[this._consecutive_counter](cell, text, cursor_pos);
 
         // then if we are at the end of list function, reset
         if (this._consecutive_counter == this.tabs_functions.length) {
             this.reset_tabs_function (cell, text, cursor);
         }
 
         return;
     };
 
     // cancel the option of having the tooltip to stick
     Tooltip.prototype.cancel_stick = function () {
         clearTimeout(this._stick_timeout);
         this._stick_timeout = null;
         this._clocklink.hide('slow');
         this._sticky = false;
     };
 
     // put the tooltip in a sicky state for 10 seconds
     // it won't be removed by remove_and_cancell() unless you called with
     // the first parameter set to true.
     // remove_and_cancell_tooltip(true)
     Tooltip.prototype.stick = function (time) {
         time = (time !== undefined) ? time : 10;
         var that = this;
         this._sticky = true;
         this._clocklink.show('slow');
         this._stick_timeout = setTimeout(function () {
             that._sticky = false;
             that._clocklink.hide('slow');
         }, time * 1000);
     };
 
     // 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) {
             // object not found, nothing to show
             return;
         }
         this.name = content.name;
 
         // do some math to have the tooltip arrow on more or less on left or right
         // width of the editor
         var w = $(this.code_mirror.getScrollerElement()).width();
         // ofset of the editor
         var o = $(this.code_mirror.getScrollerElement()).offset();
 
         // whatever anchor/head order but arrow at mid x selection
         var anchor = this.code_mirror.cursorCoords(false);
         var head  = this.code_mirror.cursorCoords(true);
         var xinit = (head.left+anchor.left)/2;
         var xinter = o.left + (xinit - o.left) / w * (w - 450);
         var posarrowleft = xinit - xinter;
 
         if (this._hidden === false) {
             this.tooltip.animate({
                 'left': xinter - 30 + 'px',
                 'top': (head.bottom + 10) + 'px'
             });
         } else {
             this.tooltip.css({
                 'left': xinter - 30 + 'px'
             });
             this.tooltip.css({
                 'top': (head.bottom + 10) + 'px'
             });
         }
         this.arrow.animate({
             'left': posarrowleft + 'px'
         });
         
         this._hidden = false;
         this.tooltip.fadeIn('fast');
         this.text.children().remove();
         
         // This should support rich data types, but only text/plain for now
         // Any HTML within the docstring is escaped by the fixConsole() method.
         var pre = $('<pre/>').html(utils.fixConsole(content.data['text/plain']));
         this.text.append(pre);
         // keep scroll top to be sure to always see the first line
         this.text.scrollTop(0);
     };
 
     // Backwards compatibility.
     IPython.Tooltip = Tooltip;
 
     return {'Tooltip': Tooltip};
 });

IPython/html/static/services/contents.js

@@ -1,242 +1,250 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     '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;
     };
 
     /** Error type */
     Contents.DIRECTORY_NOT_EMPTY_ERROR = 'DirectoryNotEmptyError';
 
     Contents.DirectoryNotEmptyError = function() {
         // Constructor
         //
         // An error representing the result of attempting to delete a non-empty
         // directory.
         this.message = 'A directory must be empty before being deleted.';
     };
     
     Contents.DirectoryNotEmptyError.prototype = Object.create(Error.prototype);
     Contents.DirectoryNotEmptyError.prototype.name =
         Contents.DIRECTORY_NOT_EMPTY_ERROR;
 
 
     Contents.prototype.api_url = function() {
         var url_parts = [this.base_url, 'api/contents'].concat(
                                 Array.prototype.slice.apply(arguments));
         return utils.url_join_encode.apply(null, url_parts);
     };
 
     /**
      * Creates a basic error handler that wraps a jqXHR error as an Error.
      *
      * Takes a callback that accepts an Error, and returns a callback that can
      * be passed directly to $.ajax, which will wrap the error from jQuery
      * as an Error, and pass that to the original callback.
      *
      * @method create_basic_error_handler
      * @param{Function} callback
      * @return{Function}
      */
     Contents.prototype.create_basic_error_handler = function(callback) {
         if (!callback) {
             return utils.log_ajax_error;
         }
         return function(xhr, status, error) {
             callback(utils.wrap_ajax_error(xhr, status, error));
         };
     };
 
     /**
      * File Functions (including notebook operations)
      */
 
     /**
      * Get a file.
      *
      * Calls success with file JSON model, or error with error.
      *
      * @method get
      * @param {String} path
      * @param {Object} options
      *    type : 'notebook', 'file', or 'directory'
      *    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,
             type : "GET",
             dataType : "json",
         };
         var url = this.api_url(path);
         params = {};
         if (options.type) { params.type = options.type; }
         if (options.format) { params.format = options.format; }
         return utils.promising_ajax(url + '?' + $.param(params), settings);
     };
 
 
     /**
      * Creates a new untitled file or directory in the specified directory path.
      *
      * @method new
      * @param {String} path: the directory in which to create the new file/directory
      * @param {Object} options:
      *      ext: file extension to use
      *      type: model type to create ('notebook', 'file', or 'directory')
      */
     Contents.prototype.new_untitled = function(path, options) {
         var data = JSON.stringify({
           ext: options.ext,
           type: options.type
         });
 
         var settings = {
             processData : false,
             type : "POST",
             data: data,
             dataType : "json",
         };
         return utils.promising_ajax(this.api_url(path), settings);
     };
 
     Contents.prototype.delete = function(path) {
         var settings = {
             processData : false,
             type : "DELETE",
             dataType : "json",
         };
         var url = this.api_url(path);
         return utils.promising_ajax(url, settings).catch(
             // Translate certain errors to more specific ones.
             function(error) {
                 // TODO: update IPEP27 to specify errors more precisely, so
                 // that error types can be detected here with certainty.
                 if (error.xhr.status === 400) {
                     throw new Contents.DirectoryNotEmptyError();
                 }
                 throw error;
             }
         );
     };
 
     Contents.prototype.rename = function(path, new_path) {
         var data = {path: new_path};
         var settings = {
             processData : false,
             type : "PATCH",
             data : JSON.stringify(data),
             dataType: "json",
             contentType: 'application/json',
         };
         var url = this.api_url(path);
         return utils.promising_ajax(url, settings);
     };
 
     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",
             data : JSON.stringify(model),
             contentType: 'application/json',
         };
         var url = this.api_url(path);
         return utils.promising_ajax(url, settings);
     };
     
     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 = {
             processData : false,
             type: "POST",
             data: JSON.stringify({copy_from: from_file}),
             dataType : "json",
         };
         return utils.promising_ajax(url, settings);
     };
 
     /**
      * Checkpointing Functions
      */
 
     Contents.prototype.create_checkpoint = function(path) {
         var url = this.api_url(path, 'checkpoints');
         var settings = {
             type : "POST",
             dataType : "json",
         };
         return utils.promising_ajax(url, settings);
     };
 
     Contents.prototype.list_checkpoints = function(path) {
         var url = this.api_url(path, 'checkpoints');
         var settings = {
             type : "GET",
             cache: false,
             dataType: "json",
         };
         return utils.promising_ajax(url, settings);
     };
 
     Contents.prototype.restore_checkpoint = function(path, checkpoint_id) {
         var url = this.api_url(path, 'checkpoints', checkpoint_id);
         var settings = {
             type : "POST",
         };
         return utils.promising_ajax(url, settings);
     };
 
     Contents.prototype.delete_checkpoint = function(path, checkpoint_id) {
         var url = this.api_url(path, 'checkpoints', checkpoint_id);
         var settings = {
             type : "DELETE",
         };
         return utils.promising_ajax(url, settings);
     };
 
     /**
      * File management functions
      */
 
     /**
      * List notebooks and directories at a given path
      *
      * On success, load_callback is called with an array of dictionaries
      * representing individual files or directories.  Each dictionary has
      * the keys:
      *     type: "notebook" or "directory"
      *     created: created date
      *     last_modified: last modified dat
      * @method list_notebooks
      * @param {String} path The path to list notebooks in
      */
     Contents.prototype.list_contents = function(path) {
         return this.get(path, {type: 'directory'});
     };
 
 
     IPython.Contents = Contents;
 
     return {'Contents': Contents};
 });

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

@@ -1,205 +1,217 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
 ], function(IPython, $, utils) {
     "use strict";
 
     //-----------------------------------------------------------------------
     // CommManager class
     //-----------------------------------------------------------------------
     
     var CommManager = function (kernel) {
         this.comms = {};
         this.targets = {};
         if (kernel !== undefined) {
             this.init_kernel(kernel);
         }
     };
     
     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++) {
             var msg_type = msg_types[i];
             kernel.register_iopub_handler(msg_type, $.proxy(this[msg_type], this));
         }
     };
     
     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);
         return comm;
     };
     
     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];
     };
     
     // comm message handlers
     
     CommManager.prototype.comm_open = function (msg) {
         var content = msg.content;
         var that = this;
         var comm_id = content.comm_id;
 
         this.comms[comm_id] = utils.load_class(content.target_name, content.target_module, 
             this.targets).then(function(target) {
                 var comm = new Comm(content.target_name, comm_id);
                 comm.kernel = that.kernel;
                 try {
                     var response = target(comm, msg);
                 } catch (e) {
                     comm.close();
                     that.unregister_comm(comm);
                     var wrapped_error = new utils.WrappedError("Exception opening new comm", e);
                     console.error(wrapped_error);
                     return Promise.reject(wrapped_error);
                 }
                 // Regardless of the target return value, we need to
                 // then return the comm
                 return Promise.resolve(response).then(function() {return comm;});
             }, utils.reject('Could not open comm', true));
         return this.comms[comm_id];
     };
     
     CommManager.prototype.comm_close = function(msg) {
         var content = msg.content;
         if (this.comms[content.comm_id] === undefined) {
             console.error('Comm promise not found for comm id ' + content.comm_id);
             return;
         }
 
         this.comms[content.comm_id] = this.comms[content.comm_id].then(function(comm) {
             this.unregister_comm(comm);
             try {
                 comm.handle_close(msg);
             } catch (e) {
                 console.log("Exception closing comm: ", e, e.stack, msg);
             }
             // don't return a comm, so that further .then() functions
             // get an undefined comm input
         });
     };
     
     CommManager.prototype.comm_msg = function(msg) {
         var content = msg.content;
         if (this.comms[content.comm_id] === undefined) {
             console.error('Comm promise not found for comm id ' + content.comm_id);
             return;
         }
 
         this.comms[content.comm_id] = this.comms[content.comm_id].then(function(comm) {
             try {
                 comm.handle_msg(msg);
             } catch (e) {
                 console.log("Exception handling comm msg: ", e, e.stack, msg);
             }
             return comm;
         });
     };
     
     //-----------------------------------------------------------------------
     // Comm base class
     //-----------------------------------------------------------------------
     
     var Comm = function (target_name, comm_id) {
         this.target_name = target_name;
         this.comm_id = comm_id || utils.uuid();
         this._msg_callback = this._close_callback = null;
     };
     
     // methods for sending messages
     Comm.prototype.open = function (data, callbacks, metadata) {
         var content = {
             comm_id : this.comm_id,
             target_name : this.target_name,
             data : data || {},
         };
         return this.kernel.send_shell_message("comm_open", content, callbacks, metadata);
     };
     
     Comm.prototype.send = function (data, callbacks, metadata, buffers) {
         var content = {
             comm_id : this.comm_id,
             data : data || {},
         };
         return this.kernel.send_shell_message("comm_msg", content, callbacks, metadata, buffers);
     };
     
     Comm.prototype.close = function (data, callbacks, metadata) {
         var content = {
             comm_id : this.comm_id,
             data : data || {},
         };
         return this.kernel.send_shell_message("comm_close", content, callbacks, metadata);
     };
     
     // methods for registering callbacks for incoming messages
     Comm.prototype._register_callback = function (key, callback) {
         this['_' + key + '_callback'] = callback;
     };
     
     Comm.prototype.on_msg = function (callback) {
         this._register_callback('msg', callback);
     };
     
     Comm.prototype.on_close = function (callback) {
         this._register_callback('close', callback);
     };
     
     // methods for handling incoming messages
     
     Comm.prototype._callback = function (key, msg) {
         var callback = this['_' + key + '_callback'];
         if (callback) {
             try {
                 callback(msg);
             } catch (e) {
                 console.log("Exception in Comm callback", e, e.stack, msg);
             }
         }
     };
     
     Comm.prototype.handle_msg = function (msg) {
         this._callback('msg', msg);
     };
     
     Comm.prototype.handle_close = function (msg) {
         this._callback('close', msg);
     };
     
     // For backwards compatability.
     IPython.CommManager = CommManager;
     IPython.Comm = Comm;
 
     return {
         'CommManager': CommManager,
         'Comm': Comm
     };
 });

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

@@ -1,1052 +1,1056 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
     './comm',
     './serialize',
     'widgets/js/init'
 ], function(IPython, $, utils, comm, serialize, widgetmanager) {
     "use strict";
 
     /**
      * A Kernel class to communicate with the Python kernel. This
      * should generally not be constructed directly, but be created
      * by.  the `Session` object. Once created, this object should be
      * used to communicate with the kernel.
      * 
      * @class Kernel
      * @param {string} kernel_service_url - the URL to access the kernel REST api
      * @param {string} ws_url - the websockets URL
      * @param {Notebook} notebook - notebook object
      * @param {string} name - the kernel type (e.g. python3)
      */
     var Kernel = function (kernel_service_url, ws_url, notebook, name) {
         this.events = notebook.events;
 
         this.id = null;
         this.name = name;
 
         this.channels = {
             'shell': null,
             'iopub': null,
             'stdin': null
         };
 
         this.kernel_service_url = kernel_service_url;
         this.kernel_url = null;
         this.ws_url = ws_url || IPython.utils.get_body_data("wsUrl");
         if (!this.ws_url) {
             // trailing 's' in https will become wss for secure web sockets
             this.ws_url = location.protocol.replace('http', 'ws') + "//" + location.host;
         }
 
         this.username = "username";
         this.session_id = utils.uuid();
         this._msg_callbacks = {};
         this.info_reply = {}; // kernel_info_reply stored here after starting
 
         if (typeof(WebSocket) !== 'undefined') {
             this.WebSocket = WebSocket;
         } else if (typeof(MozWebSocket) !== 'undefined') {
             this.WebSocket = MozWebSocket;
         } else {
             alert('Your browser does not have WebSocket support, please try Chrome, Safari or Firefox ≥ 6. Firefox 4 and 5 are also supported by you have to enable WebSockets in about:config.');
         }
         
         this.bind_events();
         this.init_iopub_handlers();
         this.comm_manager = new comm.CommManager(this);
         this.widget_manager = new widgetmanager.WidgetManager(this.comm_manager, notebook);
         
         this.last_msg_id = null;
         this.last_msg_callbacks = {};
 
         this._autorestart_attempt = 0;
         this._reconnect_attempt = 0;
         this.reconnect_limit = 7;
     };
 
     /**
      * @function _get_msg
      */
     Kernel.prototype._get_msg = function (msg_type, content, metadata, buffers) {
         var msg = {
             header : {
                 msg_id : utils.uuid(),
                 username : this.username,
                 session : this.session_id,
                 msg_type : msg_type,
                 version : "5.0"
             },
             metadata : metadata || {},
             content : content,
             buffers : buffers || [],
             parent_header : {}
         };
         return msg;
     };
 
     /**
      * @function bind_events
      */
     Kernel.prototype.bind_events = function () {
         var that = this;
         this.events.on('send_input_reply.Kernel', function(evt, data) { 
             that.send_input_reply(data);
         });
 
         var record_status = function (evt, info) {
             console.log('Kernel: ' + evt.type + ' (' + info.kernel.id + ')');
         };
 
         this.events.on('kernel_created.Kernel', record_status);
         this.events.on('kernel_reconnecting.Kernel', record_status);
         this.events.on('kernel_connected.Kernel', record_status);
         this.events.on('kernel_starting.Kernel', record_status);
         this.events.on('kernel_restarting.Kernel', record_status);
         this.events.on('kernel_autorestarting.Kernel', record_status);
         this.events.on('kernel_interrupting.Kernel', record_status);
         this.events.on('kernel_disconnected.Kernel', record_status);
         // these are commented out because they are triggered a lot, but can
         // be uncommented for debugging purposes
         //this.events.on('kernel_idle.Kernel', record_status);
         //this.events.on('kernel_busy.Kernel', record_status);
         this.events.on('kernel_ready.Kernel', record_status);
         this.events.on('kernel_killed.Kernel', record_status);
         this.events.on('kernel_dead.Kernel', record_status);
 
         this.events.on('kernel_ready.Kernel', function () {
             that._autorestart_attempt = 0;
         });
         this.events.on('kernel_connected.Kernel', function () {
             that._reconnect_attempt = 0;
         });
     };
 
     /**
      * Initialize the iopub handlers.
      *
      * @function init_iopub_handlers
      */
     Kernel.prototype.init_iopub_handlers = function () {
         var output_msg_types = ['stream', 'display_data', 'execute_result', 'error'];
         this._iopub_handlers = {};
         this.register_iopub_handler('status', $.proxy(this._handle_status_message, this));
         this.register_iopub_handler('clear_output', $.proxy(this._handle_clear_output, this));
         
         for (var i=0; i < output_msg_types.length; i++) {
             this.register_iopub_handler(output_msg_types[i], $.proxy(this._handle_output_message, this));
         }
     };
 
     /**
      * GET /api/kernels
      *
      * Get the list of running kernels.
      *
      * @function list
      * @param {function} [success] - function executed on ajax success
      * @param {function} [error] - functon executed on ajax error
      */
     Kernel.prototype.list = function (success, error) {
         $.ajax(this.kernel_service_url, {
             processData: false,
             cache: false,
             type: "GET",
             dataType: "json",
             success: success,
             error: this._on_error(error)
         });
     };
 
     /**
      * POST /api/kernels
      *
      * Start a new kernel.
      *
      * In general this shouldn't be used -- the kernel should be
      * started through the session API. If you use this function and
      * are also using the session API then your session and kernel
      * WILL be out of sync!
      *
      * @function start
      * @param {params} [Object] - parameters to include in the query string
      * @param {function} [success] - function executed on ajax success
      * @param {function} [error] - functon executed on ajax error
      */
     Kernel.prototype.start = function (params, success, error) {
         var url = this.kernel_service_url;
         var qs = $.param(params || {}); // query string for sage math stuff
         if (qs !== "") {
             url = url + "?" + qs;
         }
 
         var that = this;
         var on_success = function (data, status, xhr) {
             that.events.trigger('kernel_created.Kernel', {kernel: that});
             that._kernel_created(data);
             if (success) {
                 success(data, status, xhr);
             }
         };
 
         $.ajax(url, {
             processData: false,
             cache: false,
             type: "POST",
             data: JSON.stringify({name: this.name}),
             dataType: "json",
             success: this._on_success(on_success),
             error: this._on_error(error)
         });
 
         return url;
     };
 
     /**
      * GET /api/kernels/[:kernel_id]
      *
      * Get information about the kernel.
      *
      * @function get_info
      * @param {function} [success] - function executed on ajax success
      * @param {function} [error] - functon executed on ajax error
      */
     Kernel.prototype.get_info = function (success, error) {
         $.ajax(this.kernel_url, {
             processData: false,
             cache: false,
             type: "GET",
             dataType: "json",
             success: this._on_success(success),
             error: this._on_error(error)
         });
     };
 
     /**
      * DELETE /api/kernels/[:kernel_id]
      *
      * Shutdown the kernel.
      *
      * If you are also using sessions, then this function shoul NOT be
      * used. Instead, use Session.delete. Otherwise, the session and
      * kernel WILL be out of sync.
      *
      * @function kill
      * @param {function} [success] - function executed on ajax success
      * @param {function} [error] - functon executed on ajax error
      */
     Kernel.prototype.kill = function (success, error) {
         this.events.trigger('kernel_killed.Kernel', {kernel: this});
         this._kernel_dead();
         $.ajax(this.kernel_url, {
             processData: false,
             cache: false,
             type: "DELETE",
             dataType: "json",
             success: this._on_success(success),
             error: this._on_error(error)
         });
     };
 
     /**
      * POST /api/kernels/[:kernel_id]/interrupt
      *
      * Interrupt the kernel.
      *
      * @function interrupt
      * @param {function} [success] - function executed on ajax success
      * @param {function} [error] - functon executed on ajax error
      */
     Kernel.prototype.interrupt = function (success, error) {
         this.events.trigger('kernel_interrupting.Kernel', {kernel: this});
 
         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);
             }
         };
 
         var url = utils.url_join_encode(this.kernel_url, 'interrupt');
         $.ajax(url, {
             processData: false,
             cache: false,
             type: "POST",
             dataType: "json",
             success: this._on_success(on_success),
             error: this._on_error(error)
         });
     };
 
     Kernel.prototype.restart = function (success, error) {
         /**
          * POST /api/kernels/[:kernel_id]/restart
          *
          * Restart the kernel.
          *
          * @function interrupt
          * @param {function} [success] - function executed on ajax success
          * @param {function} [error] - functon executed on ajax error
          */
         this.events.trigger('kernel_restarting.Kernel', {kernel: this});
         this.stop_channels();
 
         var that = this;
         var on_success = function (data, status, xhr) {
             that.events.trigger('kernel_created.Kernel', {kernel: that});
             that._kernel_created(data);
             if (success) {
                 success(data, status, xhr);
             }
         };
 
         var on_error = function (xhr, status, err) {
             that.events.trigger('kernel_dead.Kernel', {kernel: that});
             that._kernel_dead();
             if (error) {
                 error(xhr, status, err);
             }
         };
 
         var url = utils.url_join_encode(this.kernel_url, 'restart');
         $.ajax(url, {
             processData: false,
             cache: false,
             type: "POST",
             dataType: "json",
             success: this._on_success(on_success),
             error: this._on_error(on_error)
         });
     };
 
     Kernel.prototype.reconnect = function () {
         /**
          * Reconnect to a disconnected kernel. This is not actually a
          * standard HTTP request, but useful function nonetheless for
          * reconnecting to the kernel if the connection is somehow lost.
          *
          * @function reconnect
          */
         if (this.is_connected()) {
             return;
         }
         this._reconnect_attempt = this._reconnect_attempt + 1;
         this.events.trigger('kernel_reconnecting.Kernel', {
             kernel: this,
             attempt: this._reconnect_attempt,
         });
         this.start_channels();
     };
 
     Kernel.prototype._on_success = function (success) {
         /**
          * Handle a successful AJAX request by updating the kernel id and
          * name from the response, and then optionally calling a provided
          * callback.
          *
          * @function _on_success
          * @param {function} success - callback
          */
         var that = this;
         return function (data, status, xhr) {
             if (data) {
                 that.id = data.id;
                 that.name = data.name;
             }
             that.kernel_url = utils.url_join_encode(that.kernel_service_url, that.id);
             if (success) {
                 success(data, status, xhr);
             }
         };
     };
 
     Kernel.prototype._on_error = function (error) {
         /**
          * Handle a failed AJAX request by logging the error message, and
          * then optionally calling a provided callback.
          *
          * @function _on_error
          * @param {function} error - callback
          */
         return function (xhr, status, err) {
             utils.log_ajax_error(xhr, status, err);
             if (error) {
                 error(xhr, status, err);
             }
         };
     };
 
     Kernel.prototype._kernel_created = function (data) {
         /**
          * Perform necessary tasks once the kernel has been started,
          * including actually connecting to the kernel.
          *
          * @function _kernel_created
          * @param {Object} data - information about the kernel including id
          */
         this.id = data.id;
         this.kernel_url = utils.url_join_encode(this.kernel_service_url, this.id);
         this.start_channels();
     };
 
     Kernel.prototype._kernel_connected = function () {
         /**
          * Perform necessary tasks once the connection to the kernel has
          * been established. This includes requesting information about
          * the kernel.
          *
          * @function _kernel_connected
          */
         this.events.trigger('kernel_connected.Kernel', {kernel: this});
         this.events.trigger('kernel_starting.Kernel', {kernel: this});
         // get kernel info so we know what state the kernel is in
         var that = this;
         this.kernel_info(function (reply) {
             that.info_reply = reply.content;
             that.events.trigger('kernel_ready.Kernel', {kernel: that});
         });
     };
 
     Kernel.prototype._kernel_dead = function () {
         /**
          * Perform necessary tasks after the kernel has died. This closing
          * communication channels to the kernel if they are still somehow
          * open.
          *
          * @function _kernel_dead
          */
         this.stop_channels();
     };
 
     Kernel.prototype.start_channels = function () {
         /**
          * Start the `shell`and `iopub` channels.
          * Will stop and restart them if they already exist.
          *
          * @function start_channels
          */
         var that = this;
         this.stop_channels();
         var ws_host_url = this.ws_url + this.kernel_url;
 
         console.log("Starting WebSockets:", ws_host_url);
         
         var channel_url = function(channel) {
             return [
                 that.ws_url,
                 utils.url_join_encode(that.kernel_url, channel),
                 "?session_id=" + that.session_id
             ].join('');
         };
         this.channels.shell = new this.WebSocket(channel_url("shell"));
         this.channels.stdin = new this.WebSocket(channel_url("stdin"));
         this.channels.iopub = new this.WebSocket(channel_url("iopub"));
         
         var already_called_onclose = false; // only alert once
         var ws_closed_early = function(evt){
             if (already_called_onclose){
                 return;
             }
             already_called_onclose = true;
             if ( ! evt.wasClean ){
                 // If the websocket was closed early, that could mean
                 // that the kernel is actually dead. Try getting
                 // information about the kernel from the API call --
                 // if that fails, then assume the kernel is dead,
                 // otherwise just follow the typical websocket closed
                 // protocol.
                 that.get_info(function () {
                     that._ws_closed(ws_host_url, false);
                 }, function () {
                     that.events.trigger('kernel_dead.Kernel', {kernel: that});
                     that._kernel_dead();
                 });
             }
         };
         var ws_closed_late = function(evt){
             if (already_called_onclose){
                 return;
             }
             already_called_onclose = true;
             if ( ! evt.wasClean ){
                 that._ws_closed(ws_host_url, false);
             }
         };
         var ws_error = function(evt){
             if (already_called_onclose){
                 return;
             }
             already_called_onclose = true;
             that._ws_closed(ws_host_url, true);
         };
 
         for (var c in this.channels) {
             this.channels[c].onopen = $.proxy(this._ws_opened, this);
             this.channels[c].onclose = ws_closed_early;
             this.channels[c].onerror = ws_error;
         }
         // switch from early-close to late-close message after 1s
         setTimeout(function() {
             for (var c in that.channels) {
                 if (that.channels[c] !== null) {
                     that.channels[c].onclose = ws_closed_late;
                 }
             }
         }, 1000);
         this.channels.shell.onmessage = $.proxy(this._handle_shell_reply, this);
         this.channels.iopub.onmessage = $.proxy(this._handle_iopub_message, this);
         this.channels.stdin.onmessage = $.proxy(this._handle_input_request, this);
     };
 
     Kernel.prototype._ws_opened = function (evt) {
         /**
          * Handle a websocket entering the open state,
          * signaling that the kernel is connected when all channels are open.
          *
          * @function _ws_opened
          */
         if (this.is_connected()) {
             // all events ready, trigger started event.
             this._kernel_connected();
         }
     };
 
     Kernel.prototype._ws_closed = function(ws_url, error) {
         /**
          * Handle a websocket entering the closed state. This closes the
          * other communication channels if they are open. If the websocket
          * was not closed due to an error, try to reconnect to the kernel.
          *
          * @function _ws_closed
          * @param {string} ws_url - the websocket url
          * @param {bool} error - whether the connection was closed due to an error
          */
         this.stop_channels();
 
         this.events.trigger('kernel_disconnected.Kernel', {kernel: this});
         if (error) {
             console.log('WebSocket connection failed: ', ws_url);
             this.events.trigger('kernel_connection_failed.Kernel', {kernel: this, ws_url: ws_url, attempt: this._reconnect_attempt});
         }
         this._schedule_reconnect();
     };
     
     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.");
             setTimeout($.proxy(this.reconnect, this), 1e3 * timeout);
         } else {
             this.events.trigger('kernel_connection_dead.Kernel', {
                 kernel: this,
                 reconnect_attempt: this._reconnect_attempt,
             });
             console.log("Failed to reconnect, giving up.");
         }
     };
     
     Kernel.prototype.stop_channels = function () {
         /**
          * Close the websocket channels. After successful close, the value
          * in `this.channels[channel_name]` will be null.
          *
          * @function stop_channels
          */
         var that = this;
         var close = function (c) {
             return function () {
                 if (that.channels[c] && that.channels[c].readyState === WebSocket.CLOSED) {
                     that.channels[c] = null;
                 }
             };
         };
         for (var c in this.channels) {
             if ( this.channels[c] !== null ) {
                 if (this.channels[c].readyState === WebSocket.OPEN) {
                     this.channels[c].onclose = close(c);
                     this.channels[c].close();
                 } else {
                     close(c)();
                 }
             }
         }
     };
 
     Kernel.prototype.is_connected = function () {
         /**
          * Check whether there is a connection to the kernel. This
          * function only returns true if all channel objects have been
          * created and have a state of WebSocket.OPEN.
          *
          * @function is_connected
          * @returns {bool} - whether there is a connection
          */
         for (var c in this.channels) {
             // if any channel is not ready, then we're not connected
             if (this.channels[c] === null) {
                 return false;
             }
             if (this.channels[c].readyState !== WebSocket.OPEN) {
                 return false;
             }
         }
         return true;
     };
 
     Kernel.prototype.is_fully_disconnected = function () {
         /**
          * Check whether the connection to the kernel has been completely
          * severed. This function only returns true if all channel objects
          * are null.
          *
          * @function is_fully_disconnected
          * @returns {bool} - whether the kernel is fully disconnected
          */
         for (var c in this.channels) {
             if (this.channels[c] === null) {
                 return true;
             }
         }
         return false;
     };
     
     Kernel.prototype.send_shell_message = function (msg_type, content, callbacks, metadata, buffers) {
         /**
          * Send a message on the Kernel's shell channel
          *
          * @function send_shell_message
          */
         if (!this.is_connected()) {
             throw new Error("kernel is not connected");
         }
         var msg = this._get_msg(msg_type, content, metadata, buffers);
         this.channels.shell.send(serialize.serialize(msg));
         this.set_callbacks_for_msg(msg.header.msg_id, callbacks);
         return msg.header.msg_id;
     };
 
     Kernel.prototype.kernel_info = function (callback) {
         /**
          * Get kernel info
          *
          * @function kernel_info
          * @param callback {function}
          *
          * When calling this method, pass a callback function that expects one argument.
          * The callback will be passed the complete `kernel_info_reply` message documented
          * [here](http://ipython.org/ipython-doc/dev/development/messaging.html#kernel-info)
          */
         var callbacks;
         if (callback) {
             callbacks = { shell : { reply : callback } };
         }
         return this.send_shell_message("kernel_info_request", {}, callbacks);
     };
 
     Kernel.prototype.inspect = function (code, cursor_pos, callback) {
         /**
          * Get info on an object
          *
          * When calling this method, pass a callback function that expects one argument.
          * The callback will be passed the complete `inspect_reply` message documented
          * [here](http://ipython.org/ipython-doc/dev/development/messaging.html#object-information)
          *
          * @function inspect
          * @param code {string}
          * @param cursor_pos {integer}
          * @param callback {function}
          */
         var callbacks;
         if (callback) {
             callbacks = { shell : { reply : callback } };
         }
         
         var content = {
             code : code,
             cursor_pos : cursor_pos,
             detail_level : 0
         };
         return this.send_shell_message("inspect_request", content, callbacks);
     };
 
     Kernel.prototype.execute = function (code, callbacks, options) {
         /**
          * Execute given code into kernel, and pass result to callback.
          *
          * @async
          * @function execute
          * @param {string} code
          * @param [callbacks] {Object} With the following keys (all optional)
          *      @param callbacks.shell.reply {function}
          *      @param callbacks.shell.payload.[payload_name] {function}
          *      @param callbacks.iopub.output {function}
          *      @param callbacks.iopub.clear_output {function}
          *      @param callbacks.input {function}
          * @param {object} [options]
          *      @param [options.silent=false] {Boolean}
          *      @param [options.user_expressions=empty_dict] {Dict}
          *      @param [options.allow_stdin=false] {Boolean} true|false
          *
          * @example
          *
          * The options object should contain the options for the execute
          * call. Its default values are:
          *
          *      options = {
          *        silent : true,
          *        user_expressions : {},
          *        allow_stdin : false
          *      }
          *
          * When calling this method pass a callbacks structure of the
          * form:
          *
          *      callbacks = {
          *       shell : {
          *         reply : execute_reply_callback,
          *         payload : {
          *           set_next_input : set_next_input_callback,
          *         }
          *       },
          *       iopub : {
          *         output : output_callback,
          *         clear_output : clear_output_callback,
          *       },
          *       input : raw_input_callback
          *      }
          *
          * Each callback will be passed the entire message as a single
          * arugment.  Payload handlers will be passed the corresponding
          * payload and the execute_reply message.
          */
         var content = {
             code : code,
             silent : true,
             store_history : false,
             user_expressions : {},
             allow_stdin : false
         };
         callbacks = callbacks || {};
         if (callbacks.input !== undefined) {
             content.allow_stdin = true;
         }
         $.extend(true, content, options);
         this.events.trigger('execution_request.Kernel', {kernel: this, content: content});
         return this.send_shell_message("execute_request", content, callbacks);
     };
 
     /**
      * When calling this method, pass a function to be called with the
      * `complete_reply` message as its only argument when it arrives.
      *
      * `complete_reply` is documented
      * [here](http://ipython.org/ipython-doc/dev/development/messaging.html#complete)
      *
      * @function complete
      * @param code {string}
      * @param cursor_pos {integer}
      * @param callback {function}
      */
     Kernel.prototype.complete = function (code, cursor_pos, callback) {
         var callbacks;
         if (callback) {
             callbacks = { shell : { reply : callback } };
         }
         var content = {
             code : code,
             cursor_pos : cursor_pos
         };
         return this.send_shell_message("complete_request", content, callbacks);
     };
 
     /**
      * @function send_input_reply
      */
     Kernel.prototype.send_input_reply = function (input) {
         if (!this.is_connected()) {
             throw new Error("kernel is not connected");
         }
         var content = {
             value : input
         };
         this.events.trigger('input_reply.Kernel', {kernel: this, content: content});
         var msg = this._get_msg("input_reply", content);
         this.channels.stdin.send(serialize.serialize(msg));
         return msg.header.msg_id;
     };
 
     /**
      * @function register_iopub_handler
      */
     Kernel.prototype.register_iopub_handler = function (msg_type, callback) {
         this._iopub_handlers[msg_type] = callback;
     };
 
     /**
      * Get the iopub handler for a specific message type.
      *
      * @function get_iopub_handler
      */
     Kernel.prototype.get_iopub_handler = function (msg_type) {
         return this._iopub_handlers[msg_type];
     };
 
     /**
      * Get callbacks for a specific message.
      *
      * @function get_callbacks_for_msg
      */
     Kernel.prototype.get_callbacks_for_msg = function (msg_id) {
         if (msg_id == this.last_msg_id) {
             return this.last_msg_callbacks;
         } else {
             return this._msg_callbacks[msg_id];
         }
     };
 
     /**
      * Clear callbacks for a specific message.
      *
      * @function clear_callbacks_for_msg
      */
     Kernel.prototype.clear_callbacks_for_msg = function (msg_id) {
         if (this._msg_callbacks[msg_id] !== undefined ) {
             delete this._msg_callbacks[msg_id];
         }
     };
     
     /**
      * @function _finish_shell
      */
     Kernel.prototype._finish_shell = function (msg_id) {
         var callbacks = this._msg_callbacks[msg_id];
         if (callbacks !== undefined) {
             callbacks.shell_done = true;
             if (callbacks.iopub_done) {
                 this.clear_callbacks_for_msg(msg_id);
             }
         }
     };
 
     /**
      * @function _finish_iopub
      */
     Kernel.prototype._finish_iopub = function (msg_id) {
         var callbacks = this._msg_callbacks[msg_id];
         if (callbacks !== undefined) {
             callbacks.iopub_done = true;
             if (callbacks.shell_done) {
                 this.clear_callbacks_for_msg(msg_id);
             }
         }
     };
     
     /**
      * Set callbacks for a particular message.
      * Callbacks should be a struct of the following form:
      * shell : {
      * 
      * }
      *
      * @function set_callbacks_for_msg
      */
     Kernel.prototype.set_callbacks_for_msg = function (msg_id, callbacks) {
         this.last_msg_id = msg_id;
         if (callbacks) {
             // shallow-copy mapping, because we will modify it at the top level
             var cbcopy = this._msg_callbacks[msg_id] = this.last_msg_callbacks = {};
             cbcopy.shell = callbacks.shell;
             cbcopy.iopub = callbacks.iopub;
             cbcopy.input = callbacks.input;
             cbcopy.shell_done = (!callbacks.shell);
             cbcopy.iopub_done = (!callbacks.iopub);
         } else {
             this.last_msg_callbacks = {};
         }
     };
 
     /**
      * @function _handle_shell_reply
      */
     Kernel.prototype._handle_shell_reply = function (e) {
         serialize.deserialize(e.data, $.proxy(this._finish_shell_reply, this));
     };
 
     Kernel.prototype._finish_shell_reply = function (reply) {
         this.events.trigger('shell_reply.Kernel', {kernel: this, reply:reply});
         var content = reply.content;
         var metadata = reply.metadata;
         var parent_id = reply.parent_header.msg_id;
         var callbacks = this.get_callbacks_for_msg(parent_id);
         if (!callbacks || !callbacks.shell) {
             return;
         }
         var shell_callbacks = callbacks.shell;
         
         // signal that shell callbacks are done
         this._finish_shell(parent_id);
         
         if (shell_callbacks.reply !== undefined) {
             shell_callbacks.reply(reply);
         }
         if (content.payload && shell_callbacks.payload) {
             this._handle_payloads(content.payload, shell_callbacks.payload, reply);
         }
     };
 
     /**
      * @function _handle_payloads
      */
     Kernel.prototype._handle_payloads = function (payloads, payload_callbacks, msg) {
         var l = payloads.length;
         // Payloads are handled by triggering events because we don't want the Kernel
         // to depend on the Notebook or Pager classes.
         for (var i=0; i<l; i++) {
             var payload = payloads[i];
             var callback = payload_callbacks[payload.source];
             if (callback) {
                 callback(payload, msg);
             }
         }
     };
 
     /**
      * @function _handle_status_message
      */
     Kernel.prototype._handle_status_message = function (msg) {
         var execution_state = msg.content.execution_state;
         var parent_id = msg.parent_header.msg_id;
         
         // dispatch status msg callbacks, if any
         var callbacks = this.get_callbacks_for_msg(parent_id);
         if (callbacks && callbacks.iopub && callbacks.iopub.status) {
             try {
                 callbacks.iopub.status(msg);
             } catch (e) {
                 console.log("Exception in status msg handler", e, e.stack);
             }
         }
         
         if (execution_state === 'busy') {
             this.events.trigger('kernel_busy.Kernel', {kernel: this});
 
         } else if (execution_state === 'idle') {
             // signal that iopub callbacks are (probably) done
             // async output may still arrive,
             // but only for the most recent request
             this._finish_iopub(parent_id);
             
             // trigger status_idle event
             this.events.trigger('kernel_idle.Kernel', {kernel: this});
 
         } else if (execution_state === 'starting') {
             this.events.trigger('kernel_starting.Kernel', {kernel: this});
             var that = this;
             this.kernel_info(function (reply) {
                 that.info_reply = reply.content;
                 that.events.trigger('kernel_ready.Kernel', {kernel: that});
             });
 
         } else if (execution_state === 'restarting') {
             // autorestarting is distinct from restarting,
             // in that it means the kernel died and the server is restarting it.
             // kernel_restarting sets the notification widget,
             // autorestart shows the more prominent dialog.
             this._autorestart_attempt = this._autorestart_attempt + 1;
             this.events.trigger('kernel_restarting.Kernel', {kernel: this});
             this.events.trigger('kernel_autorestarting.Kernel', {kernel: this, attempt: this._autorestart_attempt});
 
         } else if (execution_state === 'dead') {
             this.events.trigger('kernel_dead.Kernel', {kernel: this});
             this._kernel_dead();
         }
     };
     
     /**
      * Handle clear_output message
      *
      * @function _handle_clear_output
      */
     Kernel.prototype._handle_clear_output = function (msg) {
         var callbacks = this.get_callbacks_for_msg(msg.parent_header.msg_id);
         if (!callbacks || !callbacks.iopub) {
             return;
         }
         var callback = callbacks.iopub.clear_output;
         if (callback) {
             callback(msg);
         }
     };
 
     /**
      * handle an output message (execute_result, display_data, etc.)
      *
      * @function _handle_output_message
      */
     Kernel.prototype._handle_output_message = function (msg) {
         var callbacks = this.get_callbacks_for_msg(msg.parent_header.msg_id);
         if (!callbacks || !callbacks.iopub) {
             return;
         }
         var callback = callbacks.iopub.output;
         if (callback) {
             callback(msg);
         }
     };
 
     /**
      * Dispatch IOPub messages to respective handlers. Each message
      * type should have a handler.
      *
      * @function _handle_iopub_message
      */
     Kernel.prototype._handle_iopub_message = function (e) {
         serialize.deserialize(e.data, $.proxy(this._finish_iopub_message, this));
     };
 
 
     Kernel.prototype._finish_iopub_message = function (msg) {
         var handler = this.get_iopub_handler(msg.header.msg_type);
         if (handler !== undefined) {
             handler(msg);
         }
     };
 
     /**
      * @function _handle_input_request
      */
     Kernel.prototype._handle_input_request = function (e) {
         serialize.deserialize(e.data, $.proxy(this._finish_input_request, this));
     };
 
 
     Kernel.prototype._finish_input_request = function (request) {
         var header = request.header;
         var content = request.content;
         var metadata = request.metadata;
         var msg_type = header.msg_type;
         if (msg_type !== 'input_request') {
             console.log("Invalid input request!", request);
             return;
         }
         var callbacks = this.get_callbacks_for_msg(request.parent_header.msg_id);
         if (callbacks) {
             if (callbacks.input) {
                 callbacks.input(request);
             }
         }
     };
 
     // Backwards compatability.
     IPython.Kernel = Kernel;
 
     return {'Kernel': Kernel};
 });

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

@@ -1,114 +1,120 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'underscore',
     ], function (_) {
     "use strict";
     
     var _deserialize_array_buffer = function (buf) {
         var data = new DataView(buf);
         // read the header: 1 + nbufs 32b integers
         var nbufs = data.getUint32(0);
         var offsets = [];
         var i;
         for (i = 1; i <= nbufs; i++) {
             offsets.push(data.getUint32(i * 4));
         }
         var json_bytes = new Uint8Array(buf.slice(offsets[0], offsets[1]));
         var msg = JSON.parse(
             (new TextDecoder('utf8')).decode(json_bytes)
         );
         // the remaining chunks are stored as DataViews in msg.buffers
         msg.buffers = [];
         var start, stop;
         for (i = 1; i < nbufs; i++) {
             start = offsets[i];
             stop = offsets[i+1] || buf.byteLength;
             msg.buffers.push(new DataView(buf.slice(start, stop)));
         }
         return msg;
     };
     
     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();
             reader.onload = function () {
                 var msg = _deserialize_array_buffer(this.result);
                 callback(msg);
             };
             reader.readAsArrayBuffer(data);
         } else {
             // data is ArrayBuffer, can deserialize directly
             var msg = _deserialize_array_buffer(data);
             callback(msg);
         }
     };
 
     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));
         } else {
             // binary message
             _deserialize_binary(data, callback);
         }
     };
     
     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 = [];
         msg.buffers.map(function (buf) {
             buffers.push(buf);
         });
         delete msg.buffers;
         var json_utf8 = (new TextEncoder('utf8')).encode(JSON.stringify(msg));
         buffers.unshift(json_utf8);
         var nbufs = buffers.length;
         offsets.push(4 * (nbufs + 1));
         var i;
         for (i = 0; i + 1 < buffers.length; i++) {
             offsets.push(offsets[offsets.length-1] + buffers[i].byteLength);
         }
         var msg_buf = new Uint8Array(
             offsets[offsets.length-1] + buffers[buffers.length-1].byteLength
         );
         // use DataView.setUint32 for network byte-order
         var view = new DataView(msg_buf.buffer);
         // write nbufs to first 4 bytes
         view.setUint32(0, nbufs);
         // write offsets to next 4 * nbufs bytes
         for (i = 0; i < offsets.length; i++) {
             view.setUint32(4 * (i+1), offsets[i]);
         }
         // write all the buffers at their respective offsets
         for (i = 0; i < buffers.length; i++) {
             msg_buf.set(new Uint8Array(buffers[i].buffer), offsets[i]);
         }
         
         // return raw ArrayBuffer
         return msg_buf.buffer;
     };
     
     var serialize = function (msg) {
         if (msg.buffers && msg.buffers.length) {
             return _serialize_binary(msg);
         } else {
             return JSON.stringify(msg);
         }
     };
     
     var exports = {
         deserialize : deserialize,
         serialize: serialize
     };
     return exports;
 });
  No newline at end of file

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

@@ -1,55 +1,59 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'tree/js/notebooklist',
 ], function(IPython, $, notebooklist) {
     "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));
     };
 
     KernelList.prototype = Object.create(notebooklist.NotebookList.prototype);
 
     KernelList.prototype.add_duplicate_button = function () {
-        // do nothing
+        /**
+         * do nothing
+         */
     };
     
     KernelList.prototype.sessions_loaded = function (d) {
         this.sessions = d;
         this.clear_list();
         var item, path;
         for (path in d) {
             if (!d.hasOwnProperty(path)) {
                 // nothing is safe in javascript
                 continue;
             }
             item = this.new_item(-1);
             this.add_link({
                 name: path,
                 path: path,
                 type: 'notebook',
             }, item);
         }
         $('#running_list_header').toggle($.isEmptyObject(d));
     };
     
     // Backwards compatability.
     IPython.KernelList = KernelList;
 
     return {'KernelList': KernelList};
 });

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

@@ -1,152 +1,154 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 require([
     'jquery',
     'base/js/namespace',
     'base/js/dialog',
     'base/js/events',
     'base/js/page',
     'base/js/utils',
     'contents',
     'tree/js/notebooklist',
     'tree/js/clusterlist',
     'tree/js/sessionlist',
     'tree/js/kernellist',
     'tree/js/terminallist',
     'auth/js/loginwidget',
     // only loaded, not used:
     'jqueryui',
     'bootstrap',
     'custom/custom',
 ], function(
     $,
     IPython,
     dialog,
     events,
     page,
     utils,
     contents_service,
     notebooklist, 
     clusterlist, 
     sesssionlist, 
     kernellist,
     terminallist,
     loginwidget){
     "use strict";
 
     page = new page.Page();
     
     var common_options = {
         base_url: utils.get_body_data("baseUrl"),
         notebook_path: utils.get_body_data("notebookPath"),
     };
     var session_list = new sesssionlist.SesssionList($.extend({
         events: events}, 
         common_options));
     var contents = new contents_service.Contents($.extend({
         events: events},
         common_options));
     var notebook_list = new notebooklist.NotebookList('#notebook_list', $.extend({
         contents: contents,
         session_list:  session_list}, 
         common_options));
     var cluster_list = new clusterlist.ClusterList('#cluster_list', common_options);
     var kernel_list = new kernellist.KernelList('#running_list',  $.extend({
         session_list:  session_list}, 
         common_options));
     
     var terminal_list;
     if (utils.get_body_data("terminalsAvailable") === "True") {
         terminal_list = new terminallist.TerminalList('#terminal_list', common_options);
     }
 
     var login_widget = new loginwidget.LoginWidget('#login_widget', common_options);
 
     $('#new_notebook').click(function (e) {
         var w = window.open();
         contents.new_untitled(common_options.notebook_path, {type: "notebook"}).then(
                 function (data) {
                     w.location = utils.url_join_encode(
                             common_options.base_url, 'notebooks', data.path
                         );
                 },
                 function(error) {
                     w.close();
                     dialog.modal({
                         title : 'Creating Notebook Failed',
                         body : "The error was: " + error.message,
                         buttons : {'OK' : {'class' : 'btn-primary'}}
                     });
                 }
             );
     });
 
     var interval_id=0;
     // auto refresh every xx secondes, no need to be fast,
     //  update is done at least when page get focus
     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) {
 	    terminal_list.load_terminals();
 	}
         if (!interval_id){
             interval_id = setInterval(function(){
                     session_list.load_sessions();
                     cluster_list.load_list();
 		    if (terminal_list) {
 		        terminal_list.load_terminals();
 		    }
                 }, time_refresh*1000);
             }
     };
 
     var disable_autorefresh = function(){
         clearInterval(interval_id);
         interval_id = 0;
     };
 
     // stop autorefresh when page lose focus
     $(window).blur(function() {
         disable_autorefresh();
     });
 
     //re-enable when page get focus back
     $(window).focus(function() {
         enable_autorefresh();
     });
 
     // finally start it, it will refresh immediately
     enable_autorefresh();
 
     page.show();
 
     // For backwards compatability.
     IPython.page = page;
     IPython.notebook_list = notebook_list;
     IPython.cluster_list = cluster_list;
     IPython.session_list = session_list;
     IPython.kernel_list = kernel_list;
     IPython.login_widget = login_widget;
 
     events.trigger('app_initialized.DashboardApp');
     
     // bound the upload method to the on change of the file select list
     $("#alternate_upload").change(function (event){
         notebook_list.handleFilesUpload(event,'form');
     });
     
     // set hash on tab click
     $("#tabs").find("a").click(function() {
         window.location.hash = $(this).attr("href");
     });
     
     // load tab if url hash
     if (window.location.hash) {
         $("#tabs").find("a[href=" + window.location.hash + "]").click();
     }
 });

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

@@ -1,502 +1,508 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
     'base/js/dialog',
     'base/js/events',
 ], function(IPython, $, utils, dialog, events) {
     "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
         this.element_name = options.element_name || 'notebook';
         this.selector = selector;
         if (this.selector !== undefined) {
             this.element = $(selector);
             this.style();
             this.bind_events();
         }
         this.notebooks_list = [];
         this.sessions = {};
         this.base_url = options.base_url || utils.get_body_data("baseUrl");
         this.notebook_path = options.notebook_path || utils.get_body_data("notebookPath");
         this.contents = options.contents;
         if (this.session_list && this.session_list.events) {
             this.session_list.events.on('sessions_loaded.Dashboard', 
                 function(e, d) { that.sessions_loaded(d); });
         }
     };
 
     NotebookList.prototype.style = function () {
         var prefix = '#' + this.element_name;
         $(prefix + '_toolbar').addClass('list_toolbar');
         $(prefix + '_list_info').addClass('toolbar_info');
         $(prefix + '_buttons').addClass('toolbar_buttons');
         $(prefix + '_list_header').addClass('list_header');
         this.element.addClass("list_container");
     };
 
 
     NotebookList.prototype.bind_events = function () {
         var that = this;
         $('#refresh_' + this.element_name + '_list').click(function () {
             that.load_sessions();
         });
         this.element.bind('dragover', function () {
             return false;
         });
         this.element.bind('drop', function(event){
             that.handleFilesUpload(event,'drop');
             return false;
         });
     };
 
     NotebookList.prototype.handleFilesUpload =  function(event, dropOrForm) {
         var that = this;
         var files;
         if(dropOrForm =='drop'){
             files = event.originalEvent.dataTransfer.files;
         } else 
         {
             files = event.originalEvent.target.files;
         }
         for (var i = 0; i < files.length; i++) {
             var f = files[i];
             var name_and_ext = utils.splitext(f.name);
             var file_ext = name_and_ext[1];
 
             var reader = new FileReader();
             if (file_ext === '.ipynb') {
                 reader.readAsText(f);
             } else {
                 // read non-notebook files as binary
                 reader.readAsArrayBuffer(f);
             }
             var item = that.new_item(0);
             item.addClass('new-file');
             that.add_name_input(f.name, item, file_ext == '.ipynb' ? 'notebook' : 'file');
             // Store the list item in the reader so we can use it later
             // to know which item it belongs to.
             $(reader).data('item', item);
             reader.onload = function (event) {
                 var item = $(event.target).data('item');
                 that.add_file_data(event.target.result, item);
                 that.add_upload_button(item);
             };
             reader.onerror = function (event) {
                 var item = $(event.target).data('item');
                 var name = item.data('name');
                 item.remove();
                 dialog.modal({
                     title : 'Failed to read file',
                     body : "Failed to read file '" + name + "'",
                     buttons : {'OK' : { 'class' : 'btn-primary' }}
                 });
             };
         }
         // Replace the file input form wth a clone of itself. This is required to
         // reset the form. Otherwise, if you upload a file, delete it and try to 
         // upload it again, the changed event won't fire.
         var form = $('input.fileinput');
         form.replaceWith(form.clone(true));
         return false;
     };
 
     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 {
             this.element.children('.list_item:not(.new-file)').remove();  
         }
     };
 
     NotebookList.prototype.load_sessions = function(){
         this.session_list.load_sessions();
     };
 
 
     NotebookList.prototype.sessions_loaded = function(data){
         this.sessions = data;
         this.load_list();
     };
 
     NotebookList.prototype.load_list = function () {
         var that = this;
         this.contents.list_contents(that.notebook_path).then(
             $.proxy(this.draw_notebook_list, this),
             function(error) {
                 that.draw_notebook_list({content: []}, "Server error: " + error.message);
             }
         );
     };
 
     /**
      * Draw the list of notebooks
      * @method draw_notebook_list
      * @param {Array} list An array of dictionaries representing files or
      *     directories.
      * @param {String} error_msg An error message
      */
     NotebookList.prototype.draw_notebook_list = function (list, error_msg) {
         var message = error_msg || 'Notebook list empty.';
         var item = null;
         var model = null;
         var len = list.content.length;
         this.clear_list();
         var n_uploads = this.element.children('.list_item').length;
         if (len === 0) {
             item = this.new_item(0);
             var span12 = item.children().first();
             span12.empty();
             span12.append($('<div style="margin:auto;text-align:center;color:grey"/>').text(message));
         }
         var path = this.notebook_path;
         var offset = n_uploads;
         if (path !== '') {
             item = this.new_item(offset);
             model = {
                 type: 'directory',
                 name: '..',
                 path: utils.url_path_split(path)[0],
             };
             this.add_link(model, item);
             offset += 1;
         }
         for (var i=0; i<len; i++) {
             model = list.content[i];
             item = this.new_item(i+offset);
             this.add_link(model, item);
         }
         // Trigger an event when we've finished drawing the notebook list.
         events.trigger('draw_notebook_list.NotebookList');
     };
 
 
     NotebookList.prototype.new_item = function (index) {
         var item = $('<div/>').addClass("list_item").addClass("row");
         // item.addClass('list_item ui-widget ui-widget-content ui-helper-clearfix');
         // item.css('border-top-style','none');
         item.append($("<div/>").addClass("col-md-12").append(
             $('<i/>').addClass('item_icon')
         ).append(
             $("<a/>").addClass("item_link").append(
                 $("<span/>").addClass("item_name")
             )
         ).append(
             $('<div/>').addClass("item_buttons btn-group pull-right")
         ));
         
         if (index === -1) {
             this.element.append(item);
         } else {
             this.element.children().eq(index).after(item);
         }
         return item;
     };
 
 
     NotebookList.icons = {
         directory: 'folder_icon',
         notebook: 'notebook_icon',
         file: 'file_icon',
     };
 
     NotebookList.uri_prefixes = {
         directory: 'tree',
         notebook: 'notebooks',
         file: 'files',
     };
 
 
     NotebookList.prototype.add_link = function (model, item) {
         var path = model.path,
             name = model.name;
         item.data('name', name);
         item.data('path', path);
         item.find(".item_name").text(name);
         var icon = NotebookList.icons[model.type];
         var uri_prefix = NotebookList.uri_prefixes[model.type];
         item.find(".item_icon").addClass(icon).addClass('icon-fixed-width');
         var link = item.find("a.item_link")
             .attr('href',
                 utils.url_join_encode(
                     this.base_url,
                     uri_prefix,
                     path
                 )
             );
         // directory nav doesn't open new tabs
         // files, notebooks do
         if (model.type !== "directory") {
             link.attr('target','_blank');
         }
         if (model.type !== 'directory') {
             this.add_duplicate_button(item);
         }
         if (model.type == 'file') {
             this.add_delete_button(item);
         } else if (model.type == 'notebook') {
             if (this.sessions[path] === undefined){
                 this.add_delete_button(item);
             } else {
                 this.add_shutdown_button(item, this.sessions[path]);
             }
         }
     };
 
 
     NotebookList.prototype.add_name_input = function (name, item, icon_type) {
         item.data('name', name);
         item.find(".item_icon").addClass(NotebookList.icons[icon_type]).addClass('icon-fixed-width');
         item.find(".item_name").empty().append(
             $('<input/>')
             .addClass("filename_input")
             .attr('value', name)
             .attr('size', '30')
             .attr('type', 'text')
             .keyup(function(event){
                 if(event.keyCode == 13){item.find('.upload_button').click();}
                 else if(event.keyCode == 27){item.remove();}
             })
         );
     };
 
 
     NotebookList.prototype.add_file_data = function (data, item) {
         item.data('filedata', data);
     };
 
 
     NotebookList.prototype.add_shutdown_button = function (item, session) {
         var that = this;
         var shutdown_button = $("<button/>").text("Shutdown").addClass("btn btn-xs btn-danger").
             click(function (e) {
                 var settings = {
                     processData : false,
                     cache : false,
                     type : "DELETE",
                     dataType : "json",
                     success : function () {
                         that.load_sessions();
                     },
                     error : utils.log_ajax_error,
                 };
                 var url = utils.url_join_encode(
                     that.base_url,
                     'api/sessions',
                     session
                 );
                 $.ajax(url, settings);
                 return false;
             });
         item.find(".item_buttons").append(shutdown_button);
     };
 
     NotebookList.prototype.add_duplicate_button = function (item) {
         var notebooklist = this;
         var duplicate_button = $("<button/>").text("Duplicate").addClass("btn btn-default btn-xs").
             click(function (e) {
                 // $(this) is the button that was clicked.
                 var that = $(this);
                 var name = item.data('name');
                 var path = item.data('path');
                 var message = 'Are you sure you want to duplicate ' + name + '?';
                 var copy_from = {copy_from : path};
                 IPython.dialog.modal({
                     title : "Duplicate " + name,
                     body : message,
                     buttons : {
                         Duplicate : {
                             class: "btn-primary",
                             click: function() {
                                 notebooklist.contents.copy(path, notebooklist.notebook_path).then(function () {
                                     notebooklist.load_list();
                                 });
                             }
                         },
                         Cancel : {}
                     }
                 });
                 return false;
             });
         item.find(".item_buttons").append(duplicate_button);
     };
 
     NotebookList.prototype.add_delete_button = function (item) {
         var notebooklist = this;
         var delete_button = $("<button/>").text("Delete").addClass("btn btn-default btn-xs").
             click(function (e) {
                 // $(this) is the button that was clicked.
                 var that = $(this);
                 // We use the filename from the parent list_item element's
                 // data because the outer scope's values change as we iterate through the loop.
                 var parent_item = that.parents('div.list_item');
                 var name = parent_item.data('name');
                 var path = parent_item.data('path');
                 var message = 'Are you sure you want to permanently delete the file: ' + name + '?';
                 dialog.modal({
                     title : "Delete file",
                     body : message,
                     buttons : {
                         Delete : {
                             class: "btn-danger",
                             click: function() {
                                 notebooklist.contents.delete(path).then(
                                     function() {
                                         notebooklist.notebook_deleted(path);
                                     }
                                 );
                             }
                         },
                         Cancel : {}
                     }
                 });
                 return false;
             });
         item.find(".item_buttons").append(delete_button);
     };
 
     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) {
                 element.remove();
                 events.trigger('notebook_deleted.NotebookList');
             }
         });
     };
 
 
     NotebookList.prototype.add_upload_button = function (item) {
         var that = this;
         var upload_button = $('<button/>').text("Upload")
             .addClass('btn btn-primary btn-xs upload_button')
             .click(function (e) {
                 var filename = item.find('.item_name > input').val();
                 var path = utils.url_path_join(that.notebook_path, filename);
                 var filedata = item.data('filedata');
                 var format = 'text';
                 if (filename.length === 0 || filename[0] === '.') {
                     dialog.modal({
                         title : 'Invalid file name',
                         body : "File names must be at least one character and not start with a dot",
                         buttons : {'OK' : { 'class' : 'btn-primary' }}
                     });
                     return false;
                 }
                 if (filedata instanceof ArrayBuffer) {
                     // base64-encode binary file data
                     var bytes = '';
                     var buf = new Uint8Array(filedata);
                     var nbytes = buf.byteLength;
                     for (var i=0; i<nbytes; i++) {
                         bytes += String.fromCharCode(buf[i]);
                     }
                     filedata = btoa(bytes);
                     format = 'base64';
                 }
                 var model = {};
 
                 var name_and_ext = utils.splitext(filename);
                 var file_ext = name_and_ext[1];
                 var content_type;
                 if (file_ext === '.ipynb') {
                     model.type = 'notebook';
                     model.format = 'json';
                     try {
                         model.content = JSON.parse(filedata);
                     } catch (e) {
                         dialog.modal({
                             title : 'Cannot upload invalid Notebook',
                             body : "The error was: " + e,
                             buttons : {'OK' : {
                                 'class' : 'btn-primary',
                                 click: function () {
                                     item.remove();
                                 }
                             }}
                         });
                         return false;
                     }
                     content_type = 'application/json';
                 } else {
                     model.type = 'file';
                     model.format = format;
                     model.content = filedata;
                     content_type = 'application/octet-stream';
                 }
                 filedata = item.data('filedata');
 
                 var on_success = function () {
                     item.removeClass('new-file');
                     that.add_link(model, item);
                     that.add_delete_button(item);
                     that.session_list.load_sessions();
                 };
                 
                 var exists = false;
                 $.each(that.element.find('.list_item:not(.new-file)'), function(k,v){
                     if ($(v).data('name') === filename) { exists = true; return false; }
                 });
                 
                 if (exists) {
                     dialog.modal({
                         title : "Replace file",
                         body : 'There is already a file named ' + filename + ', do you want to replace it?',
                         buttons : {
                             Overwrite : {
                                 class: "btn-danger",
                                 click: function () {
                                     that.contents.save(path, model).then(on_success);
                                 }
                             },
                             Cancel : {
                                 click: function() { item.remove(); }
                             }
                         }
                     });
                 } else {
                     that.contents.save(path, model).then(on_success);
                 }
                 
                 return false;
             });
         var cancel_button = $('<button/>').text("Cancel")
             .addClass("btn btn-default btn-xs")
             .click(function (e) {
                 item.remove();
                 return false;
             });
         item.find(".item_buttons").empty()
             .append(upload_button)
             .append(cancel_button);
     };
 
 
     // Backwards compatability.
     IPython.NotebookList = NotebookList;
 
     return {'NotebookList': NotebookList};
 });

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

@@ -1,53 +1,55 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'jquery',
     'base/js/utils',
 ], function(IPython, $, utils) {
     "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");
     };
     
     SesssionList.prototype.load_sessions = function(){
         var that = this;
         var settings = {
             processData : false,
             cache : false,
             type : "GET",
             dataType : "json",
             success : $.proxy(that.sessions_loaded, this),
             error : utils.log_ajax_error,
         };
         var url = utils.url_join_encode(this.base_url, 'api/sessions');
         $.ajax(url, settings);
     };
 
     SesssionList.prototype.sessions_loaded = function(data){
         this.sessions = {};
         var len = data.length;
         var nb_path;
         for (var i=0; i<len; i++) {
             nb_path = data[i].notebook.path;
             this.sessions[nb_path] = data[i].id;
         }
         this.events.trigger('sessions_loaded.Dashboard', this.sessions);
     };
 
     // Backwards compatability.
     IPython.SesssionList = SesssionList;
 
     return {'SesssionList': SesssionList};
 });

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

@@ -1,120 +1,122 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     'base/js/namespace',
     'base/js/utils',
     'jquery',
     'tree/js/notebooklist',
 ], function(IPython, utils, $, notebooklist) {
     "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;
         this.terminals = [];
         if (this.selector !== undefined) {
             this.element = $(selector);
             this.style();
             this.bind_events();
             this.load_terminals();
         }
     };
 
     TerminalList.prototype = Object.create(notebooklist.NotebookList.prototype);
 
     TerminalList.prototype.bind_events = function () {
         var that = this;
         $('#refresh_' + this.element_name + '_list').click(function () {
             that.load_terminals();
         });
         $('#new_terminal').click($.proxy(this.new_terminal, this));
     };
 
     TerminalList.prototype.new_terminal = function () {
         var w = window.open();
         var base_url = this.base_url;
         var settings = {
             type : "POST",
             dataType: "json",
             success : function (data, status, xhr) {
                 var name = data.name;
                 w.location = utils.url_join_encode(base_url, 'terminals', name);
             },
             error : function(jqXHR, status, error){
                 w.close();
                 utils.log_ajax_error(jqXHR, status, error);
             },
         };
         var url = utils.url_join_encode(
             this.base_url,
             'api/terminals'
         );
         $.ajax(url, settings);
     };
     
     TerminalList.prototype.load_terminals = function() {
         var that = this;
         var url = utils.url_join_encode(this.base_url, 'api/terminals');
         $.ajax(url, {
             type: "GET",
             cache: false,
             dataType: "json",
             success: $.proxy(this.terminals_loaded, this),
             error : utils.log_ajax_error
         });
     };
 
     TerminalList.prototype.terminals_loaded = function (data) {
         this.terminals = data;
         this.clear_list();
         var item, path_name, term;
         for (var i=0; i < this.terminals.length; i++) {
             term = this.terminals[i];
             item = this.new_item(-1);
             this.add_link(term.name, item);
             this.add_shutdown_button(term.name, item);
         }
         $('#terminal_list_header').toggle(data.length === 0);
     };
     
     TerminalList.prototype.add_link = function(name, item) {
         item.data('term-name', name);
         item.find(".item_name").text("terminals/" + name);
         item.find(".item_icon").addClass("fa fa-terminal");
         var link = item.find("a.item_link")
             .attr('href', utils.url_join_encode(this.base_url, "terminals", name));
         link.attr('target', '_blank');
         this.add_shutdown_button(name, item);
     };
     
     TerminalList.prototype.add_shutdown_button = function(name, item) {
         var that = this;
         var shutdown_button = $("<button/>").text("Shutdown").addClass("btn btn-xs btn-danger").
             click(function (e) {
                 var settings = {
                     processData : false,
                     type : "DELETE",
                     dataType : "json",
                     success : function () {
                         that.load_terminals();
                     },
                     error : utils.log_ajax_error,
                 };
                 var url = utils.url_join_encode(that.base_url, 'api/terminals', name);
                 $.ajax(url, settings);
                 return false;
             });
         item.find(".item_buttons").text("").append(shutdown_button);
     };
 
     return {TerminalList: TerminalList};
 });

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

@@ -1,239 +1,255 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     "underscore",
     "backbone",
     "jquery",
     "base/js/utils",
     "base/js/namespace",
 ], function (_, Backbone, $, utils, IPython) {
     "use strict";
     //--------------------------------------------------------------------
     // WidgetManager class
     //--------------------------------------------------------------------
     var WidgetManager = function (comm_manager, notebook) {
-        // Public constructor
+        /**
+         * Public constructor
+         */
         WidgetManager._managers.push(this);
 
         // Attach a comm manager to the 
         this.keyboard_manager = notebook.keyboard_manager;
         this.notebook = notebook;
         this.comm_manager = comm_manager;
         this._models = {}; /* Dictionary of model ids and model instances */
 
         // Register with the comm manager.
         this.comm_manager.register_target('ipython.widget', $.proxy(this._handle_comm_open, this));
     };
 
     //--------------------------------------------------------------------
     // Class level
     //--------------------------------------------------------------------
     WidgetManager._model_types = {}; /* Dictionary of model type names (target_name) and model types. */
     WidgetManager._view_types = {}; /* Dictionary of view names and view types. */
     WidgetManager._managers = []; /* List of widget managers */
 
     WidgetManager.register_widget_model = function (model_name, model_type) {
         // Registers a widget model by name.
         WidgetManager._model_types[model_name] = model_type;
     };
 
     WidgetManager.register_widget_view = function (view_name, view_type) {
         // Registers a widget view by name.
         WidgetManager._view_types[view_name] = view_type;
     };
 
     //--------------------------------------------------------------------
     // 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) {
             return Promise.reject(new Error("Could not determine where the display" +
                                             " message was from.  Widget will not be displayed"));
         } else if (cell.widget_subarea) {
             var dummy = $('<div />');
             cell.widget_subarea.append(dummy);
             return this.create_view(model, {cell: cell}).then(
                 function(view) {
                     that._handle_display_view(view);
                     dummy.replaceWith(view.$el);
                     view.trigger('displayed');
                     return view;
                 }).catch(utils.reject('Could not display view', true));
         }
     };
 
     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);
         
             if (view.additional_elements) {
                 for (var i = 0; i < view.additional_elements.length; i++) {
                     this.keyboard_manager.register_events(view.additional_elements[i]);
                 }
             } 
         }
     };
     
     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'),
             WidgetManager._view_types).then(function(ViewType) {
 
                 // If a view is passed into the method, use that view's cell as
                 // the cell for the view that is created.
                 options = options || {};
                 if (options.parent !== undefined) {
                     options.cell = options.parent.options.cell;
                 }
                 // Create and render the view...
                 var parameters = {model: model, options: options};
                 var view = new ViewType(parameters);
                 view.listenTo(model, 'destroy', view.remove);
                 return Promise.resolve(view.render()).then(function() {return view;});
             }).catch(utils.reject("Couldn't create a view for model id '" + String(model.id) + "'", true));
         });
         return model.state_change;
     };
 
     WidgetManager.prototype.get_msg_cell = function (msg_id) {
         var cell = null;
         // First, check to see if the msg was triggered by cell execution.
         if (this.notebook) {
             cell = this.notebook.get_msg_cell(msg_id);
         }
         if (cell !== null) {
             return cell;
         }
         // Second, check to see if a get_cell callback was defined
         // for the message.  get_cell callbacks are registered for
         // widget messages, so this block is actually checking to see if the
         // message was triggered by a widget.
         var kernel = this.comm_manager.kernel;
         if (kernel) {
             var callbacks = kernel.get_callbacks_for_msg(msg_id);
             if (callbacks && callbacks.iopub &&
                 callbacks.iopub.get_cell !== undefined) {
                 return callbacks.iopub.get_cell();
             }
         }
         
         // Not triggered by a cell or widget (no get_cell callback 
         // exists).
         return null;
     };
 
     WidgetManager.prototype.callbacks = function (view) {
-        // callback handlers specific a view
+        /**
+         * callback handlers specific a view
+         */
         var callbacks = {};
         if (view && view.options.cell) {
 
             // Try to get output handlers
             var cell = view.options.cell;
             var handle_output = null;
             var handle_clear_output = null;
             if (cell.output_area) {
                 handle_output = $.proxy(cell.output_area.handle_output, cell.output_area);
                 handle_clear_output = $.proxy(cell.output_area.handle_clear_output, cell.output_area);
             }
 
             // Create callback dictionary using what is known
             var that = this;
             callbacks = {
                 iopub : {
                     output : handle_output,
                     clear_output : handle_clear_output,
 
                     // Special function only registered by widget messages.
                     // Allows us to get the cell for a message so we know
                     // where to add widgets if the code requires it.
                     get_cell : function () {
                         return cell;
                     },
                 },
             };
         }
         return callbacks;
     };
 
     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, 
             comm: comm}).catch(utils.reject("Couldn't create a model.", true));
     };
 
     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});
         }
 
         var that = this;
         var model_id = comm.comm_id;
         var model_promise =  utils.load_class(options.model_name, options.model_module, WidgetManager._model_types)
             .then(function(ModelType) {
                 var widget_model = new ModelType(that, model_id, comm);
                 widget_model.once('comm:close', function () {
                     delete that._models[model_id];
                 });
                 return widget_model;
 
             }, function(error) {
                 delete that._models[model_id];
                 var wrapped_error = new utils.WrappedError("Couldn't create model", error);
                 return Promise.reject(wrapped_error);
             });
         this._models[model_id] = model_promise;
         return model_promise;
     };
 
     // Backwards compatibility.
     IPython.WidgetManager = WidgetManager;
 
     return {'WidgetManager': WidgetManager};
 });

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

@@ -1,617 +1,679 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define(["widgets/js/manager",
         "underscore",
         "backbone",
         "jquery",
         "base/js/utils",
         "base/js/namespace",
 ], function(widgetmanager, _, Backbone, $, utils, IPython){
 
     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 = {};
             this.pending_msgs = 0;
             this.msg_buffer = null;
             this.state_lock = null;
             this.id = model_id;
             this.views = {};
 
             if (comm !== undefined) {
                 // Remember comm associated with the model.
                 this.comm = comm;
                 comm.model = this;
 
                 // Hook comm messages up to model.
                 comm.on_close($.proxy(this._handle_comm_closed, this));
                 comm.on_msg($.proxy(this._handle_comm_msg, this));
             }
             return Backbone.Model.apply(this);
         },
 
         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);
                 this.pending_msgs++;
             }
         },
 
         _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);
             delete this.comm.model; // Delete ref so GC will collect widget model.
             delete this.comm;
             delete this.model_id; // Delete id from model so widget manager cleans up.
             for (var id in this.views) {
                 if (this.views.hasOwnProperty(id)) {
                     this.views[id].remove();
                 }
             }
         },
 
         _handle_comm_msg: function (msg) {
-            // Handle incoming comm msg.
+            /**
+             * Handle incoming comm msg.
+             */
             var method = msg.content.data.method;
             var that = this;
             switch (method) {
                 case 'update':
                     this.state_change = this.state_change.then(function() {
                         return that.set_state(msg.content.data.state);
                     }).catch(utils.reject("Couldn't process update msg for model id '" + String(that.id) + "'", true));
                     break;
                 case 'custom':
                     this.trigger('msg:custom', msg.content.data.content);
                     break;
                 case 'display':
                     this.widget_manager.display_view(msg, this);
                     break;
             }
         },
 
         set_state: function (state) {
             var that = this;
             // Handle when a widget is updated via the python side.
             return this._unpack_models(state).then(function(state) {
                 that.state_lock = state;
                 try {
                     WidgetModel.__super__.set.call(that, state);
                 } finally {
                     that.state_lock = null;
                 }
             }).catch(utils.reject("Couldn't set model state", true));
         },
 
         _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
                     // throttled.
                     if (this.msg_buffer !== null &&
                         (this.get('msg_throttle') || 3) === this.pending_msgs) {
                         var data = {method: 'backbone', sync_method: 'update', sync_data: this.msg_buffer};
                         this.comm.send(data, callbacks);
                         this.msg_buffer = null;
                     } else {
                         --this.pending_msgs;
                     }
                 }
             }
         },
 
         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) {
                 callbacks.iopub = {};
             }
 
             var that = this;
             callbacks.iopub.status = function (msg) {
                 that._handle_status(msg, callbacks);
             };
             return callbacks;
         },
 
         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()
             // operation.  Calling set multiple times in a row results in a 
             // loss of diff information.  Here we keep our own running diff.
             this._buffered_state_diff = $.extend(this._buffered_state_diff, this.changedAttributes() || {});
             return return_value;
         },
 
         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);
             };
             if (this.comm === undefined) {
                 error();
                 return false;
             }
 
             // Delete any key value pairs that the back-end already knows about.
             var attrs = (method === 'patch') ? options.attrs : model.toJSON(options);
             if (this.state_lock !== null) {
                 var keys = Object.keys(this.state_lock);
                 for (var i=0; i<keys.length; i++) {
                     var key = keys[i];
                     if (attrs[key] === this.state_lock[key]) {
                         delete attrs[key];
                     }
                 }
             }
 
             // Only sync if there are attributes to send to the back-end.
             attrs = this._pack_models(attrs);
             if (_.size(attrs) > 0) {
 
                 // If this message was sent via backbone itself, it will not
                 // have any callbacks.  It's important that we create callbacks
                 // so we can listen for status messages, etc...
                 var callbacks = options.callbacks || this.callbacks();
 
                 // Check throttle.
                 if (this.pending_msgs >= (this.get('msg_throttle') || 3)) {
                     // The throttle has been exceeded, buffer the current msg so
                     // it can be sent once the kernel has finished processing 
                     // some of the existing messages.
                     
                     // Combine updates if it is a 'patch' sync, otherwise replace updates
                     switch (method) {
                         case 'patch':
                             this.msg_buffer = $.extend(this.msg_buffer || {}, attrs);
                             break;
                         case 'update':
                         case 'create':
                             this.msg_buffer = attrs;
                             break;
                         default:
                             error();
                             return false;
                     }
                     this.msg_buffer_callbacks = callbacks;
 
                 } else {
                     // We haven't exceeded the throttle, send the message like 
                     // normal.
                     var data = {method: 'backbone', sync_data: attrs};
                     this.comm.send(data, callbacks);
                     this.pending_msgs++;
                 }
             }
             // Since the comm is a one-way communication, assume the message 
             // arrived.  Don't call success since we don't have a model back from the server
             // this means we miss out on the 'sync' event.
             this._buffered_state_diff = {};
         },
 
         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) {
                 return "IPY_MODEL_" + value.id;
 
             } else if ($.isArray(value)) {
                 packed = [];
                 _.each(value, function(sub_value, key) {
                     packed.push(that._pack_models(sub_value));
                 });
                 return packed;
             } else if (value instanceof Date || value instanceof String) {
                 return value;
             } else if (value instanceof Object) {
                 packed = {};
                 _.each(value, function(sub_value, key) {
                     packed[key] = that._pack_models(sub_value);
                 });
                 return packed;
 
             } else {
                 return value;
             }
         },
 
         _unpack_models: function(value) {
-            // Replace model ids with models recursively.
+            /**
+             * Replace model ids with models recursively.
+             */
             var that = this;
             var unpacked;
             if ($.isArray(value)) {
                 unpacked = [];
                 _.each(value, function(sub_value, key) {
                     unpacked.push(that._unpack_models(sub_value));
                 });
                 return Promise.all(unpacked);
             } else if (value instanceof Object) {
                 unpacked = {};
                 _.each(value, function(sub_value, key) {
                     unpacked[key] = that._unpack_models(sub_value);
                 });
                 return utils.resolve_promises_dict(unpacked);
             } else if (typeof value === 'string' && value.slice(0,10) === "IPY_MODEL_") {
                 // get_model returns a promise already
                 return this.widget_manager.get_model(value.slice(10, value.length));
             } else {
                 return Promise.resolve(value);
             }
         },
 
         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);
                 }
             }, this);
 
        },
     });
     widgetmanager.WidgetManager.register_widget_model('WidgetModel', WidgetModel);
 
 
     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();
             this.model.views[this.id] = this;
             this.on('displayed', function() { 
                 this.is_displayed = true; 
             }, this);
         },
 
         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();
             }
         },
 
         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());
         },
 
         touch: function () {
             this.model.save_changes(this.callbacks());
         },
 
         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 {
                 this.on('displayed', callback, context);
             }
         },
     });
 
 
     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);
             this.model.on('change:_css', this.update_css, this);
 
             this.model.on('change:_dom_classes', function(model, new_classes) {
                 var old_classes = model.previous('_dom_classes');
                 this.update_classes(old_classes, new_classes);
             }, this);
 
             this.model.on('change:color', function (model, value) { 
                 this.update_attr('color', value); }, this);
 
             this.model.on('change:background_color', function (model, value) { 
                 this.update_attr('background', value); }, this);
 
             this.model.on('change:width', function (model, value) { 
                 this.update_attr('width', value); }, this);
 
             this.model.on('change:height', function (model, value) { 
                 this.update_attr('height', value); }, this);
 
             this.model.on('change:border_color', function (model, value) { 
                 this.update_attr('border-color', value); }, this);
 
             this.model.on('change:border_width', function (model, value) { 
                 this.update_attr('border-width', value); }, this);
 
             this.model.on('change:border_style', function (model, value) { 
                 this.update_attr('border-style', value); }, this);
 
             this.model.on('change:font_style', function (model, value) { 
                 this.update_attr('font-style', value); }, this);
 
             this.model.on('change:font_weight', function (model, value) { 
                 this.update_attr('font-weight', value); }, this);
 
             this.model.on('change:font_size', function (model, value) { 
                 this.update_attr('font-size', this._default_px(value)); }, this);
 
             this.model.on('change:font_family', function (model, value) { 
                 this.update_attr('font-family', value); }, this);
 
             this.model.on('change:padding', function (model, value) { 
                 this.update_attr('padding', value); }, this);
 
             this.model.on('change:margin', function (model, value) { 
                 this.update_attr('margin', this._default_px(value)); }, this);
 
             this.model.on('change:border_radius', function (model, value) { 
                 this.update_attr('border-radius', this._default_px(value)); }, this);
 
             this.after_displayed(function() {
                 this.update_visible(this.model, this.model.get("visible"));
                 this.update_classes([], this.model.get('_dom_classes'));
                 
                 this.update_attr('color', this.model.get('color'));
                 this.update_attr('background', this.model.get('background_color'));
                 this.update_attr('width', this.model.get('width'));
                 this.update_attr('height', this.model.get('height'));
                 this.update_attr('border-color', this.model.get('border_color'));
                 this.update_attr('border-width', this.model.get('border_width'));
                 this.update_attr('border-style', this.model.get('border_style'));
                 this.update_attr('font-style', this.model.get('font_style'));
                 this.update_attr('font-weight', this.model.get('font_weight'));
                 this.update_attr('font-size', this.model.get('font_size'));
                 this.update_attr('font-family', this.model.get('font_family'));
                 this.update_attr('padding', this.model.get('padding'));
                 this.update_attr('margin', this.model.get('margin'));
                 this.update_attr('border-radius', this.model.get('border_radius'));
 
                 this.update_css(this.model, this.model.get("_css"));
             }, this);
         },
 
         _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';
             }
             return value;
         },
 
         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++) {
                 // Apply the css traits to all elements that match the selector.
                 var selector = css[i][0];
                 var elements = this._get_selector_element(selector);
                 if (elements.length > 0) {
                     var trait_key = css[i][1];
                     var trait_value = css[i][2];
                     elements.css(trait_key ,trait_value);
                 }
             }
         },
 
         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;
             }
             _.difference(old_classes, new_classes).map(function(c) {$el.removeClass(c);})
             _.difference(new_classes, old_classes).map(function(c) {$el.addClass(c);})
         },
 
         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);
             }
             var old_classes = class_map[key] ? class_map[key] : [];
             key = this.model.get(trait_name);
             var new_classes = class_map[key] ? class_map[key] : [];
 
             this.update_classes(old_classes, new_classes, $el || this.$el);
         },
         
         _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;
             } else {
                 elements = this.$el.find(selector).addBack(selector);
             }
             return elements;
         },
     });
 
 
     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);
     };
 
     _.extend(ViewList.prototype, {
         initialize: function(create_view, remove_view, context) {
             this.state_change = Promise.resolve();
             this._handler_context = context || this;
             this._models = [];
             this.views = [];
             this._create_view = create_view;
             this._remove_view = remove_view || function(view) {view.remove();};
         },
 
         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){
                 console.error("Must define a create a remove function");
             }
             var context = context || this._handler_context;
             var added_views = [];
             var that = this;
             this.state_change = this.state_change.then(function() {
                 var i;
                  // first, skip past the beginning of the lists if they are identical
                 for (i = 0; i < new_models.length; i++) {
                     if (i >= that._models.length || new_models[i] !== that._models[i]) {
                         break;
                     }
                 }
                 var first_removed = i;
                 // Remove the non-matching items from the old list.
                 for (var j = first_removed; j < that._models.length; j++) {
                     remove.call(context, that.views[j]);
                 }
 
                 // Add the rest of the new list items.
                 for (; i < new_models.length; i++) {
                     added_views.push(create.call(context, new_models[i]));
                 }
                 // make a copy of the input array
                 that._models = new_models.slice();
                 return Promise.all(added_views).then(function(added) {
                     Array.prototype.splice.apply(that.views, [first_removed, that.views.length].concat(added));
                     return that.views;
                 });
             });
             return this.state_change;
         },
 
         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++) {
                     that._remove_view.call(that._handler_context, that.views[i]);
                 }
                 that._models = [];
                 that.views = [];
             });
             return this.state_change;
         },
     });
 
     var widget = {
         'WidgetModel': WidgetModel,
         'WidgetView': WidgetView,
         'DOMWidgetView': DOMWidgetView,
         'ViewList': ViewList,
     };
 
     // For backwards compatability.
     $.extend(IPython, widget);
 
     return widget;
 });

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

@@ -1,141 +1,155 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     "widgets/js/widget",
     "jquery",
     "bootstrap",
 ], function(widget, $){
 
     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 />')
                 .addClass('widget-label')
                 .appendTo(this.$el)
                 .hide();
             this.$checkbox = $('<input />')
                 .attr('type', 'checkbox')
                 .appendTo(this.$el)
                 .click($.proxy(this.handle_click, this));
 
             this.update(); // Set defaults.
         },
 
         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) {
                 var disabled = this.model.get('disabled');
                 this.$checkbox.prop('disabled', disabled);
 
                 var description = this.model.get('description');
                 if (description.trim().length === 0) {
                     this.$label.hide();
                 } else {
                     this.$label.text(description);
                     MathJax.Hub.Queue(["Typeset",MathJax.Hub,this.$label.get(0)]);
                     this.$label.show();
                 }
             }
             return CheckboxView.__super__.update.apply(this);
         },
         
     });
 
 
     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')
                 .attr('type', 'button')
                 .on('click', function (e) {
                     e.preventDefault();
                     that.handle_click();
                 }));
             this.$el.attr("data-toggle", "tooltip");
             this.model.on('change:button_style', function(model, value) {
                 this.update_button_style();
             }, this);
             this.update_button_style('');
 
             this.update(); // Set defaults.
         },
 
         update_button_style: function(previous_trait_value) {
             var class_map = {
                 primary: ['btn-primary'],
                 success: ['btn-success'],
                 info: ['btn-info'],
                 warning: ['btn-warning'],
                 danger: ['btn-danger']
             };
             this.update_mapped_classes(class_map, 'button_style', previous_trait_value);
         },
         
         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 {
                 this.$el.removeClass('active');
             }
 
             if (options === undefined || options.updated_view != this) {
 
                 var disabled = this.model.get('disabled');
                 this.$el.prop('disabled', disabled);
 
                 var description = this.model.get('description');
                 this.$el.attr("title", this.model.get("tooltip"));
                 if (description.trim().length === 0) {
                     this.$el.html("&nbsp;"); // Preserve button height
                 } else {
                     this.$el.text(description);
                 }
             }
             return ToggleButtonView.__super__.update.apply(this);
         },
         
         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();
         },
     });
 
     return {
         'CheckboxView': CheckboxView,
         'ToggleButtonView': ToggleButtonView,
     };
 });

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

@@ -1,344 +1,370 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     "widgets/js/widget",
     "jqueryui",
     "base/js/utils",
     "bootstrap",
 ], function(widget, $, utils){
 
     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) {
                 this.children_views.update(value);
             }, this);
             this.listenTo(this.model, 'change:overflow_x', function(model, value) {
                 this.update_overflow_x();
             }, this);
             this.listenTo(this.model, 'change:overflow_y', function(model, value) {
                 this.update_overflow_y();
             }, this);
             this.listenTo(this.model, 'change:box_style', function(model, value) {
                 this.update_box_style();
             }, this);
         },
 
         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'));
             this.update_overflow_x();
             this.update_overflow_y();
             this.update_box_style('');
         },
 
         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'));
         },
 
         update_box_style: function(previous_trait_value) {
             var class_map = {
                 success: ['alert', 'alert-success'],
                 info: ['alert', 'alert-info'],
                 warning: ['alert', 'alert-warning'],
                 danger: ['alert', 'alert-danger']
             };
             this.update_mapped_classes(class_map, 'box_style', previous_trait_value, this.$box);
         },
         
         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);
             return this.create_child_view(model).then(function(view) {
                 dummy.replaceWith(view.el);
 
                 // Trigger the displayed event of the child view.
                 that.after_displayed(function() {
                     view.trigger('displayed');
                 });
                 return view;
             }).catch(utils.reject("Couldn't add child view to box", true));
         },
         
         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();
         },
     });
 
 
     var FlexBoxView = BoxView.extend({
         render: function(){
             FlexBoxView.__super__.render.apply(this);
             this.listenTo(this.model, 'change:orientation', this.update_orientation, this);
             this.listenTo(this.model, 'change:flex', this._flex_changed, this);
             this.listenTo(this.model, 'change:pack', this._pack_changed, this);
             this.listenTo(this.model, 'change:align', this._align_changed, this);
             this._flex_changed();
             this._pack_changed();
             this._align_changed();
             this.update_orientation();
         },
 
         update_orientation: function(){
             var orientation = this.model.get("orientation");
             if (orientation == "vertical") {
                 this.$box.removeClass("hbox").addClass("vbox");
             } else {
                 this.$box.removeClass("vbox").addClass("hbox");
             }
         },
 
         _flex_changed: function(){
             if (this.model.previous('flex')) {
                 this.$box.removeClass('box-flex' + this.model.previous('flex'));
             }
             this.$box.addClass('box-flex' + this.model.get('flex'));
         },
 
         _pack_changed: function(){
             if (this.model.previous('pack')) {
                 this.$box.removeClass(this.model.previous('pack'));
             }
             this.$box.addClass(this.model.get('pack'));
         },
 
         _align_changed: function(){
             if (this.model.previous('align')) {
                 this.$box.removeClass('align-' + this.model.previous('align'));
             }
             this.$box.addClass('align-' + this.model.get('align'));
         },
     });
 
     var PopupView = BoxView.extend({
 
         render: function(){
-            // Called when view is rendered.
+            /**
+             * Called when view is rendered.
+             */
             var that = this;
             
             this.$el.on("remove", function(){
                     that.$backdrop.remove();
                 });
             this.$backdrop = $('<div />')
                 .appendTo($('#notebook-container'))
                 .addClass('modal-dialog')
                 .css('position', 'absolute')
                 .css('left', '0px')
                 .css('top', '0px');
             this.$window = $('<div />')
                 .appendTo(this.$backdrop)
                 .addClass('modal-content widget-modal')
                 .mousedown(function(){
                     that.bring_to_front();
                 });
 
             // Set the elements array since the this.$window element is not child
             // of this.$el and the parent widget manager or other widgets may
             // need to know about all of the top-level widgets.  The IPython
             // widget manager uses this to register the elements with the
             // keyboard manager.
             this.additional_elements = [this.$window];
 
             this.$title_bar = $('<div />')
                 .addClass('popover-title')
                 .appendTo(this.$window)
                 .mousedown(function(){
                     that.bring_to_front();
                 });
             this.$close = $('<button />')
                 .addClass('close fa fa-remove')
                 .css('margin-left', '5px')
                 .appendTo(this.$title_bar)
                 .click(function(){
                     that.hide();
                     event.stopPropagation();
                 });
             this.$minimize = $('<button />')
                 .addClass('close fa fa-arrow-down')
                 .appendTo(this.$title_bar)
                 .click(function(){
                     that.popped_out = !that.popped_out;
                     if (!that.popped_out) {
                         that.$minimize
                             .removeClass('fa-arrow-down')
                             .addClass('fa-arrow-up');
                             
                         that.$window
                             .draggable('destroy')
                             .resizable('destroy')
                             .removeClass('widget-modal modal-content')
                             .addClass('docked-widget-modal')
                             .detach()
                             .insertBefore(that.$show_button);
                         that.$show_button.hide();
                         that.$close.hide();
                     } else {
                         that.$minimize
                             .addClass('fa-arrow-down')
                             .removeClass('fa-arrow-up');
 
                         that.$window
                             .removeClass('docked-widget-modal')
                             .addClass('widget-modal modal-content')
                             .detach()
                             .appendTo(that.$backdrop)
                             .draggable({handle: '.popover-title', snap: '#notebook, .modal', snapMode: 'both'})
                             .resizable()
                             .children('.ui-resizable-handle').show();
                         that.show();
                         that.$show_button.show();
                         that.$close.show();
                     }
                     event.stopPropagation();
                 });
             this.$title = $('<div />')
                 .addClass('widget-modal-title')
                 .html("&nbsp;")
                 .appendTo(this.$title_bar);     
             this.$box = $('<div />')
                 .addClass('modal-body')
                 .addClass('widget-modal-body')
                 .addClass('widget-box')
                 .addClass('vbox')
                 .appendTo(this.$window);
             
             this.$show_button = $('<button />')
                 .html("&nbsp;")
                 .addClass('btn btn-info widget-modal-show')
                 .appendTo(this.$el)
                 .click(function(){
                     that.show();
                 });
             
             this.$window.draggable({handle: '.popover-title', snap: '#notebook, .modal', snapMode: 'both'});
             this.$window.resizable();
             this.$window.on('resize', function(){
                 that.$box.outerHeight(that.$window.innerHeight() - that.$title_bar.outerHeight());
             });
 
             this._shown_once = false;
             this.popped_out = true;
 
             this.children_views.update(this.model.get('children'))
         },
         
         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) {
                 this.$window.css("positon", "absolute");
                 this.$window.css("top", "0px");
                 this.$window.css("left", Math.max(0, (($('body').outerWidth() - this.$window.outerWidth()) / 2) + 
                     $(window).scrollLeft()) + "px");
                 this.bring_to_front();
             }
         },
         
         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){
                 var zindex = parseInt($(el).css('z-index'));
                 if (!isNaN(zindex)) {
                     max_zindex = Math.max(max_zindex, zindex);
                 }
             });
             
             // Start z-index of widget modals at 2000
             max_zindex = Math.max(max_zindex, 2000);
             
             $widget_modals.each(function (index, el){
                 $el = $(el);
                 if (max_zindex == parseInt($el.css('z-index'))) {
                     $el.css('z-index', max_zindex - 1);
                 }
             });
             this.$window.css('z-index', max_zindex);
         },
         
         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
             } else {
                 this.$title.text(description);
                 MathJax.Hub.Queue(["Typeset",MathJax.Hub,this.$title.get(0)]);
             }
             
             var button_text = this.model.get('button_text');
             if (button_text.trim().length === 0) {
                 this.$show_button.html("&nbsp;"); // Preserve button height
             } else {
                 this.$show_button.text(button_text);
             }
             
             if (!this._shown_once) {
                 this._shown_once = true;
                 this.show();
             }
             
             return PopupView.__super__.update.apply(this);
         },
         
         _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;
                 } else {
                     return this.$window.find(selector.substring(6));
                 }
             } else {
                 return PopupView.__super__._get_selector_element.apply(this, [selector]);
             }
         },
     });
 
     return {
         'BoxView': BoxView,
         'PopupView': PopupView,
         'FlexBoxView': FlexBoxView,
     };
 });

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

@@ -1,71 +1,77 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     "widgets/js/widget",
     "jquery",
     "bootstrap",
 ], function(widget, $){
 
     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");
             this.model.on('change:button_style', function(model, value) {
                 this.update_button_style();
             }, this);
             this.update_button_style('');
 
             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 description = this.model.get('description');
             this.$el.attr("title", this.model.get("tooltip"));
             if (description.length === 0) {
                 this.$el.html("&nbsp;"); // Preserve button height
             } else {
                 this.$el.text(description);
             }
             
             if (this.model.get('disabled')) {
                 this.$el.attr('disabled','disabled');
             } else {
                 this.$el.removeAttr('disabled');
             }
 
             return ButtonView.__super__.update.apply(this);
         },
 
         update_button_style: function(previous_trait_value) {
             var class_map = {
                 primary: ['btn-primary'],
                 success: ['btn-success'],
                 info: ['btn-info'],
                 warning: ['btn-warning'],
                 danger: ['btn-danger']
             };
             this.update_mapped_classes(class_map, 'button_style', previous_trait_value);
         },
 
         events: {
             // Dictionary of events and their handlers.
             'click': '_handle_click',
         },
         
         _handle_click: function(){
-            // Handles when the button is clicked.
+            /**
+             * Handles when the button is clicked.
+             */
             this.send({event: 'click'});
         },
     });
 
     return {
         'ButtonView': ButtonView,
     };
 });

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

@@ -1,32 +1,34 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     "widgets/js/widget",
     "widgets/js/widget_int",
 ], function(widget, int_widgets){
     var IntSliderView = int_widgets.IntSliderView;
     var IntTextView = int_widgets.IntTextView;
 
     var FloatSliderView = IntSliderView.extend({
         _parse_value: parseFloat,
 
         // matches: whitespace?, float, whitespace?, [-:], whitespace?, float
         _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;
         },
     });
 
     var FloatTextView = IntTextView.extend({
         _parse_value: parseFloat
     });
 
     return {
         'FloatSliderView': FloatSliderView,
         'FloatTextView': FloatTextView,
     };
 });

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

@@ -1,44 +1,48 b''
 // Copyright (c) IPython Development Team.
 // Distributed under the terms of the Modified BSD License.
 
 define([
     "widgets/js/widget",
     "jquery",
 ], function(widget, $){
     
     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);
             
             var width = this.model.get('width');
             if (width !== undefined && width.length > 0) {
                 this.$el.attr('width', width);
             } else {
                 this.$el.removeAttr('width');
             }
             
             var height = this.model.get('height');
             if (height !== undefined && height.length > 0) {
                 this.$el.attr('height', height);
             } else {
                 this.$el.removeAttr('height');
             }
             return ImageView.__super__.update.apply(this);
         },
     });
 
     return {
         'ImageView': ImageView,
     };
 });