From beb15f5e4641c5a43d39016bac87d5367feb7ac6 2014-07-10 20:47:23
From: jon <jon.freder@gmail.com>
Date: 2014-07-10 20:47:23
Subject: [PATCH] Added some nice comments,
so devs can easily figure out what options to pass
into the objects they want to construct.
---
diff --git a/IPython/html/static/notebook/js/cell.js b/IPython/html/static/notebook/js/cell.js
index 13bd925..d5f7946 100644
--- a/IPython/html/static/notebook/js/cell.js
+++ b/IPython/html/static/notebook/js/cell.js
@@ -27,18 +27,17 @@ define([
};
// end monkey patching CodeMirror
- /**
- * The Base `Cell` class from which to inherit
- * @class Cell
- **/
-
- /*
- * @constructor
- *
- * @param {object|undefined} [options]
- * @param [options.cm_config] {object} config to pass to CodeMirror, will extend default parameters
- */
var Cell = function (options) {
+ // Constructor
+ //
+ // The Base `Cell` class from which to inherit.
+ //
+ // Parameters:
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // events: $(Events) instance
+ // config: dictionary
+ // keyboard_manager: KeyboardManager instance
options = options || {};
this.keyboard_manager = options.keyboard_manager;
this.events = options.events;
diff --git a/IPython/html/static/notebook/js/codecell.js b/IPython/html/static/notebook/js/codecell.js
index 3869d7a..dd5e917 100644
--- a/IPython/html/static/notebook/js/codecell.js
+++ b/IPython/html/static/notebook/js/codecell.js
@@ -41,21 +41,21 @@ define([
var keycodes = keyboard.keycodes;
- /**
- * A Cell conceived to write code.
- *
- * The kernel doesn't have to be set at creation time, in that case
- * it will be null and set_kernel has to be called later.
- * @class CodeCell
- * @extends Cell
- *
- * @constructor
- * @param {Object|null} kernel
- * @param {object|undefined} [options]
- * @param [options.cm_config] {object} config to pass to CodeMirror
- */
var CodeCell = function (kernel, options) {
- options = options || {};
+ // Constructor
+ //
+ // A Cell conceived to write code.
+ //
+ // Parameters:
+ // kernel: Kernel instance
+ // The kernel doesn't have to be set at creation time, in that case
+ // it will be null and set_kernel has to be called later.
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // events: $(Events) instance
+ // config: dictionary
+ // keyboard_manager: KeyboardManager instance
+ // notebook: Notebook instance
this.kernel = kernel || null;
this.notebook = options.notebook;
this.collapsed = false;
diff --git a/IPython/html/static/notebook/js/keyboardmanager.js b/IPython/html/static/notebook/js/keyboardmanager.js
index dad667d..bf35e0f 100644
--- a/IPython/html/static/notebook/js/keyboardmanager.js
+++ b/IPython/html/static/notebook/js/keyboardmanager.js
@@ -16,6 +16,13 @@ define([
var keycodes = keyboard.keycodes;
var KeyboardManager = function (options) {
+ // Constructor
+ //
+ // Parameters:
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // events: $(Events) instance
+ // pager: Pager instance
this.mode = 'command';
this.enabled = true;
this.pager = options.pager;
diff --git a/IPython/html/static/notebook/js/maintoolbar.js b/IPython/html/static/notebook/js/maintoolbar.js
index e14e93f..1ec318b 100644
--- a/IPython/html/static/notebook/js/maintoolbar.js
+++ b/IPython/html/static/notebook/js/maintoolbar.js
@@ -10,6 +10,14 @@ define([
"use strict";
var MainToolBar = function (selector, options) {
+ // Constructor
+ //
+ // Parameters:
+ // selector: string
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // events: $(Events) instance
+ // notebook: Notebook instance
toolbar.ToolBar.apply(this, arguments);
this.events = options.events;
this.notebook = options.notebook;
diff --git a/IPython/html/static/notebook/js/mathjaxutils.js b/IPython/html/static/notebook/js/mathjaxutils.js
index fcd9867..ba5b59b 100644
--- a/IPython/html/static/notebook/js/mathjaxutils.js
+++ b/IPython/html/static/notebook/js/mathjaxutils.js
@@ -2,10 +2,11 @@
// Distributed under the terms of the Modified BSD License.
define([
+ 'base/js/namespace',
'jquery',
'base/js/utils',
'base/js/dialog',
-], function($, utils, dialog) {
+], function(IPython, $, utils, dialog) {
"use strict";
var init = function () {
@@ -235,9 +236,13 @@ define([
return text;
};
- return {
+ var mathjaxutils = {
init : init,
remove_math : remove_math,
replace_math : replace_math
};
+
+ IPython.mathjaxutils = mathjaxutils;
+
+ return mathjaxutils;
});
diff --git a/IPython/html/static/notebook/js/menubar.js b/IPython/html/static/notebook/js/menubar.js
index 9698d58..f5e37cd 100644
--- a/IPython/html/static/notebook/js/menubar.js
+++ b/IPython/html/static/notebook/js/menubar.js
@@ -6,25 +6,26 @@ define([
'jquery',
'base/js/utils',
'notebook/js/tour',
- 'components/bootstrap-tour/build/js/bootstrap-tour.min',
], function(IPython, $, utils, tour) {
"use strict";
- /**
- * A MenuBar Class to generate the menubar of IPython notebook
- * @Class MenuBar
- *
- * @constructor
- *
- *
- * @param selector {string} selector for the menubar element in DOM
- * @param {object} [options]
- * @param [options.base_url] {String} String to use for the
- * base project url. Default is to inspect
- * $('body').data('baseUrl');
- * does not support change for now is set through this option
- */
var MenuBar = function (selector, options) {
+ // Constructor
+ //
+ // A MenuBar Class to generate the menubar of IPython notebook
+ //
+ // Parameters:
+ // selector: string
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // notebook: Notebook instance
+ // layout_manager: LayoutManager instance
+ // events: $(Events) instance
+ // save_widget: SaveWidget instance
+ // quick_help: QuickHelp instance
+ // base_url : string
+ // notebook_path : string
+ // notebook_name : string
options = options || {};
this.base_url = options.base_url || utils.get_body_data("baseUrl");
this.selector = selector;
diff --git a/IPython/html/static/notebook/js/notebook.js b/IPython/html/static/notebook/js/notebook.js
index 6389862..f7aaee5 100644
--- a/IPython/html/static/notebook/js/notebook.js
+++ b/IPython/html/static/notebook/js/notebook.js
@@ -20,7 +20,7 @@ define([
$,
utils,
dialog,
- cells,
+ textcell,
codecell,
session,
celltoolbar,
@@ -29,16 +29,22 @@ define([
keyboard
) {
- /**
- * A notebook contains and manages cells.
- *
- * @class Notebook
- * @constructor
- * @param {String} selector A jQuery selector for the notebook's DOM element
- * @param {Object} [options] A config object
- * @param {Object} [events] An events object
- */
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
+ // save_widget: SaveWidget instance
+ // config: dictionary
+ // base_url : string
+ // notebook_path : string
+ // notebook_name : string
this.config = options.config || {};
this.base_url = options.base_url;
this.notebook_path = options.notebook_path;
@@ -806,9 +812,6 @@ define([
if (ncells === 0 || this.is_valid_cell_index(index) || index === ncells) {
var cell_options = {
- base_url: base_url,
- notebook_path: notebook_path,
- notebook_name: notebook_name,
events: this.events,
config: this.config,
keyboard_manager: this.keyboard_manager,
@@ -818,11 +821,11 @@ define([
cell = new codecell.CodeCell(this.kernel, cell_options);
cell.set_input_prompt();
} else if (type === 'markdown') {
- cell = new cells.MarkdownCell(cell_options);
+ cell = new textcell.MarkdownCell(cell_options);
} else if (type === 'raw') {
- cell = new cells.RawCell(cell_options);
+ cell = new textcell.RawCell(cell_options);
} else if (type === 'heading') {
- cell = new cells.HeadingCell(cell_options);
+ cell = new textcell.HeadingCell(cell_options);
}
if(this._insert_element_at_index(cell.element,index)) {
@@ -967,7 +970,7 @@ define([
if (this.is_valid_cell_index(i)) {
var source_element = this.get_cell_element(i);
var source_cell = source_element.data("cell");
- if (!(source_cell instanceof cells.MarkdownCell)) {
+ if (!(source_cell instanceof textcell.MarkdownCell)) {
var target_cell = this.insert_cell_below('markdown',i);
var text = source_cell.get_text();
if (text === source_cell.placeholder) {
@@ -981,7 +984,7 @@ define([
target_cell.code_mirror.clearHistory();
source_element.remove();
this.select(i);
- if ((source_cell instanceof cells.TextCell) && source_cell.rendered) {
+ if ((source_cell instanceof textcell.TextCell) && source_cell.rendered) {
target_cell.render();
}
var cursor = source_cell.code_mirror.getCursor();
@@ -1003,7 +1006,7 @@ define([
var source_element = this.get_cell_element(i);
var source_cell = source_element.data("cell");
var target_cell = null;
- if (!(source_cell instanceof cells.RawCell)) {
+ if (!(source_cell instanceof textcell.RawCell)) {
target_cell = this.insert_cell_below('raw',i);
var text = source_cell.get_text();
if (text === source_cell.placeholder) {
@@ -1038,7 +1041,7 @@ define([
var source_element = this.get_cell_element(i);
var source_cell = source_element.data("cell");
var target_cell = null;
- if (source_cell instanceof cells.HeadingCell) {
+ if (source_cell instanceof textcell.HeadingCell) {
source_cell.set_level(level);
} else {
target_cell = this.insert_cell_below('heading',i);
@@ -1057,7 +1060,7 @@ define([
this.select(i);
var cursor = source_cell.code_mirror.getCursor();
target_cell.code_mirror.setCursor(cursor);
- if ((source_cell instanceof cells.TextCell) && source_cell.rendered) {
+ if ((source_cell instanceof textcell.TextCell) && source_cell.rendered) {
target_cell.render();
}
}
@@ -1176,8 +1179,8 @@ define([
* @method split_cell
*/
Notebook.prototype.split_cell = function () {
- var mdc = cells.MarkdownCell;
- var rc = cells.RawCell;
+ var mdc = textcell.MarkdownCell;
+ var rc = textcell.RawCell;
var cell = this.get_selected_cell();
if (cell.is_splittable()) {
var texta = cell.get_pre_cursor();
@@ -1205,8 +1208,8 @@ define([
* @method merge_cell_above
*/
Notebook.prototype.merge_cell_above = function () {
- var mdc = cells.MarkdownCell;
- var rc = cells.RawCell;
+ var mdc = textcell.MarkdownCell;
+ var rc = textcell.RawCell;
var index = this.get_selected_index();
var cell = this.get_cell(index);
var render = cell.rendered;
@@ -1242,8 +1245,8 @@ define([
* @method merge_cell_below
*/
Notebook.prototype.merge_cell_below = function () {
- var mdc = cells.MarkdownCell;
- var rc = cells.RawCell;
+ var mdc = textcell.MarkdownCell;
+ var rc = textcell.RawCell;
var index = this.get_selected_index();
var cell = this.get_cell(index);
var render = cell.rendered;
diff --git a/IPython/html/static/notebook/js/notificationarea.js b/IPython/html/static/notebook/js/notificationarea.js
index 59d3a8c..11d03bd 100644
--- a/IPython/html/static/notebook/js/notificationarea.js
+++ b/IPython/html/static/notebook/js/notificationarea.js
@@ -11,6 +11,15 @@ define([
"use strict";
var NotificationArea = function (selector, options) {
+ // Constructor
+ //
+ // Parameters:
+ // selector: string
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // notebook: Notebook instance
+ // events: $(Events) instance
+ // save_widget: SaveWidget instance
this.selector = selector;
this.events = options.events;
this.save_widget = options.save_widget;
diff --git a/IPython/html/static/notebook/js/pager.js b/IPython/html/static/notebook/js/pager.js
index 744f339..a8c0cc2 100644
--- a/IPython/html/static/notebook/js/pager.js
+++ b/IPython/html/static/notebook/js/pager.js
@@ -9,6 +9,15 @@ define([
"use strict";
var Pager = function (pager_selector, pager_splitter_selector, options) {
+ // Constructor
+ //
+ // Parameters:
+ // pager_selector: string
+ // pager_splitter_selector: string
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // events: $(Events) instance
+ // layout_manager: LayoutManager instance
this.events = options.events;
this.pager_element = $(pager_selector);
this.pager_button_area = $('#pager_button_area');
diff --git a/IPython/html/static/notebook/js/quickhelp.js b/IPython/html/static/notebook/js/quickhelp.js
index aecf961..fff4f35 100644
--- a/IPython/html/static/notebook/js/quickhelp.js
+++ b/IPython/html/static/notebook/js/quickhelp.js
@@ -11,6 +11,13 @@ define([
var platform = utils.platform;
var QuickHelp = function (options) {
+ // Constructor
+ //
+ // Parameters:
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // events: $(Events) instance
+ // keyboard_manager: KeyboardManager instance
this.keyboard_manager = options.keyboard_manager;
this.keyboard_manager.quick_help = this;
this.events = options.events;
diff --git a/IPython/html/static/notebook/js/savewidget.js b/IPython/html/static/notebook/js/savewidget.js
index 70590ca..2b0e030 100644
--- a/IPython/html/static/notebook/js/savewidget.js
+++ b/IPython/html/static/notebook/js/savewidget.js
@@ -12,6 +12,7 @@ define([
"use strict";
var SaveWidget = function (selector, events) {
+ // TODO: Remove circulat ref.
this.notebook = undefined;
this.selector = selector;
this.events = events;
diff --git a/IPython/html/static/notebook/js/textcell.js b/IPython/html/static/notebook/js/textcell.js
index 1eb3f57..8f2755c 100644
--- a/IPython/html/static/notebook/js/textcell.js
+++ b/IPython/html/static/notebook/js/textcell.js
@@ -13,19 +13,21 @@ define([
"use strict";
var Cell = cell.Cell;
- /**
- * Construct a new TextCell, codemirror mode is by default 'htmlmixed', and cell type is 'text'
- * cell start as not redered.
- *
- * @class TextCell
- * @constructor TextCell
- * @extend Cell
- * @param {object|undefined} [options]
- * @param [options.cm_config] {object} config to pass to CodeMirror, will extend/overwrite default config
- * @param [options.placeholder] {string} default string to use when souce in empty for rendering (only use in some TextCell subclass)
- */
var TextCell = function (options) {
+ // Constructor
+ //
+ // Construct a new TextCell, codemirror mode is by default 'htmlmixed',
+ // and cell type is 'text' cell start as not redered.
+ //
+ // Parameters:
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // events: $(Events) instance
+ // config: dictionary
+ // keyboard_manager: KeyboardManager instance
+ // notebook: Notebook instance
options = options || {};
+
// in all TextCell/Cell subclasses
// do not assign most of members here, just pass it down
// in the options dict potentially overwriting what you wish.
@@ -214,12 +216,16 @@ define([
};
- /**
- * @class MarkdownCell
- * @constructor MarkdownCell
- * @extends IPython.HTMLCell
- */
var MarkdownCell = function (options) {
+ // Constructor
+ //
+ // Parameters:
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // events: $(Events) instance
+ // config: dictionary
+ // keyboard_manager: KeyboardManager instance
+ // notebook: Notebook instance
options = options || {};
var config = this.mergeopt(MarkdownCell, options.config);
TextCell.apply(this, [$.extend({}, options, {config: config})]);
@@ -263,14 +269,16 @@ define([
};
- // RawCell
-
- /**
- * @class RawCell
- * @constructor RawCell
- * @extends TextCell
- */
var RawCell = function (options) {
+ // Constructor
+ //
+ // Parameters:
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // events: $(Events) instance
+ // config: dictionary
+ // keyboard_manager: KeyboardManager instance
+ // notebook: Notebook instance
options = options || {};
var config = this.mergeopt(RawCell, options.config);
TextCell.apply(this, [$.extend({}, options, {config: config})]);
@@ -321,16 +329,16 @@ define([
};
- /**
- * @class HeadingCell
- * @extends TextCell
- */
-
- /**
- * @constructor HeadingCell
- * @extends TextCell
- */
var HeadingCell = function (options) {
+ // Constructor
+ //
+ // Parameters:
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // events: $(Events) instance
+ // config: dictionary
+ // keyboard_manager: KeyboardManager instance
+ // notebook: Notebook instance
options = options || {};
var config = this.mergeopt(HeadingCell, options.config);
TextCell.apply(this, [$.extend({}, options, {config: config})]);
diff --git a/IPython/html/static/notebook/js/tour.js b/IPython/html/static/notebook/js/tour.js
index 3ead790..0059319 100644
--- a/IPython/html/static/notebook/js/tour.js
+++ b/IPython/html/static/notebook/js/tour.js
@@ -4,7 +4,8 @@
define([
'base/js/namespace',
'jquery',
-], function(IPython, $) {
+ 'components/bootstrap-tour/build/js/bootstrap-tour.min',
+], function(IPython, $, Tour) {
"use strict";
var tour_style = "<div class='popover tour'>\n" +
diff --git a/IPython/html/static/tree/js/kernellist.js b/IPython/html/static/tree/js/kernellist.js
index 62305b7..60b5628 100644
--- a/IPython/html/static/tree/js/kernellist.js
+++ b/IPython/html/static/tree/js/kernellist.js
@@ -9,6 +9,15 @@ define([
"use strict";
var KernelList = function (selector, options) {
+ // Constructor
+ //
+ // Parameters:
+ // selector: string
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // session_list: SessionList instance
+ // base_url: string
+ // notebook_path: string
notebooklist.NotebookList.call(this, selector, $.extend({
element_name: 'running'},
options));
diff --git a/IPython/html/static/tree/js/notebooklist.js b/IPython/html/static/tree/js/notebooklist.js
index 8fe2ba3..4228e39 100644
--- a/IPython/html/static/tree/js/notebooklist.js
+++ b/IPython/html/static/tree/js/notebooklist.js
@@ -10,6 +10,16 @@ define([
"use strict";
var NotebookList = function (selector, options) {
+ // Constructor
+ //
+ // Parameters:
+ // selector: string
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // session_list: SessionList instance
+ // element_name: string
+ // base_url: string
+ // notebook_path: string
var that = this;
this.session_list = options.session_list;
// allow code re-use by just changing element_name in kernellist.js
diff --git a/IPython/html/static/tree/js/sessionlist.js b/IPython/html/static/tree/js/sessionlist.js
index 206b59e..2f3e623 100644
--- a/IPython/html/static/tree/js/sessionlist.js
+++ b/IPython/html/static/tree/js/sessionlist.js
@@ -8,7 +8,14 @@ define([
], function(IPython, $, utils) {
"use strict";
- var SesssionList = function (options, events) {
+ var SesssionList = function (options) {
+ // Constructor
+ //
+ // Parameters:
+ // options: dictionary
+ // Dictionary of keyword arguments.
+ // events: $(Events) instance
+ // base_url : string
this.events = options.events;
this.sessions = {};
this.base_url = options.base_url || utils.get_body_data("baseUrl");