diff --git a/IPython/html/static/notebook/js/notebook.js b/IPython/html/static/notebook/js/notebook.js index 19556f240..940a3f31f 100644 --- a/IPython/html/static/notebook/js/notebook.js +++ b/IPython/html/static/notebook/js/notebook.js @@ -1,6 +1,9 @@ // Copyright (c) IPython Development Team. // Distributed under the terms of the Modified BSD License. +/** + * @module notebook + */ define([ 'base/js/namespace', 'jquery', @@ -44,25 +47,22 @@ define([ ) { "use strict"; + /** + * Contains and manages cells. + * + * @class Notebook + * @param {string} selector + * @param {object} options - Dictionary of keyword arguments. + * @param {jQuery} options.events - selector of Events + * @param {KeyboardManager} options.keyboard_manager + * @param {Contents} options.contents + * @param {SaveWidget} options.save_widget + * @param {object} options.config + * @param {string} options.base_url + * @param {string} options.notebook_path + * @param {string} options.notebook_name + */ 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 - */ this.config = utils.mergeopt(Notebook, options.config); this.base_url = options.base_url; this.notebook_path = options.notebook_path; @@ -177,11 +177,8 @@ define([ } }; - /** * Create an HTML and CSS representation of the notebook. - * - * @method create_elements */ Notebook.prototype.create_elements = function () { var that = this; @@ -202,8 +199,6 @@ define([ /** * Bind JavaScript events: key presses and custom IPython events. - * - * @method bind_events */ Notebook.prototype.bind_events = function () { var that = this; @@ -320,10 +315,10 @@ define([ }; }; + /** + * Trigger a warning dialog about missing functionality from newer minor versions + */ Notebook.prototype.warn_nbformat_minor = function (event) { - /** - * 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; @@ -342,12 +337,10 @@ define([ } } }); - } + }; /** * Set the dirty flag, and trigger the set_dirty.Notebook event - * - * @method set_dirty */ Notebook.prototype.set_dirty = function (value) { if (value === undefined) { @@ -362,25 +355,22 @@ define([ /** * 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 + * @param {integer} index - An index of the cell to view + * @param {integer} time - Animation time in milliseconds + * @return {integer} Pixel offset from the top of the container */ - Notebook.prototype.scroll_to_cell = function (cell_number, time) { + Notebook.prototype.scroll_to_cell = function (index, 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 ; + index = Math.min(cells.length-1,index); + index = Math.max(0 ,index); + var scroll_value = cells[index].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); @@ -388,8 +378,6 @@ define([ /** * Scroll to the top of the page. - * - * @method scroll_to_top */ Notebook.prototype.scroll_to_top = function () { this.element.animate({scrollTop:0}, 0); @@ -397,6 +385,9 @@ define([ // Edit Notebook metadata + /** + * Display a dialog that allows the user to edit the Notebook's metadata. + */ Notebook.prototype.edit_metadata = function () { var that = this; dialog.edit_metadata({ @@ -414,7 +405,6 @@ define([ /** * 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 () { @@ -424,8 +414,7 @@ define([ /** * Get a particular cell element. * - * @method get_cell_element - * @param {Number} index An index of a cell to select + * @param {integer} index An index of a cell to select * @return {jQuery} A selector of the given cell. */ Notebook.prototype.get_cell_element = function (index) { @@ -440,8 +429,7 @@ define([ /** * Try to get a particular cell by msg_id. * - * @method get_msg_cell - * @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) { @@ -451,8 +439,7 @@ define([ /** * Count the cells in this notebook. * - * @method ncells - * @return {Number} The number of cells in this notebook + * @return {integer} The number of cells in this notebook */ Notebook.prototype.ncells = function () { return this.get_cell_elements().length; @@ -461,22 +448,20 @@ define([ /** * 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 () { + // TODO: we are often calling cells as cells()[i], which we should optimize + // to cells(i) or a new method. return this.get_cell_elements().toArray().map(function (e) { return $(e).data("cell"); }); }; /** - * Get a Cell object from this notebook. + * Get a Cell objects from this notebook. * - * @method get_cell - * @param {Number} index An index of a cell to retrieve + * @param {integer} index - An index of a cell to retrieve * @return {Cell} Cell or null if no cell was found. */ Notebook.prototype.get_cell = function (index) { @@ -491,8 +476,7 @@ define([ /** * Get the cell below a given cell. * - * @method get_next_cell - * @param {Cell} cell The provided cell + * @param {Cell} cell * @return {Cell} the next cell or null if no cell was found. */ Notebook.prototype.get_next_cell = function (cell) { @@ -507,8 +491,7 @@ define([ /** * Get the cell above a given cell. * - * @method get_prev_cell - * @param {Cell} cell The provided cell + * @param {Cell} cell * @return {Cell} The previous cell or null if no cell was found. */ Notebook.prototype.get_prev_cell = function (cell) { @@ -523,9 +506,8 @@ define([ /** * 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. + * @param {Cell} cell + * @return {integer} The cell's numeric index or null if no cell was found. */ Notebook.prototype.find_cell_index = function (cell) { var result = null; @@ -538,11 +520,10 @@ define([ }; /** - * Get a given index , or the selected index if none is provided. + * Return given index if defined, or the selected index if not. * - * @method index_or_selected - * @param {Number} index A cell's index - * @return {Number} The given index, or selected index if none is provided. + * @param {integer} [index] - A cell's index + * @return {integer} cell index */ Notebook.prototype.index_or_selected = function (index) { var i; @@ -559,7 +540,7 @@ define([ /** * Get the currently selected cell. - * @method get_selected_cell + * * @return {Cell} The selected cell */ Notebook.prototype.get_selected_cell = function () { @@ -570,8 +551,7 @@ define([ /** * Check whether a cell index is valid. * - * @method is_valid_cell_index - * @param {Number} index A cell index + * @param {integer} index - A cell index * @return True if the index is valid, false otherwise */ Notebook.prototype.is_valid_cell_index = function (index) { @@ -584,9 +564,8 @@ define([ /** * Get the index of the currently selected cell. - - * @method get_selected_index - * @return {Number} The selected cell's numeric index + * + * @return {integer} The selected cell's numeric index */ Notebook.prototype.get_selected_index = function () { var result = null; @@ -604,8 +583,7 @@ define([ /** * Programmatically select a cell. * - * @method select - * @param {Number} index A cell's index + * @param {integer} index - A cell's index * @return {Notebook} This notebook */ Notebook.prototype.select = function (index) { @@ -637,7 +615,6 @@ define([ /** * Programmatically select the next cell. * - * @method select_next * @return {Notebook} This notebook */ Notebook.prototype.select_next = function () { @@ -649,7 +626,6 @@ define([ /** * Programmatically select the previous cell. * - * @method select_prev * @return {Notebook} This notebook */ Notebook.prototype.select_prev = function () { @@ -664,10 +640,8 @@ define([ /** * Gets the index of the cell that is in edit mode. * - * @method get_edit_index - * - * @return index {int} - **/ + * @return {integer} index + */ Notebook.prototype.get_edit_index = function () { var result = null; this.get_cell_elements().filter(function (index) { @@ -681,9 +655,8 @@ define([ /** * 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. - **/ + * @param {Cell} [cell] - Cell to enter command mode on. + */ Notebook.prototype.handle_command_mode = function (cell) { if (this.mode !== 'command') { cell.command_mode(); @@ -695,9 +668,7 @@ define([ /** * 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') { @@ -711,9 +682,8 @@ define([ /** * Handle when a cell fires it's edit_mode event. * - * @method handle_edit_mode - * @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') { cell.edit_mode(); @@ -725,9 +695,7 @@ define([ /** * 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') { @@ -738,9 +706,7 @@ define([ /** * 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 @@ -752,10 +718,9 @@ define([ /** * Move given (or selected) cell up and select it. * - * @method move_cell_up - * @param [index] {integer} cell index + * @param {integer} [index] - 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) { @@ -775,12 +740,11 @@ define([ /** - * Move given (or selected) cell down and select it + * Move given (or selected) cell down and select it. * - * @method move_cell_down - * @param [index] {integer} cell index + * @param {integer} [index] - 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)) { @@ -804,8 +768,7 @@ define([ /** * Delete a cell from the notebook. * - * @method delete_cell - * @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,8 +809,6 @@ define([ /** * Restore the most recently deleted cell. - * - * @method undelete */ Notebook.prototype.undelete_cell = function() { if (this.undelete_backup !== null && this.undelete_index !== null) { @@ -886,16 +847,14 @@ define([ * 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 + * Similar to insert_above, but index parameter is mandatory. * - * Index will be brought back into the accessible range [0,n] + * 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 - **/ + * @param {string} [type] - in ['code','markdown', 'raw'], defaults to 'code' + * @param {integer} [index] - a valid index where to insert cell + * @return {Cell|null} created cell or null + */ Notebook.prototype.insert_cell_at_index = function(type, index){ var ncells = this.ncells(); @@ -961,13 +920,10 @@ define([ /** * 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. - **/ + * @param {HTMLElement} element - a cell element + * @param {integer} [index] - a valid index where to inser cell + * @returns {boolean} success + */ Notebook.prototype._insert_element_at_index = function(element, index){ if (element === undefined){ return false; @@ -999,14 +955,10 @@ define([ * 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 - **/ + * @param {string} [type] - cell type + * @param {integer} [index] - defaults to the currently selected cell + * @return {Cell|null} 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); @@ -1016,15 +968,10 @@ define([ * 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 - * - **/ + * @param {string} [type] - cell type + * @param {integer} [index] - defaults to the currently selected cell + * @return {Cell|null} 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); @@ -1034,11 +981,9 @@ define([ /** * Insert cell at end of notebook * - * @method insert_cell_at_bottom - * @param {String} type cell type - * - * @return the added cell; or null - **/ + * @param {string} type - cell type + * @return {Cell|null} handle to created cell or null + */ Notebook.prototype.insert_cell_at_bottom = function (type){ var len = this.ncells(); return this.insert_cell_below(type,len-1); @@ -1047,8 +992,7 @@ define([ /** * Turn a cell into a code cell. * - * @method to_code - * @param {Number} [index] A cell's index + * @param {integer} [index] - cell index */ Notebook.prototype.to_code = function (index) { var i = this.index_or_selected(index); @@ -1079,8 +1023,7 @@ define([ /** * Turn a cell into a Markdown cell. * - * @method to_markdown - * @param {Number} [index] A cell's index + * @param {integer} [index] - cell index */ Notebook.prototype.to_markdown = function (index) { var i = this.index_or_selected(index); @@ -1117,8 +1060,7 @@ define([ /** * Turn a cell into a raw text cell. * - * @method to_raw - * @param {Number} [index] A cell's index + * @param {integer} [index] - cell index */ Notebook.prototype.to_raw = function (index) { var i = this.index_or_selected(index); @@ -1149,10 +1091,10 @@ define([ } }; + /** + * Warn about heading cell support removal. + */ Notebook.prototype._warn_heading = function () { - /** - * warn about heading cells being removed - */ dialog.modal({ notebook: this, keyboard_manager: this.keyboard_manager, @@ -1170,11 +1112,10 @@ define([ }; /** - * Turn a cell into a markdown cell with a heading. + * Turn a cell into a heading containing markdown cell. * - * @method to_heading - * @param {Number} [index] A cell's index - * @param {Number} [level] A heading level (e.g., 1 for h1) + * @param {integer} [index] - cell index + * @param {integer} [level] - heading level (e.g., 1 for h1) */ Notebook.prototype.to_heading = function (index, level) { this.to_markdown(index); @@ -1191,9 +1132,7 @@ define([ // Cut/Copy/Paste /** - * Enable UI elements for pasting cells. - * - * @method enable_paste + * Enable the UI elements for pasting cells. */ Notebook.prototype.enable_paste = function () { var that = this; @@ -1209,9 +1148,7 @@ define([ }; /** - * Disable UI elements for pasting cells. - * - * @method disable_paste + * Disable the UI elements for pasting cells. */ Notebook.prototype.disable_paste = function () { if (this.paste_enabled) { @@ -1224,8 +1161,6 @@ define([ /** * Cut a cell. - * - * @method cut_cell */ Notebook.prototype.cut_cell = function () { this.copy_cell(); @@ -1234,8 +1169,6 @@ define([ /** * Copy a cell. - * - * @method copy_cell */ Notebook.prototype.copy_cell = function () { var cell = this.get_selected_cell(); @@ -1248,9 +1181,7 @@ define([ }; /** - * Replace the selected cell with a cell in the clipboard. - * - * @method paste_cell_replace + * Replace the selected cell with the cell in the clipboard. */ Notebook.prototype.paste_cell_replace = function () { if (this.clipboard !== null && this.paste_enabled) { @@ -1265,8 +1196,6 @@ define([ /** * 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) { @@ -1279,8 +1208,6 @@ define([ /** * 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) { @@ -1294,9 +1221,7 @@ define([ // Split/merge /** - * Split the selected cell into two, at the cursor. - * - * @method split_cell + * Split the selected cell into two cells. */ Notebook.prototype.split_cell = function () { var cell = this.get_selected_cell(); @@ -1312,9 +1237,7 @@ define([ }; /** - * Combine the selected cell into the cell above it. - * - * @method merge_cell_above + * Merge the selected cell into the cell above it. */ Notebook.prototype.merge_cell_above = function () { var index = this.get_selected_index(); @@ -1347,9 +1270,7 @@ define([ }; /** - * Combine the selected cell into the cell below it. - * - * @method merge_cell_below + * Merge the selected cell into the cell below it. */ Notebook.prototype.merge_cell_below = function () { var index = this.get_selected_index(); @@ -1387,8 +1308,7 @@ define([ /** * Hide a cell's output. * - * @method collapse_output - * @param {Number} index A cell's numeric index + * @param {integer} index - cell index */ Notebook.prototype.collapse_output = function (index) { var i = this.index_or_selected(index); @@ -1401,8 +1321,6 @@ define([ /** * Hide each code cell's output area. - * - * @method collapse_all_output */ Notebook.prototype.collapse_all_output = function () { this.get_cells().map(function (cell, i) { @@ -1417,8 +1335,7 @@ define([ /** * Show a cell's output. * - * @method expand_output - * @param {Number} index A cell's numeric index + * @param {integer} index - cell index */ Notebook.prototype.expand_output = function (index) { var i = this.index_or_selected(index); @@ -1431,8 +1348,6 @@ define([ /** * 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) { @@ -1447,8 +1362,7 @@ define([ /** * Clear the selected CodeCell's output area. * - * @method clear_output - * @param {Number} index A cell's numeric index + * @param {integer} index - cell index */ Notebook.prototype.clear_output = function (index) { var i = this.index_or_selected(index); @@ -1461,8 +1375,6 @@ define([ /** * Clear each code cell's output area. - * - * @method clear_all_output */ Notebook.prototype.clear_all_output = function () { this.get_cells().map(function (cell, i) { @@ -1476,8 +1388,7 @@ define([ /** * Scroll the selected CodeCell's output area. * - * @method scroll_output - * @param {Number} index A cell's numeric index + * @param {integer} index - cell index */ Notebook.prototype.scroll_output = function (index) { var i = this.index_or_selected(index); @@ -1489,9 +1400,7 @@ define([ }; /** - * Expand each code cell's output area, and add a scrollbar for long output. - * - * @method scroll_all_output + * Expand each code cell's output area and add a scrollbar for long output. */ Notebook.prototype.scroll_all_output = function () { this.get_cells().map(function (cell, i) { @@ -1503,10 +1412,10 @@ define([ this.set_dirty(true); }; - /** Toggle whether a cell's output is collapsed or expanded. + /** + * Toggle whether a cell's output is collapsed or expanded. * - * @method toggle_output - * @param {Number} index A cell's numeric index + * @param {integer} index - cell index */ Notebook.prototype.toggle_output = function (index) { var i = this.index_or_selected(index); @@ -1518,9 +1427,7 @@ define([ }; /** - * Hide/show the output of all cells. - * - * @method toggle_all_output + * Toggle the output of all cells. */ Notebook.prototype.toggle_all_output = function () { this.get_cells().map(function (cell, i) { @@ -1535,8 +1442,7 @@ define([ /** * Toggle a scrollbar for long cell outputs. * - * @method toggle_output_scroll - * @param {Number} index A cell's numeric index + * @param {integer} index - cell index */ Notebook.prototype.toggle_output_scroll = function (index) { var i = this.index_or_selected(index); @@ -1549,8 +1455,6 @@ define([ /** * 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) { @@ -1566,8 +1470,6 @@ define([ /** * 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(); @@ -1576,8 +1478,6 @@ define([ /** * 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) { @@ -1604,8 +1504,6 @@ define([ /** * 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) { @@ -1636,8 +1534,7 @@ define([ /** * Once a session is started, link the code cells to the kernel and pass the - * comm manager to the widget manager - * + * comm manager to the widget manager. */ Notebook.prototype._session_started = function (){ this._session_starting = false; @@ -1650,15 +1547,17 @@ define([ } } }; - Notebook.prototype._session_start_failed = function (jqxhr, status, error){ + + /** + * Called when the session fails to start. + */ + 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; @@ -1683,13 +1582,9 @@ define([ /** * 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(); @@ -1699,8 +1594,6 @@ define([ /** * 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(); @@ -1728,8 +1621,6 @@ define([ /** * Execute or render cell outputs and select the next cell. - * - * @method execute_cell_and_select_below */ Notebook.prototype.execute_cell_and_select_below = function () { @@ -1757,8 +1648,6 @@ define([ /** * 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()); @@ -1767,8 +1656,6 @@ define([ /** * 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()); @@ -1776,8 +1663,6 @@ define([ /** * Execute all cells. - * - * @method execute_all_cells */ Notebook.prototype.execute_all_cells = function () { this.execute_cell_range(0, this.ncells()); @@ -1787,9 +1672,8 @@ define([ /** * 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) + * @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(); @@ -1804,8 +1688,7 @@ define([ /** * Getter method for this notebook's name. * - * @method get_notebook_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); @@ -1815,8 +1698,7 @@ define([ /** * Setter method for this notebook's name. * - * @method set_notebook_name - * @param {String} name A new name for this notebook + * @param {string} name */ Notebook.prototype.set_notebook_name = function (name) { var parent = utils.url_path_split(this.notebook_path)[0]; @@ -1827,9 +1709,8 @@ define([ /** * 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 + * @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 || ''; @@ -1843,8 +1724,7 @@ define([ /** * Load a notebook from JSON (.ipynb). * - * @method fromJSON - * @param {Object} data JSON representation of a notebook + * @param {object} data - JSON representation of a notebook */ Notebook.prototype.fromJSON = function (data) { @@ -1896,13 +1776,10 @@ define([ /** * Dump this notebook into a JSON-friendly object. * - * @method toJSON - * @return {Object} A JSON-friendly representation of this notebook. + * @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; @@ -1931,10 +1808,9 @@ define([ }; /** - * Start an autosave timer, for periodically saving the notebook. + * Start an autosave timer which periodically saves the notebook. * - * @method set_autosave_interval - * @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; @@ -1964,8 +1840,6 @@ define([ /** * 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) { @@ -2004,9 +1878,8 @@ define([ /** * 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 + * @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); @@ -2043,10 +1916,9 @@ define([ }; /** - * update the autosave interval based on how long the last save took + * Update the autosave interval based on the duration of the last save. * - * @method _update_autosave_interval - * @param {Integer} timestamp when the save request started + * @param {integer} timestamp - when the save request started */ Notebook.prototype._update_autosave_interval = function (start) { var duration = (new Date().getTime() - start); @@ -2064,8 +1936,6 @@ define([ /** * Explicitly trust the output of this notebook. - * - * @method trust_notebook */ Notebook.prototype.trust_notebook = function () { var body = $("
").append($("

