diff --git a/IPython/html/static/notebook/js/notebook.js b/IPython/html/static/notebook/js/notebook.js index 8319aaf..9f9b118 100644 --- a/IPython/html/static/notebook/js/notebook.js +++ b/IPython/html/static/notebook/js/notebook.js @@ -50,7 +50,7 @@ define([ /** * Contains and manages cells. * @class Notebook - * @param {String} selector + * @param {string} selector * @param {dictionary} options - Dictionary of keyword arguments. * events: $(Events) instance * keyboard_manager: KeyboardManager instance @@ -315,7 +315,7 @@ define([ }; /** - * trigger a warning dialog about missing functionality from newer minor versions + * Trigger a warning dialog about missing functionality from newer minor versions */ Notebook.prototype.warn_nbformat_minor = function (event) { var v = 'v' + this.nbformat + '.'; @@ -354,9 +354,9 @@ define([ /** * Scroll the top of the page to a given 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 + * @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(); @@ -384,6 +384,10 @@ define([ // Edit Notebook metadata + /** + * Display a dialog that allows the user to edit the Notebook's metadata. + * @return {null} + */ Notebook.prototype.edit_metadata = function () { var that = this; dialog.edit_metadata({ @@ -410,7 +414,7 @@ define([ /** * Get a particular cell element. * - * @param {Number} index An index of a cell to select + * @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) { @@ -425,7 +429,7 @@ define([ /** * Try to get a particular cell by msg_id. * - * @param {String} msg_id A message UUID + * @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) { @@ -435,7 +439,7 @@ define([ /** * Count the cells in this notebook. * - * @return {Number} The number of cells in this notebook + * @return {number} The number of cells in this notebook */ Notebook.prototype.ncells = function () { return this.get_cell_elements().length; @@ -457,7 +461,7 @@ define([ /** * Get a Cell object from this notebook. * - * @param {Number} index An index of a cell to retrieve + * @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) { @@ -503,7 +507,7 @@ define([ * Get the numeric index of a given cell. * * @param {Cell} cell The provided cell - * @return {Number} The cell's numeric index or null if no cell was found. + * @return {number} The cell's numeric index or null if no cell was found. */ Notebook.prototype.find_cell_index = function (cell) { var result = null; @@ -518,8 +522,8 @@ define([ /** * Get a given index , or the selected index if none is provided. * - * @param {Number} index A cell's index - * @return {Number} The given index, or selected index if none is provided. + * @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; @@ -546,7 +550,7 @@ define([ /** * Check whether a cell index is valid. * - * @param {Number} index A 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) { @@ -560,7 +564,7 @@ define([ /** * Get the index of the currently selected cell. - * @return {Number} The selected cell's numeric index + * @return {number} The selected cell's numeric index */ Notebook.prototype.get_selected_index = function () { var result = null; @@ -578,7 +582,7 @@ define([ /** * Programmatically select a cell. * - * @param {Number} index A cell's index + * @param {number} index A cell's index * @return {Notebook} This notebook */ Notebook.prototype.select = function (index) { @@ -635,7 +639,7 @@ define([ /** * Gets the index of the cell that is in edit mode. * - * @return index {int} + * @return index {integer} **/ Notebook.prototype.get_edit_index = function () { var result = null; @@ -650,7 +654,7 @@ define([ /** * Handle when a a cell blurs and the notebook should enter command mode. * - * @param [cell] {Cell} Cell to enter command mode on. + * @param {Cell} [cell] Cell to enter command mode on. **/ Notebook.prototype.handle_command_mode = function (cell) { if (this.mode !== 'command') { @@ -677,7 +681,7 @@ define([ /** * Handle when a cell fires it's edit_mode event. * - * @param [cell] {Cell} Cell to enter edit mode on. + * @param {Cell} [cell] Cell to enter edit mode on. **/ Notebook.prototype.handle_edit_mode = function (cell) { if (cell && this.mode !== 'edit') { @@ -713,7 +717,7 @@ define([ /** * Move given (or selected) cell up and select it. * - * @param [index] {integer} cell index + * @param {integer} [index] cell index * @return {Notebook} This notebook **/ Notebook.prototype.move_cell_up = function (index) { @@ -737,7 +741,7 @@ define([ /** * Move given (or selected) cell down and select it * - * @param [index] {integer} cell index + * @param {integer} [index] cell index * @return {Notebook} This notebook **/ Notebook.prototype.move_cell_down = function (index) { @@ -763,7 +767,7 @@ define([ /** * Delete a cell from the notebook. * - * @param [index] A cell's numeric index + * @param {integer} [index] cell's numeric index * @return {Notebook} This notebook */ Notebook.prototype.delete_cell = function (index) { @@ -846,10 +850,10 @@ define([ * * Index will be brought back into the accessible range [0,n] * - * @param [type] {string} in ['code','markdown', 'raw'], defaults to 'code' - * @param [index] {int} a valid index where to insert cell + * @param {string} [type] in ['code','markdown', 'raw'], defaults to 'code' + * @param {integer} [index] a valid index where to insert cell * - * @return cell {cell|null} created cell or null + * @return {Cell|null} created cell or null **/ Notebook.prototype.insert_cell_at_index = function(type, index){ @@ -917,9 +921,9 @@ define([ * Insert an element at given cell index. * return true if everything whent fine. * - * @param element {dom_element} a cell element - * @param [index] {int} a valid index where to inser cell * @private + * @param {HTMLElement} element - a cell element + * @param {integer} [index] a valid index where to inser cell **/ Notebook.prototype._insert_element_at_index = function(element, index){ if (element === undefined){ @@ -954,10 +958,10 @@ define([ * * default index value is the one of currently selected cell * - * @param [type] {string} cell type - * @param [index] {integer} + * @param {string} [type] cell type + * @param {integer} [index] * - * @return handle to created cell or null + * @return {Cell|null} handle to created cell or null **/ Notebook.prototype.insert_cell_above = function (type, index) { index = this.index_or_selected(index); @@ -970,10 +974,10 @@ define([ * * default index value is the one of currently selected cell * - * @param [type] {string} cell type - * @param [index] {integer} + * @param {string} [type] cell type + * @param {integer} [index] * - * @return handle to created cell or null + * @return {Cell|null} handle to created cell or null **/ Notebook.prototype.insert_cell_below = function (type, index) { index = this.index_or_selected(index); @@ -984,9 +988,9 @@ define([ /** * Insert cell at end of notebook * - * @param {String} type cell type + * @param {string} type cell type * - * @return the added cell; or null + * @return {Cell|null} the added cell; or null **/ Notebook.prototype.insert_cell_at_bottom = function (type){ var len = this.ncells(); @@ -996,7 +1000,7 @@ define([ /** * Turn a cell into a code cell. * - * @param {Number} [index] A cell's index + * @param {number} [index] A cell's index */ Notebook.prototype.to_code = function (index) { var i = this.index_or_selected(index); @@ -1027,7 +1031,7 @@ define([ /** * Turn a cell into a Markdown cell. * - * @param {Number} [index] A cell's index + * @param {number} [index] A cell's index */ Notebook.prototype.to_markdown = function (index) { var i = this.index_or_selected(index); @@ -1064,7 +1068,7 @@ define([ /** * Turn a cell into a raw text cell. * - * @param {Number} [index] A cell's index + * @param {number} [index] A cell's index */ Notebook.prototype.to_raw = function (index) { var i = this.index_or_selected(index); @@ -1095,11 +1099,11 @@ define([ } }; + /** + * warn about heading cells being removed + * @private + */ Notebook.prototype._warn_heading = function () { - /** - * warn about heading cells being removed - * @private - */ dialog.modal({ notebook: this, keyboard_manager: this.keyboard_manager, @@ -1116,13 +1120,13 @@ define([ }); }; - Notebook.prototype.to_heading = function (index, level) { /** * Turn a cell into a markdown cell with a heading. * - * @param {Number} [index] A cell's index - * @param {Number} [level] A heading level (e.g., 1 for h1) + * @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); @@ -1313,7 +1317,7 @@ define([ /** * Hide a cell's output. * - * @param {Number} index A cell's numeric index + * @param {integer} index - A cell's numeric index */ Notebook.prototype.collapse_output = function (index) { var i = this.index_or_selected(index); @@ -1340,7 +1344,7 @@ define([ /** * Show a cell's output. * - * @param {Number} index A cell's numeric index + * @param {integer} index - A cell's numeric index */ Notebook.prototype.expand_output = function (index) { var i = this.index_or_selected(index); @@ -1367,7 +1371,7 @@ define([ /** * Clear the selected CodeCell's output area. * - * @param {Number} index A cell's numeric index + * @param {integer} index - A cell's numeric index */ Notebook.prototype.clear_output = function (index) { var i = this.index_or_selected(index); @@ -1393,7 +1397,7 @@ define([ /** * Scroll the selected CodeCell's output area. * - * @param {Number} index A cell's numeric index + * @param {integer} index - A cell's numeric index */ Notebook.prototype.scroll_output = function (index) { var i = this.index_or_selected(index); @@ -1419,7 +1423,7 @@ define([ /** Toggle whether a cell's output is collapsed or expanded. * - * @param {Number} index A cell's numeric index + * @param {integer} index - A cell's numeric index */ Notebook.prototype.toggle_output = function (index) { var i = this.index_or_selected(index); @@ -1446,7 +1450,7 @@ define([ /** * Toggle a scrollbar for long cell outputs. * - * @param {Number} index A cell's numeric index + * @param {integer} index - A cell's numeric index */ Notebook.prototype.toggle_output_scroll = function (index) { var i = this.index_or_selected(index); @@ -1676,8 +1680,8 @@ define([ /** * Execute a contiguous range of cells. * - * @param {Number} start Index of the first cell to execute (inclusive) - * @param {Number} end Index of the last cell to execute (exclusive) + * @param {integer} start - Index of the first cell to execute (inclusive) + * @param {integer} end - Index of the last cell to execute (exclusive) */ Notebook.prototype.execute_cell_range = function (start, end) { this.command_mode(); @@ -1692,7 +1696,7 @@ define([ /** * Getter method for this notebook's name. * - * @return {String} This notebook's name (excluding file extension) + * @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); @@ -1702,7 +1706,7 @@ define([ /** * Setter method for this notebook's name. * - * @param {String} name A new name for this notebook + * @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]; @@ -1713,8 +1717,8 @@ define([ /** * Check that a notebook's name is valid. * - * @param {String} nbname A name for this notebook - * @return {Boolean} True if the name is valid, false if invalid + * @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 || ''; @@ -1728,7 +1732,7 @@ define([ /** * Load a notebook from JSON (.ipynb). * - * @param {Object} data JSON representation of a notebook + * @param {Object} data - JSON representation of a notebook */ Notebook.prototype.fromJSON = function (data) { @@ -1814,7 +1818,7 @@ define([ /** * Start an autosave timer, for periodically saving the notebook. * - * @param {Integer} interval the autosave interval in milliseconds + * @param {integer} interval - the autosave interval in milliseconds */ Notebook.prototype.set_autosave_interval = function (interval) { var that = this; @@ -1882,8 +1886,8 @@ define([ /** * Success callback for saving a notebook. * - * @param {Integer} start Time when the save request start - * @param {Object} data JSON representation of a notebook + * @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); @@ -1922,7 +1926,7 @@ define([ /** * update the autosave interval based on how long the last save took * - * @param {Integer} timestamp when the save request started + * @param {integer} timestamp - when the save request started * @private */ Notebook.prototype._update_autosave_interval = function (start) { @@ -1941,7 +1945,6 @@ define([ /** * Explicitly trust the output of this notebook. - * */ Notebook.prototype.trust_notebook = function () { var body = $("
").append($("

") @@ -2044,7 +2047,7 @@ define([ /** * Request a notebook's data from the server. * - * @param {String} notebook_path A notebook to load + * @param {string} notebook_path - A notebook to load */ Notebook.prototype.load_notebook = function (notebook_path) { this.notebook_path = notebook_path; @@ -2268,7 +2271,7 @@ define([ /** * Success callback for listing checkpoints. * - * @param {Object} data JSON representation of a checkpoint + * @param {Object} data - JSON representation of a checkpoint */ Notebook.prototype.list_checkpoints_success = function (data) { this.checkpoints = data; @@ -2296,13 +2299,18 @@ define([ /** * Success callback for creating a checkpoint. * - * @param {Object} data JSON representation of a checkpoint + * @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); }; + /** + * Display the restore checkpoint dialog + * @param {string} checkpoint ID + * @return {null} + */ Notebook.prototype.restore_checkpoint_dialog = function (checkpoint) { var that = this; checkpoint = checkpoint || this.last_checkpoint; @@ -2347,7 +2355,7 @@ define([ /** * Restore the notebook to a checkpoint state. * - * @param {String} checkpoint ID + * @param {string} checkpoint ID */ Notebook.prototype.restore_checkpoint = function (checkpoint) { this.events.trigger('notebook_restoring.Notebook', checkpoint); @@ -2371,7 +2379,7 @@ define([ /** * Delete a notebook checkpoint. * - * @param {String} checkpoint ID + * @param {string} checkpoint ID */ Notebook.prototype.delete_checkpoint = function (checkpoint) { this.events.trigger('notebook_restoring.Notebook', checkpoint);