From 1aa280d9c94ac5c6e82b78d51304482bca57e324 Mon Sep 17 00:00:00 2001 From: Jonathan Frederic Date: Fri, 5 Dec 2014 11:00:43 -0800 Subject: [PATCH 1/9] Start JSDoc integration --- IPython/html/static/notebook/js/notebook.js | 191 +++----------------- docs/conf.json | 16 ++ 2 files changed, 37 insertions(+), 170 deletions(-) create mode 100644 docs/conf.json diff --git a/IPython/html/static/notebook/js/notebook.js b/IPython/html/static/notebook/js/notebook.js index 19556f240..6c72cc48c 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,14 @@ define([ ) { "use strict"; + /** + * + * @exports Notebook + * @class + * @param {String} selector + * @param {dictionary} options + */ 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; @@ -180,8 +172,6 @@ define([ /** * Create an HTML and CSS representation of the notebook. - * - * @method create_elements */ Notebook.prototype.create_elements = function () { var that = this; @@ -202,8 +192,6 @@ define([ /** * Bind JavaScript events: key presses and custom IPython events. - * - * @method bind_events */ Notebook.prototype.bind_events = function () { var that = this; @@ -346,8 +334,6 @@ 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,7 +348,6 @@ 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 @@ -379,8 +364,6 @@ define([ /** * 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 +371,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); @@ -414,7 +395,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,7 +404,6 @@ define([ /** * 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. */ @@ -440,7 +419,6 @@ define([ /** * 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. */ @@ -451,7 +429,6 @@ define([ /** * Count the cells in this notebook. * - * @method ncells * @return {Number} The number of cells in this notebook */ Notebook.prototype.ncells = function () { @@ -461,7 +438,6 @@ 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 @@ -475,7 +451,6 @@ define([ /** * 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. */ @@ -491,7 +466,6 @@ define([ /** * 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. */ @@ -507,7 +481,6 @@ define([ /** * 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. */ @@ -523,7 +496,6 @@ 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. */ @@ -540,7 +512,6 @@ define([ /** * 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. */ @@ -559,7 +530,6 @@ define([ /** * Get the currently selected cell. - * @method get_selected_cell * @return {Cell} The selected cell */ Notebook.prototype.get_selected_cell = function () { @@ -570,7 +540,6 @@ define([ /** * 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 */ @@ -585,7 +554,6 @@ define([ /** * 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 () { @@ -604,7 +572,6 @@ define([ /** * Programmatically select a cell. * - * @method select * @param {Number} index A cell's index * @return {Notebook} This notebook */ @@ -637,7 +604,6 @@ define([ /** * Programmatically select the next cell. * - * @method select_next * @return {Notebook} This notebook */ Notebook.prototype.select_next = function () { @@ -649,7 +615,6 @@ define([ /** * Programmatically select the previous cell. * - * @method select_prev * @return {Notebook} This notebook */ Notebook.prototype.select_prev = function () { @@ -664,8 +629,6 @@ define([ /** * Gets the index of the cell that is in edit mode. * - * @method get_edit_index - * * @return index {int} **/ Notebook.prototype.get_edit_index = function () { @@ -681,7 +644,6 @@ 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. **/ Notebook.prototype.handle_command_mode = function (cell) { @@ -695,8 +657,6 @@ define([ /** * Make the notebook enter command mode. - * - * @method command_mode **/ Notebook.prototype.command_mode = function () { var cell = this.get_cell(this.get_edit_index()); @@ -711,7 +671,6 @@ define([ /** * 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) { @@ -725,8 +684,6 @@ define([ /** * Make a cell enter edit mode. - * - * @method edit_mode **/ Notebook.prototype.edit_mode = function () { var cell = this.get_selected_cell(); @@ -738,8 +695,6 @@ define([ /** * Focus the currently selected cell. - * - * @method focus_cell **/ Notebook.prototype.focus_cell = function () { var cell = this.get_selected_cell(); @@ -752,7 +707,6 @@ define([ /** * Move given (or selected) cell up and select it. * - * @method move_cell_up * @param [index] {integer} cell index * @return {Notebook} This notebook **/ @@ -777,7 +731,6 @@ define([ /** * Move given (or selected) cell down and select it * - * @method move_cell_down * @param [index] {integer} cell index * @return {Notebook} This notebook **/ @@ -804,7 +757,6 @@ define([ /** * Delete a cell from the notebook. * - * @method delete_cell * @param [index] A cell's numeric index * @return {Notebook} This notebook */ @@ -846,8 +798,6 @@ define([ /** * Restore the most recently deleted cell. - * - * @method undelete */ Notebook.prototype.undelete_cell = function() { if (this.undelete_backup !== null && this.undelete_index !== null) { @@ -890,7 +840,6 @@ define([ * * 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 * @@ -960,13 +909,11 @@ define([ /** * Insert an element at given cell index. + * return true if everything whent fine. * - * @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){ @@ -1001,7 +948,6 @@ define([ * * default index value is the one of currently selected cell * - * @method insert_cell_above * @param [type] {string} cell type * @param [index] {integer} * @@ -1018,12 +964,10 @@ define([ * * 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); @@ -1034,7 +978,6 @@ define([ /** * Insert cell at end of notebook * - * @method insert_cell_at_bottom * @param {String} type cell type * * @return the added cell; or null @@ -1047,7 +990,6 @@ define([ /** * Turn a cell into a code cell. * - * @method to_code * @param {Number} [index] A cell's index */ Notebook.prototype.to_code = function (index) { @@ -1079,7 +1021,6 @@ define([ /** * Turn a cell into a Markdown cell. * - * @method to_markdown * @param {Number} [index] A cell's index */ Notebook.prototype.to_markdown = function (index) { @@ -1117,7 +1058,6 @@ define([ /** * Turn a cell into a raw text cell. * - * @method to_raw * @param {Number} [index] A cell's index */ Notebook.prototype.to_raw = function (index) { @@ -1151,8 +1091,9 @@ define([ Notebook.prototype._warn_heading = function () { /** - * warn about heading cells being removed + * @private */ + // warn about heading cells being removed dialog.modal({ notebook: this, keyboard_manager: this.keyboard_manager, @@ -1169,14 +1110,13 @@ define([ }); }; + Notebook.prototype.to_heading = function (index, level) { /** * 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); @@ -1192,8 +1132,6 @@ define([ /** * Enable UI elements for pasting cells. - * - * @method enable_paste */ Notebook.prototype.enable_paste = function () { var that = this; @@ -1210,8 +1148,6 @@ define([ /** * Disable UI elements for pasting cells. - * - * @method disable_paste */ Notebook.prototype.disable_paste = function () { if (this.paste_enabled) { @@ -1224,8 +1160,6 @@ define([ /** * Cut a cell. - * - * @method cut_cell */ Notebook.prototype.cut_cell = function () { this.copy_cell(); @@ -1234,8 +1168,6 @@ define([ /** * Copy a cell. - * - * @method copy_cell */ Notebook.prototype.copy_cell = function () { var cell = this.get_selected_cell(); @@ -1249,8 +1181,6 @@ define([ /** * 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) { @@ -1265,8 +1195,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 +1207,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) { @@ -1295,8 +1221,6 @@ define([ /** * Split the selected cell into two, at the cursor. - * - * @method split_cell */ Notebook.prototype.split_cell = function () { var cell = this.get_selected_cell(); @@ -1313,8 +1237,6 @@ define([ /** * 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(); @@ -1348,8 +1270,6 @@ define([ /** * 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(); @@ -1387,7 +1307,6 @@ define([ /** * Hide a cell's output. * - * @method collapse_output * @param {Number} index A cell's numeric index */ Notebook.prototype.collapse_output = function (index) { @@ -1401,8 +1320,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,7 +1334,6 @@ define([ /** * Show a cell's output. * - * @method expand_output * @param {Number} index A cell's numeric index */ Notebook.prototype.expand_output = function (index) { @@ -1431,8 +1347,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,7 +1361,6 @@ define([ /** * Clear the selected CodeCell's output area. * - * @method clear_output * @param {Number} index A cell's numeric index */ Notebook.prototype.clear_output = function (index) { @@ -1461,8 +1374,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,7 +1387,6 @@ define([ /** * Scroll the selected CodeCell's output area. * - * @method scroll_output * @param {Number} index A cell's numeric index */ Notebook.prototype.scroll_output = function (index) { @@ -1490,8 +1400,6 @@ define([ /** * 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) { @@ -1505,7 +1413,6 @@ define([ /** 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) { @@ -1519,8 +1426,6 @@ define([ /** * Hide/show the output of all cells. - * - * @method toggle_all_output */ Notebook.prototype.toggle_all_output = function () { this.get_cells().map(function (cell, i) { @@ -1535,7 +1440,6 @@ define([ /** * 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) { @@ -1549,8 +1453,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 +1468,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 +1476,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 +1502,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) { @@ -1637,7 +1533,7 @@ define([ /** * Once a session is started, link the code cells to the kernel and pass the * comm manager to the widget manager - * + * @private */ Notebook.prototype._session_started = function (){ this._session_starting = false; @@ -1650,6 +1546,9 @@ define([ } } }; + /** + * @private + */ Notebook.prototype._session_start_failed = function (jqxhr, status, error){ this._session_starting = false; utils.log_ajax_error(jqxhr, status, error); @@ -1657,8 +1556,6 @@ define([ /** * Prompt the user to restart the IPython kernel. - * - * @method restart_kernel */ Notebook.prototype.restart_kernel = function () { var that = this; @@ -1683,13 +1580,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 +1592,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 +1619,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 +1646,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 +1654,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 +1661,6 @@ define([ /** * Execute all cells. - * - * @method execute_all_cells */ Notebook.prototype.execute_all_cells = function () { this.execute_cell_range(0, this.ncells()); @@ -1787,7 +1670,6 @@ 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) */ @@ -1804,7 +1686,6 @@ define([ /** * 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 () { @@ -1815,7 +1696,6 @@ define([ /** * 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) { @@ -1827,7 +1707,6 @@ 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 */ @@ -1843,7 +1722,6 @@ define([ /** * Load a notebook from JSON (.ipynb). * - * @method fromJSON * @param {Object} data JSON representation of a notebook */ Notebook.prototype.fromJSON = function (data) { @@ -1896,13 +1774,10 @@ define([ /** * 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; @@ -1933,7 +1808,6 @@ define([ /** * 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) { @@ -1964,8 +1838,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,7 +1876,6 @@ 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 */ @@ -2045,8 +1916,8 @@ define([ /** * update the autosave interval based on how long the last save took * - * @method _update_autosave_interval * @param {Integer} timestamp when the save request started + * @private */ Notebook.prototype._update_autosave_interval = function (start) { var duration = (new Date().getTime() - start); @@ -2065,7 +1936,6 @@ define([ /** * Explicitly trust the output of this notebook. * - * @method trust_notebook */ Notebook.prototype.trust_notebook = function () { var body = $("
").append($("

") @@ -2155,7 +2025,6 @@ define([ /** * 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) { @@ -2173,7 +2042,6 @@ define([ * * 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) { @@ -2311,7 +2179,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) { @@ -2340,8 +2207,6 @@ define([ /** * Save the notebook then immediately create a checkpoint. - * - * @method save_checkpoint */ Notebook.prototype.save_checkpoint = function () { this._checkpoint_after_save = true; @@ -2351,8 +2216,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 +2235,6 @@ define([ /** * List checkpoints for this notebook. - * - * @method list_checkpoints */ Notebook.prototype.list_checkpoints = function () { var that = this; @@ -2388,7 +2249,6 @@ define([ /** * Success callback for listing checkpoints. * - * @method list_checkpoint_success * @param {Object} data JSON representation of a checkpoint */ Notebook.prototype.list_checkpoints_success = function (data) { @@ -2403,8 +2263,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,7 +2277,6 @@ define([ /** * 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) { @@ -2471,7 +2328,6 @@ define([ /** * Restore the notebook to a checkpoint state. * - * @method restore_checkpoint * @param {String} checkpoint ID */ Notebook.prototype.restore_checkpoint = function (checkpoint) { @@ -2487,8 +2343,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,7 +2352,6 @@ define([ /** * Delete a notebook checkpoint. * - * @method delete_checkpoint * @param {String} checkpoint ID */ Notebook.prototype.delete_checkpoint = function (checkpoint) { @@ -2514,8 +2367,6 @@ define([ /** * Success callback for deleting a notebook checkpoint - * - * @method delete_checkpoint_success */ Notebook.prototype.delete_checkpoint_success = function () { this.events.trigger('checkpoint_deleted.Notebook'); diff --git a/docs/conf.json b/docs/conf.json new file mode 100644 index 000000000..67cc9a21f --- /dev/null +++ b/docs/conf.json @@ -0,0 +1,16 @@ +{ + "tags": { + "allowUnknownTags": true + }, + "source": { + "include": [ + "../IPython/html/static/notebook/js/notebook.js" + ] + }, + "plugins": [], + "templates": { + "cleverLinks": false, + "monospaceLinks": false + }, + "destination": "./out/" +} \ No newline at end of file From 0f2da9aa0756c8e67b6ea6700de193daa5a31579 Mon Sep 17 00:00:00 2001 From: Jonathan Frederic Date: Fri, 5 Dec 2014 11:38:19 -0800 Subject: [PATCH 2/9] Finish implementing JSDoc support --- docs/{conf.json => jsdoc_config.json} | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) rename docs/{conf.json => jsdoc_config.json} (88%) diff --git a/docs/conf.json b/docs/jsdoc_config.json similarity index 88% rename from docs/conf.json rename to docs/jsdoc_config.json index 67cc9a21f..7299244d4 100644 --- a/docs/conf.json +++ b/docs/jsdoc_config.json @@ -11,6 +11,5 @@ "templates": { "cleverLinks": false, "monospaceLinks": false - }, - "destination": "./out/" + } } \ No newline at end of file From 580230915149b68f5591b3dabb2bd8f26d1833ec Mon Sep 17 00:00:00 2001 From: Jonathan Frederic Date: Fri, 5 Dec 2014 12:10:37 -0800 Subject: [PATCH 3/9] Make notebook.js jsdoc compatible --- IPython/html/static/notebook/js/notebook.js | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/IPython/html/static/notebook/js/notebook.js b/IPython/html/static/notebook/js/notebook.js index 6c72cc48c..cb9b06b14 100644 --- a/IPython/html/static/notebook/js/notebook.js +++ b/IPython/html/static/notebook/js/notebook.js @@ -48,11 +48,18 @@ define([ "use strict"; /** - * - * @exports Notebook - * @class + * Contains and manages cells. + * @class Notebook * @param {String} selector - * @param {dictionary} options + * @param {dictionary} options - 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 */ var Notebook = function (selector, options) { this.config = utils.mergeopt(Notebook, options.config); @@ -169,7 +176,6 @@ define([ } }; - /** * Create an HTML and CSS representation of the notebook. */ From c46ae2e637e188b5e96b72a527cfeea25f5a7bb3 Mon Sep 17 00:00:00 2001 From: Jonathan Frederic Date: Fri, 5 Dec 2014 12:16:51 -0800 Subject: [PATCH 4/9] Markdown support. --- docs/jsdoc_config.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/jsdoc_config.json b/docs/jsdoc_config.json index 7299244d4..ba3ba968b 100644 --- a/docs/jsdoc_config.json +++ b/docs/jsdoc_config.json @@ -11,5 +11,9 @@ "templates": { "cleverLinks": false, "monospaceLinks": false + }, + "plugins": [ "plugins/markdown" ], + "markdown": { + "parser": "gfm" } } \ No newline at end of file From d756816e2b788df3768089fbe73b5f55bd274008 Mon Sep 17 00:00:00 2001 From: Jonathan Frederic Date: Fri, 5 Dec 2014 12:21:35 -0800 Subject: [PATCH 5/9] Some typo fixes --- IPython/html/static/notebook/js/notebook.js | 2 +- docs/jsdoc_config.json | 17 +++++++++-------- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/IPython/html/static/notebook/js/notebook.js b/IPython/html/static/notebook/js/notebook.js index cb9b06b14..9d9c66d58 100644 --- a/IPython/html/static/notebook/js/notebook.js +++ b/IPython/html/static/notebook/js/notebook.js @@ -1097,9 +1097,9 @@ define([ Notebook.prototype._warn_heading = function () { /** + * warn about heading cells being removed * @private */ - // warn about heading cells being removed dialog.modal({ notebook: this, keyboard_manager: this.keyboard_manager, diff --git a/docs/jsdoc_config.json b/docs/jsdoc_config.json index ba3ba968b..8cdd77aea 100644 --- a/docs/jsdoc_config.json +++ b/docs/jsdoc_config.json @@ -1,19 +1,20 @@ { - "tags": { - "allowUnknownTags": true + "markdown": { + "parser": "gfm" }, + "plugins": [ + "plugins/markdown" + ], "source": { "include": [ "../IPython/html/static/notebook/js/notebook.js" ] }, - "plugins": [], + "tags": { + "allowUnknownTags": true + }, "templates": { "cleverLinks": false, "monospaceLinks": false - }, - "plugins": [ "plugins/markdown" ], - "markdown": { - "parser": "gfm" } -} \ No newline at end of file +} From beb5ea6debfeda8df3f72c73094d16005cdfa7d7 Mon Sep 17 00:00:00 2001 From: Jonathan Frederic Date: Mon, 8 Dec 2014 10:27:32 -0800 Subject: [PATCH 6/9] Make sure every function appears in the Notebook class. --- IPython/html/static/notebook/js/notebook.js | 23 ++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/IPython/html/static/notebook/js/notebook.js b/IPython/html/static/notebook/js/notebook.js index 9d9c66d58..8319aafcf 100644 --- a/IPython/html/static/notebook/js/notebook.js +++ b/IPython/html/static/notebook/js/notebook.js @@ -314,10 +314,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; @@ -446,9 +446,9 @@ define([ * * @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"); }); @@ -1988,6 +1988,10 @@ define([ }); }; + /** + * Make a copy of the current notebook. + * @return {null} + */ Notebook.prototype.copy_notebook = function () { var that = this; var base_url = this.base_url; @@ -2006,6 +2010,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"; @@ -2024,6 +2033,10 @@ define([ ); }; + /** + * Delete this notebook + * @return {null} + */ Notebook.prototype.delete = function () { this.contents.delete(this.notebook_path); }; From c703b3f3f5d3bd986c5f64e5b37b3d23583ace2a Mon Sep 17 00:00:00 2001 From: Jonathan Frederic Date: Mon, 8 Dec 2014 10:39:04 -0800 Subject: [PATCH 7/9] Some clean-up --- IPython/html/static/notebook/js/notebook.js | 142 +++++++++++--------- 1 file changed, 75 insertions(+), 67 deletions(-) diff --git a/IPython/html/static/notebook/js/notebook.js b/IPython/html/static/notebook/js/notebook.js index 8319aafcf..9f9b11833 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); From 1e0acbeb31cf5d4453683540b6971983b77ca7b3 Mon Sep 17 00:00:00 2001 From: Jonathan Frederic Date: Mon, 8 Dec 2014 12:33:46 -0800 Subject: [PATCH 8/9] Write a plugin to handle private function automatically. --- IPython/html/static/notebook/js/notebook.js | 7 +------ docs/jsdoc_config.json | 3 ++- docs/jsdoc_plugin.js | 12 ++++++++++++ 3 files changed, 15 insertions(+), 7 deletions(-) create mode 100644 docs/jsdoc_plugin.js diff --git a/IPython/html/static/notebook/js/notebook.js b/IPython/html/static/notebook/js/notebook.js index 9f9b11833..0798435b3 100644 --- a/IPython/html/static/notebook/js/notebook.js +++ b/IPython/html/static/notebook/js/notebook.js @@ -336,7 +336,7 @@ define([ } } }); - } + }; /** * Set the dirty flag, and trigger the set_dirty.Notebook event @@ -921,7 +921,6 @@ define([ * Insert an element at given cell index. * return true if everything whent fine. * - * @private * @param {HTMLElement} element - a cell element * @param {integer} [index] a valid index where to inser cell **/ @@ -1101,7 +1100,6 @@ define([ /** * warn about heading cells being removed - * @private */ Notebook.prototype._warn_heading = function () { dialog.modal({ @@ -1543,7 +1541,6 @@ define([ /** * Once a session is started, link the code cells to the kernel and pass the * comm manager to the widget manager - * @private */ Notebook.prototype._session_started = function (){ this._session_starting = false; @@ -1557,7 +1554,6 @@ define([ } }; /** - * @private */ Notebook.prototype._session_start_failed = function (jqxhr, status, error){ this._session_starting = false; @@ -1927,7 +1923,6 @@ define([ * update the autosave interval based on how long the last save took * * @param {integer} timestamp - when the save request started - * @private */ Notebook.prototype._update_autosave_interval = function (start) { var duration = (new Date().getTime() - start); diff --git a/docs/jsdoc_config.json b/docs/jsdoc_config.json index 8cdd77aea..dd30a1502 100644 --- a/docs/jsdoc_config.json +++ b/docs/jsdoc_config.json @@ -3,7 +3,8 @@ "parser": "gfm" }, "plugins": [ - "plugins/markdown" + "plugins/markdown" , + "jsdoc_plugin.js" ], "source": { "include": [ 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 From 12366e8e8d7452ba09d2497dca351bad9b8c5c62 Mon Sep 17 00:00:00 2001 From: Jonathan Frederic Date: Thu, 11 Dec 2014 13:01:58 -0800 Subject: [PATCH 9/9] Clean up comments --- IPython/html/static/notebook/js/notebook.js | 220 ++++++++++---------- 1 file changed, 106 insertions(+), 114 deletions(-) diff --git a/IPython/html/static/notebook/js/notebook.js b/IPython/html/static/notebook/js/notebook.js index 0798435b3..940a3f31f 100644 --- a/IPython/html/static/notebook/js/notebook.js +++ b/IPython/html/static/notebook/js/notebook.js @@ -49,17 +49,18 @@ define([ /** * Contains and manages cells. + * * @class Notebook - * @param {string} selector - * @param {dictionary} options - 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 + * @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) { this.config = utils.mergeopt(Notebook, options.config); @@ -354,16 +355,16 @@ 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 {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; }; @@ -386,7 +387,6 @@ define([ /** * Display a dialog that allows the user to edit the Notebook's metadata. - * @return {null} */ Notebook.prototype.edit_metadata = function () { var that = this; @@ -414,7 +414,7 @@ define([ /** * Get a particular 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) { @@ -439,7 +439,7 @@ define([ /** * Count the cells in this notebook. * - * @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; @@ -459,9 +459,9 @@ define([ }; /** - * Get a Cell object from this notebook. + * Get a Cell objects from this notebook. * - * @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) { @@ -476,7 +476,7 @@ define([ /** * Get the cell below a given 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) { @@ -491,7 +491,7 @@ define([ /** * Get the cell above a given 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) { @@ -506,8 +506,8 @@ 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. + * @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; @@ -520,10 +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. * - * @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; @@ -540,6 +540,7 @@ define([ /** * Get the currently selected cell. + * * @return {Cell} The selected cell */ Notebook.prototype.get_selected_cell = function () { @@ -550,7 +551,7 @@ define([ /** * Check whether a cell index is valid. * - * @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) { @@ -563,8 +564,8 @@ define([ /** * Get the index of the currently selected cell. - - * @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; @@ -582,7 +583,7 @@ define([ /** * Programmatically select a cell. * - * @param {number} index A cell's index + * @param {integer} index - A cell's index * @return {Notebook} This notebook */ Notebook.prototype.select = function (index) { @@ -639,8 +640,8 @@ define([ /** * Gets the index of the cell that is in edit mode. * - * @return index {integer} - **/ + * @return {integer} index + */ Notebook.prototype.get_edit_index = function () { var result = null; this.get_cell_elements().filter(function (index) { @@ -654,8 +655,8 @@ 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') { cell.command_mode(); @@ -667,7 +668,7 @@ define([ /** * Make the notebook enter command mode. - **/ + */ Notebook.prototype.command_mode = function () { var cell = this.get_cell(this.get_edit_index()); if (cell && this.mode !== 'command') { @@ -682,7 +683,7 @@ define([ * Handle when a cell fires it's edit_mode event. * * @param {Cell} [cell] Cell to enter edit mode on. - **/ + */ Notebook.prototype.handle_edit_mode = function (cell) { if (cell && this.mode !== 'edit') { cell.edit_mode(); @@ -694,7 +695,7 @@ define([ /** * Make a cell enter edit mode. - **/ + */ Notebook.prototype.edit_mode = function () { var cell = this.get_selected_cell(); if (cell && this.mode !== 'edit') { @@ -705,7 +706,7 @@ define([ /** * Focus the currently selected cell. - **/ + */ Notebook.prototype.focus_cell = function () { var cell = this.get_selected_cell(); if (cell === null) {return;} // No cell is selected @@ -717,9 +718,9 @@ define([ /** * Move given (or selected) cell up and select it. * - * @param {integer} [index] 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) { @@ -739,11 +740,11 @@ define([ /** - * Move given (or selected) cell down and select it + * Move given (or selected) cell down and select it. * - * @param {integer} [index] 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)) { @@ -767,7 +768,7 @@ define([ /** * Delete a cell from the notebook. * - * @param {integer} [index] cell's numeric index + * @param {integer} [index] - cell's numeric index * @return {Notebook} This notebook */ Notebook.prototype.delete_cell = function (index) { @@ -846,15 +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] - * - * @param {string} [type] in ['code','markdown', 'raw'], defaults to 'code' - * @param {integer} [index] a valid index where to insert cell + * Index will be brought back into the accessible range [0,n]. * + * @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(); @@ -919,11 +919,11 @@ define([ /** * Insert an element at given cell index. - * return true if everything whent fine. * * @param {HTMLElement} element - a cell element - * @param {integer} [index] a valid index where to inser cell - **/ + * @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; @@ -955,13 +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 - * - * @param {string} [type] cell type - * @param {integer} [index] - * + * @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); @@ -971,13 +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 - * - * @param {string} [type] cell type - * @param {integer} [index] - * + * @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); @@ -987,10 +981,9 @@ define([ /** * Insert cell at end of notebook * - * @param {string} type cell type - * - * @return {Cell|null} 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); @@ -999,7 +992,7 @@ define([ /** * Turn a cell into a code cell. * - * @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); @@ -1030,7 +1023,7 @@ define([ /** * Turn a cell into a Markdown cell. * - * @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); @@ -1067,7 +1060,7 @@ define([ /** * Turn a cell into a raw text cell. * - * @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); @@ -1099,7 +1092,7 @@ define([ }; /** - * warn about heading cells being removed + * Warn about heading cell support removal. */ Notebook.prototype._warn_heading = function () { dialog.modal({ @@ -1119,10 +1112,10 @@ define([ }; /** - * Turn a cell into a markdown cell with a heading. + * Turn a cell into a heading containing markdown cell. * - * @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); @@ -1139,7 +1132,7 @@ define([ // Cut/Copy/Paste /** - * Enable UI elements for pasting cells. + * Enable the UI elements for pasting cells. */ Notebook.prototype.enable_paste = function () { var that = this; @@ -1155,7 +1148,7 @@ define([ }; /** - * Disable UI elements for pasting cells. + * Disable the UI elements for pasting cells. */ Notebook.prototype.disable_paste = function () { if (this.paste_enabled) { @@ -1188,7 +1181,7 @@ define([ }; /** - * Replace the selected cell with a cell in the clipboard. + * Replace the selected cell with the cell in the clipboard. */ Notebook.prototype.paste_cell_replace = function () { if (this.clipboard !== null && this.paste_enabled) { @@ -1228,7 +1221,7 @@ define([ // Split/merge /** - * Split the selected cell into two, at the cursor. + * Split the selected cell into two cells. */ Notebook.prototype.split_cell = function () { var cell = this.get_selected_cell(); @@ -1244,7 +1237,7 @@ define([ }; /** - * Combine the selected cell into the cell above it. + * Merge the selected cell into the cell above it. */ Notebook.prototype.merge_cell_above = function () { var index = this.get_selected_index(); @@ -1277,7 +1270,7 @@ define([ }; /** - * Combine the selected cell into the cell below it. + * Merge the selected cell into the cell below it. */ Notebook.prototype.merge_cell_below = function () { var index = this.get_selected_index(); @@ -1315,7 +1308,7 @@ define([ /** * Hide a cell's output. * - * @param {integer} index - A cell's numeric index + * @param {integer} index - cell index */ Notebook.prototype.collapse_output = function (index) { var i = this.index_or_selected(index); @@ -1342,7 +1335,7 @@ define([ /** * Show a cell's output. * - * @param {integer} index - A cell's numeric index + * @param {integer} index - cell index */ Notebook.prototype.expand_output = function (index) { var i = this.index_or_selected(index); @@ -1369,7 +1362,7 @@ define([ /** * Clear the selected CodeCell's output area. * - * @param {integer} index - A cell's numeric index + * @param {integer} index - cell index */ Notebook.prototype.clear_output = function (index) { var i = this.index_or_selected(index); @@ -1395,7 +1388,7 @@ define([ /** * Scroll the selected CodeCell's output area. * - * @param {integer} index - A cell's numeric index + * @param {integer} index - cell index */ Notebook.prototype.scroll_output = function (index) { var i = this.index_or_selected(index); @@ -1407,7 +1400,7 @@ define([ }; /** - * Expand each code cell's output area, and add a scrollbar for long 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) { @@ -1419,9 +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. * - * @param {integer} index - A cell's numeric index + * @param {integer} index - cell index */ Notebook.prototype.toggle_output = function (index) { var i = this.index_or_selected(index); @@ -1433,7 +1427,7 @@ define([ }; /** - * Hide/show the output of all cells. + * Toggle the output of all cells. */ Notebook.prototype.toggle_all_output = function () { this.get_cells().map(function (cell, i) { @@ -1448,7 +1442,7 @@ define([ /** * Toggle a scrollbar for long cell outputs. * - * @param {integer} 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); @@ -1540,7 +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; @@ -1553,9 +1547,11 @@ define([ } } }; + /** + * Called when the session fails to start. */ - Notebook.prototype._session_start_failed = function (jqxhr, status, error){ + Notebook.prototype._session_start_failed = function(jqxhr, status, error){ this._session_starting = false; utils.log_ajax_error(jqxhr, status, error); }; @@ -1676,8 +1672,8 @@ define([ /** * Execute a contiguous range of cells. * - * @param {integer} start - Index of the first cell to execute (inclusive) - * @param {integer} 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(); @@ -1702,7 +1698,7 @@ define([ /** * Setter method for this notebook's 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]; @@ -1728,7 +1724,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) { @@ -1780,7 +1776,7 @@ define([ /** * Dump this notebook into a JSON-friendly object. * - * @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 @@ -1812,7 +1808,7 @@ define([ }; /** - * Start an autosave timer, for periodically saving the notebook. + * Start an autosave timer which periodically saves the notebook. * * @param {integer} interval - the autosave interval in milliseconds */ @@ -1883,7 +1879,7 @@ 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 {object} data - JSON representation of a notebook */ Notebook.prototype.save_notebook_success = function (start, data) { this.set_dirty(false); @@ -1920,7 +1916,7 @@ 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. * * @param {integer} timestamp - when the save request started */ @@ -1988,7 +1984,6 @@ define([ /** * Make a copy of the current notebook. - * @return {null} */ Notebook.prototype.copy_notebook = function () { var that = this; @@ -2009,7 +2004,7 @@ define([ }; /** - * Rename the notebook + * Rename the notebook. * @param {string} new_name * @return {Promise} promise that resolves when the notebook is renamed. */ @@ -2033,7 +2028,6 @@ define([ /** * Delete this notebook - * @return {null} */ Notebook.prototype.delete = function () { this.contents.delete(this.notebook_path); @@ -2059,7 +2053,7 @@ define([ * * Load notebook data from the JSON response. * - * @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; @@ -2220,7 +2214,7 @@ define([ }); }; - /********************* checkpoint-related *********************/ + /********************* checkpoint-related ********************/ /** * Save the notebook then immediately create a checkpoint. @@ -2232,7 +2226,6 @@ define([ /** * Add a checkpoint for this notebook. - * for use as a callback from checkpoint creation. */ Notebook.prototype.add_checkpoint = function (checkpoint) { var found = false; @@ -2266,7 +2259,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; @@ -2294,7 +2287,7 @@ 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); @@ -2304,7 +2297,6 @@ define([ /** * Display the restore checkpoint dialog * @param {string} checkpoint ID - * @return {null} */ Notebook.prototype.restore_checkpoint_dialog = function (checkpoint) { var that = this; @@ -2388,7 +2380,7 @@ define([ }; /** - * Success callback for deleting a notebook checkpoint + * Success callback for deleting a notebook checkpoint. */ Notebook.prototype.delete_checkpoint_success = function () { this.events.trigger('checkpoint_deleted.Notebook');