") @@ -2112,6 +1982,9 @@ define([ }); }; + /** + * Make a copy of the current notebook. + */ Notebook.prototype.copy_notebook = function () { var that = this; var base_url = this.base_url; @@ -2130,6 +2003,11 @@ define([ ); }; + /** + * Rename the notebook. + * @param {string} new_name + * @return {Promise} promise that resolves when the notebook is renamed. + */ Notebook.prototype.rename = function (new_name) { if (!new_name.match(/\.ipynb$/)) { new_name = new_name + ".ipynb"; @@ -2148,6 +2026,9 @@ define([ ); }; + /** + * Delete this notebook + */ Notebook.prototype.delete = function () { this.contents.delete(this.notebook_path); }; @@ -2155,8 +2036,7 @@ define([ /** * Request a notebook's data from the server. * - * @method load_notebook - * @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; @@ -2173,8 +2053,7 @@ define([ * * Load notebook data from the JSON response. * - * @method load_notebook_success - * @param {Object} data JSON representation of a notebook + * @param {object} data JSON representation of a notebook */ Notebook.prototype.load_notebook_success = function (data) { var failed, msg; @@ -2311,7 +2190,6 @@ define([ /** * Failure callback for loading a notebook from the server. * - * @method load_notebook_error * @param {Error} error */ Notebook.prototype.load_notebook_error = function (error) { @@ -2336,12 +2214,10 @@ define([ }); }; - /********************* checkpoint-related *********************/ + /********************* checkpoint-related ********************/ /** * Save the notebook then immediately create a checkpoint. - * - * @method save_checkpoint */ Notebook.prototype.save_checkpoint = function () { this._checkpoint_after_save = true; @@ -2350,9 +2226,6 @@ define([ /** * 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; @@ -2372,8 +2245,6 @@ define([ /** * List checkpoints for this notebook. - * - * @method list_checkpoints */ Notebook.prototype.list_checkpoints = function () { var that = this; @@ -2388,8 +2259,7 @@ define([ /** * Success callback for listing checkpoints. * - * @method list_checkpoint_success - * @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; @@ -2403,8 +2273,6 @@ define([ /** * 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; @@ -2419,14 +2287,17 @@ define([ /** * Success callback for creating a checkpoint. * - * @method create_checkpoint_success - * @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 + */ Notebook.prototype.restore_checkpoint_dialog = function (checkpoint) { var that = this; checkpoint = checkpoint || this.last_checkpoint; @@ -2471,8 +2342,7 @@ define([ /** * Restore the notebook to a checkpoint state. * - * @method restore_checkpoint - * @param {String} checkpoint ID + * @param {string} checkpoint ID */ Notebook.prototype.restore_checkpoint = function (checkpoint) { this.events.trigger('notebook_restoring.Notebook', checkpoint); @@ -2487,8 +2357,6 @@ define([ /** * 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'); @@ -2498,8 +2366,7 @@ define([ /** * Delete a notebook checkpoint. * - * @method delete_checkpoint - * @param {String} checkpoint ID + * @param {string} checkpoint ID */ Notebook.prototype.delete_checkpoint = function (checkpoint) { this.events.trigger('notebook_restoring.Notebook', checkpoint); @@ -2513,9 +2380,7 @@ define([ }; /** - * Success callback for deleting a notebook checkpoint - * - * @method delete_checkpoint_success + * Success callback for deleting a notebook checkpoint. */ Notebook.prototype.delete_checkpoint_success = function () { this.events.trigger('checkpoint_deleted.Notebook'); diff --git a/docs/jsdoc_config.json b/docs/jsdoc_config.json new file mode 100644 index 000000000..dd30a1502 --- /dev/null +++ b/docs/jsdoc_config.json @@ -0,0 +1,21 @@ +{ + "markdown": { + "parser": "gfm" + }, + "plugins": [ + "plugins/markdown" , + "jsdoc_plugin.js" + ], + "source": { + "include": [ + "../IPython/html/static/notebook/js/notebook.js" + ] + }, + "tags": { + "allowUnknownTags": true + }, + "templates": { + "cleverLinks": false, + "monospaceLinks": false + } +} diff --git a/docs/jsdoc_plugin.js b/docs/jsdoc_plugin.js new file mode 100644 index 000000000..3fa303502 --- /dev/null +++ b/docs/jsdoc_plugin.js @@ -0,0 +1,12 @@ +exports.handlers = { + newDoclet: function(e) { + // e.doclet will refer to the newly created doclet + // you can read and modify properties of that doclet if you wish + if (typeof e.doclet.name === 'string') { + if (e.doclet.name[0] == '_') { + console.log('Private method "' + e.doclet.longname + '" not documented.'); + e.doclet.memberof = ''; + } + } + } +}; \ No newline at end of file