upstream/ipython Commit - r19511:679a39e7

Clean up comments

Jonathan Frederic -

r19511:679a39e7

parent child

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

0 +106 -114

                  /**
                   * 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);
                  /**
                   * 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;
                  };
                  /**
                   * Display a dialog that allows the user to edit the Notebook's metadata.
-                  * @return {null}
                   */
                  Notebook.prototype.edit_metadata = function () {
                      var that = this;
                  /**
                   * 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) {
                  /**
                   * 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;
                  };
                  /**
-                  * 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) {
                  /**
                   * 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) {
                  /**
                   * 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) {
                  /**
                   * 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;
                  };
                  /**
-                  * 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;
                  /**
                   * Get the currently selected cell.
+                  *
                   * @return {Cell} The selected cell
                   */
                  Notebook.prototype.get_selected_cell = function () {
                  /**
                   * 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) {
                  /**
                   * 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;
                  /**
                   * 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) {
                  /**
                   * 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) {
                  /**
                   * 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();
                  /**
                   * 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') {
                   * 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();
                  /**
                   * Make a cell enter edit mode.
-                  **/
+                  */
                  Notebook.prototype.edit_mode = function () {
                      var cell = this.get_selected_cell();
                      if (cell && this.mode !== 'edit') {
                  /**
                   * Focus the currently selected cell.
-                  **/
+                  */
                  Notebook.prototype.focus_cell = function () {
                      var cell = this.get_selected_cell();
                      if (cell === null) {return;}  // No cell is selected
                  /**
                   * 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) {
                  /**
-                  * 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)) {
                  /**
                   * 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) {
                   * If cell type is not provided, it will default to the type of the
                   * currently active cell.
                   *
-                  * Similar to insert_above, but index parameter is mandatory
+                  *
-                  * Index will be brought back into the accessible range [0,n]
+                  * Similar to insert_above, but index parameter is mandatory.
                   *
-                  * @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();
                  /**
                   * 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;
                   * 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);
                   * 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);
                  /**
                   * 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);
                  /**
                   * 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);
                  /**
                   * 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);
                  /**
                   * 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);
                  };
                  /**
-                  * warn about heading cells being removed
+                  * Warn about heading cell support removal.
                   */
                  Notebook.prototype._warn_heading = function () {
                      dialog.modal({
                  };
                  /**
-                  * 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);
                  // Cut/Copy/Paste
                  /**
-                  * Enable UI elements for pasting cells.
+                  * Enable the UI elements for pasting cells.
                   */
                  Notebook.prototype.enable_paste = function () {
                      var that = this;
                  };
                  /**
-                  * Disable UI elements for pasting cells.
+                  * Disable the UI elements for pasting cells.
                   */
                  Notebook.prototype.disable_paste = function () {
                      if (this.paste_enabled) {
                  };
                  /**
-                  * 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) {
                  // 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();
                  };
                  /**
-                  * 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();
                  };
                  /**
-                  * 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();
                  /**
                   * 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);
                  /**
                   * 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);
                  /**
                   * 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);
                  /**
                   * 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);
                  };
                  /**
-                  * 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) {
                      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);
                  };
                  /**
-                  * 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) {
                  /**
                   * 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);
                  /**
                   * 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;
                          }
                      }
                  };
                  /**
+                  * 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);
                  };
                  /**
                   * 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();
                  /**
                   * 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];
                  /**
                   * 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) {
                  /**
                   * 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
                  };
                  /**
-                  * 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
                   */
                   * 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);
                  };
                  /**
-                  * 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
                   */
                  /**
                   * Make a copy of the current notebook.
-                  * @return {null}
                   */
                  Notebook.prototype.copy_notebook = function () {
                      var that = this;
                  };
                  /**
-                  * Rename the notebook
+                  * Rename the notebook.
                   * @param  {string} new_name
                   * @return {Promise} promise that resolves when the notebook is renamed.
                   */
                  /**
                   * Delete this notebook
-                  * @return {null}
                   */
                  Notebook.prototype.delete = function () {
                      this.contents.delete(this.notebook_path);
                   *
                   * 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;
                      });
                  };
-                 /*********************  checkpoint-related  *********************/
+                 /*********************  checkpoint-related  ********************/
                  /**
                   * Save the notebook then immediately create a checkpoint.
                  /**
                   * Add a checkpoint for this notebook.
-                  * for use as a callback from checkpoint creation.
                   */
                  Notebook.prototype.add_checkpoint = function (checkpoint) {
                      var found = false;
                  /**
                   * 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;
                  /**
                   * 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);
                  /**
                   * Display the restore checkpoint dialog
                   * @param  {string} checkpoint ID
-                  * @return {null}
                   */
                  Notebook.prototype.restore_checkpoint_dialog = function (checkpoint) {
                      var that = this;
                  };
                  /**
-                  * 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');

General Comments 0

Write
Preview

You need to be logged in to leave comments. Login now

No reviewers

No TODOs yet

	Site-wide shortcuts
/	Use quick search box
g h	Goto home page
g g	Goto my private gists page
g G	Goto my public gists page
g 0-9	Goto bookmarked items from 0-9
n r	New repository page
n g	New gist page

	Repositories
g s	Goto summary page
g c	Goto changelog page
g f	Goto files page
g F	Goto files page with file search activated
g p	Goto pull requests page
g o	Goto repository settings
g O	Goto repository access permissions settings
t s	Toggle sidebar on some pages