From ea8094cd342d7cdfe5fe2582e52a06b8c3b25b57 2012-11-17 19:46:51 From: Matthias BUSSONNIER Date: 2012-11-17 19:46:51 Subject: [PATCH] start docummenting kernel --- diff --git a/IPython/frontend/html/notebook/static/js/codecell.js b/IPython/frontend/html/notebook/static/js/codecell.js index bdba51c..112c0fa 100644 --- a/IPython/frontend/html/notebook/static/js/codecell.js +++ b/IPython/frontend/html/notebook/static/js/codecell.js @@ -8,6 +8,12 @@ //============================================================================ // CodeCell //============================================================================ +/** + * An extendable module that provide base functionnality to create cell for notebook. + * @module IPython + * @namespace IPython + * @submodule CodeCell + */ var IPython = (function (IPython) { "use strict"; @@ -16,9 +22,18 @@ var IPython = (function (IPython) { var key = IPython.utils.keycodes; CodeMirror.modeURL = "/static/codemirror/mode/%N/%N.js"; + /** + * 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 IPython.Cell + * + * @constructor + * @param {Object|null} kernel + */ var CodeCell = function (kernel) { - // 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. this.kernel = kernel || null; this.code_mirror = null; this.input_prompt_number = null; @@ -36,11 +51,14 @@ var IPython = (function (IPython) { CodeCell.prototype = new IPython.Cell(); - + /** + * @method auto_highlight + */ CodeCell.prototype.auto_highlight = function () { this._auto_highlight(IPython.config.cell_magic_highlight) }; + /** @method create_element */ CodeCell.prototype.create_element = function () { var cell = $('
').addClass('cell border-box-sizing code_cell vbox'); cell.attr('tabindex','2'); @@ -69,11 +87,14 @@ var IPython = (function (IPython) { } }; + /** + * This method gets called in CodeMirror's onKeyDown/onKeyPress + * handlers and is used to provide custom key handling. Its return + * value is used to determine if CodeMirror should ignore the event: + * true = ignore, false = don't ignore. + * @method handle_codemirror_keyevent + */ CodeCell.prototype.handle_codemirror_keyevent = function (editor, event) { - // This method gets called in CodeMirror's onKeyDown/onKeyPress - // handlers and is used to provide custom key handling. Its return - // value is used to determine if CodeMirror should ignore the event: - // true = ignore, false = don't ignore. if (this.read_only){ return false; @@ -155,7 +176,10 @@ var IPython = (function (IPython) { this.kernel = kernel; } - + /** + * Execute current code cell to the kernel + * @method execute + */ CodeCell.prototype.execute = function () { this.output_area.clear_output(true, true, true); this.set_input_prompt('*'); @@ -169,7 +193,10 @@ var IPython = (function (IPython) { var msg_id = this.kernel.execute(this.get_text(), callbacks, {silent: false}); }; - + /** + * @method _handle_execute_reply + * @private + */ CodeCell.prototype._handle_execute_reply = function (content) { this.set_input_prompt(content.execution_count); this.element.removeClass("running"); @@ -226,20 +253,17 @@ var IPython = (function (IPython) { }; - - - CodeCell.input_prompt_classical = function (prompt_value, lines_number) { var ns = prompt_value || " "; return 'In [' + ns + ']:' }; - + CodeCell.input_prompt_continuation = function (prompt_value, lines_number) { var html = [CodeCell.input_prompt_classical(prompt_value, lines_number)]; for(var i=1; i < lines_number; i++){html.push(['...:'])}; return html.join('
') }; - + CodeCell.input_prompt_function = CodeCell.input_prompt_classical; diff --git a/IPython/frontend/html/notebook/static/js/kernel.js b/IPython/frontend/html/notebook/static/js/kernel.js index 14f382f..b90b20f 100644 --- a/IPython/frontend/html/notebook/static/js/kernel.js +++ b/IPython/frontend/html/notebook/static/js/kernel.js @@ -9,12 +9,22 @@ // Kernel //============================================================================ +/** + * An extendable module that provide base functionnality to create cell for notebook. + * @module IPython + * @namespace IPython + * @submodule Kernel + */ + var IPython = (function (IPython) { var utils = IPython.utils; // Initialization and connection. - + /** + * A Kernel Class to communicate with the Python kernel + * @Class Kernel + */ var Kernel = function (base_url) { this.kernel_id = null; this.shell_channel = null; @@ -50,6 +60,10 @@ var IPython = (function (IPython) { return msg; }; + /** + * Start the Python kernel + * @method start + */ Kernel.prototype.start = function (notebook_id) { var that = this; if (!this.running) { @@ -62,7 +76,14 @@ var IPython = (function (IPython) { }; }; - + /** + * Restart the python kernel. + * + * Emit a 'status_restarting.Kernel' event with + * the current object as parameter + * + * @method restart + */ Kernel.prototype.restart = function () { $([IPython.events]).trigger('status_restarting.Kernel', {kernel: this}); var that = this; @@ -122,6 +143,12 @@ var IPython = (function (IPython) { }; + /** + * Start the `shell`and `iopub` channels. + * Will stop and restart them if they already exist. + * + * @method start_channels + */ Kernel.prototype.start_channels = function () { var that = this; this.stop_channels(); @@ -162,7 +189,10 @@ var IPython = (function (IPython) { }, 1000); }; - + /** + * Start the `shell`and `iopub` channels. + * @method stop_channels + */ Kernel.prototype.stop_channels = function () { if (this.shell_channel !== null) { this.shell_channel.onclose = function (evt) {}; @@ -178,17 +208,28 @@ var IPython = (function (IPython) { // Main public methods. + /** + * Get info on object asynchronoulsy + * + * @async + * @param objname {string} + * @param callback {dict} + * @method object_info_request + * + * @example + * + * When calling this method pass a callbacks structure of the form: + * + * callbacks = { + * 'object_info_reply': object_info_reply_callback + * } + * + * The `object_info_reply_callback` will be passed the content object of the + * + * `object_into_reply` message documented in + * [IPython dev documentation](http://ipython.org/ipython-doc/dev/development/messaging.html#object-information) + */ Kernel.prototype.object_info_request = function (objname, callbacks) { - // When calling this method pass a callbacks structure of the form: - // - // callbacks = { - // 'object_info_reply': object_into_reply_callback - // } - // - // The object_info_reply_callback will be passed the content object of the - // object_into_reply message documented here: - // - // http://ipython.org/ipython-doc/dev/development/messaging.html#object-information if(typeof(objname)!=null && objname!=null) { var content = { @@ -202,42 +243,61 @@ var IPython = (function (IPython) { return; } + /** + * Execute given code into kernel, and pass result to callback. + * + * @async + * @method execute + * @param {string} code + * @param callback {Object} With the following keys + * @param callback.'execute_reply' {function} + * @param callback.'output' {function} + * @param callback.'clear_output' {function} + * @param callback.'set_next_input' {function} + * @param {object} [options] + * @param [options.silent=false] {Boolean} + * @param [options.user_expressions=empty_dict] {Dict} + * @param [options.user_variables=empty_list] {List od Strings} + * @param [options.allow_stdin=false] {Boolean} true|false + * + * @example + * + * The options object should contain the options for the execute call. Its default + * values are: + * + * options = { + * silent : true, + * user_variables : [], + * user_expressions : {}, + * allow_stdin : false + * } + * + * When calling this method pass a callbacks structure of the form: + * + * callbacks = { + * 'execute_reply': execute_reply_callback, + * 'output': output_callback, + * 'clear_output': clear_output_callback, + * 'set_next_input': set_next_input_callback + * } + * + * The `execute_reply_callback` will be passed the content and metadata + * objects of the `execute_reply` message documented + * [here](http://ipython.org/ipython-doc/dev/development/messaging.html#execute) + * + * The `output_callback` will be passed `msg_type` ('stream','display_data','pyout','pyerr') + * of the output and the content and metadata objects of the PUB/SUB channel that contains the + * output: + * + * http://ipython.org/ipython-doc/dev/development/messaging.html#messages-on-the-pub-sub-socket + * + * The `clear_output_callback` will be passed a content object that contains + * stdout, stderr and other fields that are booleans, as well as the metadata object. + * + * The `set_next_input_callback` will be passed the text that should become the next + * input cell. + */ Kernel.prototype.execute = function (code, callbacks, options) { - // The options object should contain the options for the execute call. Its default - // values are: - // - // options = { - // silent : true, - // user_variables : [], - // user_expressions : {}, - // allow_stdin : false - // } - // - // When calling this method pass a callbacks structure of the form: - // - // callbacks = { - // 'execute_reply': execute_reply_callback, - // 'output': output_callback, - // 'clear_output': clear_output_callback, - // 'set_next_input': set_next_input_callback - // } - // - // The execute_reply_callback will be passed the content and metadata objects of the execute_reply - // message documented here: - // - // http://ipython.org/ipython-doc/dev/development/messaging.html#execute - // - // The output_callback will be passed msg_type ('stream','display_data','pyout','pyerr') - // of the output and the content and metadata objects of the PUB/SUB channel that contains the - // output: - // - // http://ipython.org/ipython-doc/dev/development/messaging.html#messages-on-the-pub-sub-socket - // - // The clear_output_callback will be passed a content object that contains - // stdout, stderr and other fields that are booleans, as well as the metadata object. - // - // The set_next_input_callback will be passed the text that should become the next - // input cell. var content = { code : code, @@ -254,18 +314,25 @@ var IPython = (function (IPython) { return msg.header.msg_id; }; - + /** + * When calling this method pass a callbacks structure of the form: + * + * callbacks = { + * 'complete_reply': complete_reply_callback + * } + * + * The `complete_reply_callback` will be passed the content object of the + * `complete_reply` message documented + * [here](http://ipython.org/ipython-doc/dev/development/messaging.html#complete) + * + * @method complete + * @param line {integer} + * @param cursor_pos {integer} + * @param {dict} callbacks + * @param callbacks.complete_reply {function} `complete_reply_callback` + * + */ Kernel.prototype.complete = function (line, cursor_pos, callbacks) { - // When calling this method pass a callbacks structure of the form: - // - // callbacks = { - // 'complete_reply': complete_reply_callback - // } - // - // The complete_reply_callback will be passed the content object of the - // complete_reply message documented here: - // - // http://ipython.org/ipython-doc/dev/development/messaging.html#complete callbacks = callbacks || {}; var content = { text : '', diff --git a/IPython/frontend/html/notebook/static/js/textcell.js b/IPython/frontend/html/notebook/static/js/textcell.js index 72c47e6..2a76e23 100644 --- a/IPython/frontend/html/notebook/static/js/textcell.js +++ b/IPython/frontend/html/notebook/static/js/textcell.js @@ -25,7 +25,7 @@ var IPython = (function (IPython) { * * @class TextCell * @constructor TextCell - * @extend Cell + * @extend Ipython.Cell */ var TextCell = function () { this.code_mirror_mode = this.code_mirror_mode || 'htmlmixed'; @@ -260,7 +260,7 @@ var IPython = (function (IPython) { /** * @constructor HtmlCell * @class HtmlCell - * @extends TextCell + * @extends Ipython.TextCell */ var HTMLCell = function () { this.placeholder = "Type HTML and LaTeX: $\\alpha^2$"; @@ -290,7 +290,7 @@ var IPython = (function (IPython) { /** * @class MarkdownCell * @constructor MarkdownCell - * @extends HtmlCell + * @extends Ipython.HtmlCell */ var MarkdownCell = function () { this.placeholder = "Type *Markdown* and LaTeX: $\\alpha^2$"; @@ -345,7 +345,7 @@ var IPython = (function (IPython) { /** * @class RawCell * @constructor RawCell - * @extends TextCell + * @extends Ipython.TextCell */ var RawCell = function () { this.placeholder = "Type plain text and LaTeX: $\\alpha^2$"; @@ -434,12 +434,12 @@ var IPython = (function (IPython) { /** * @class HeadingCell - * @extends TextCell + * @extends Ipython.TextCell */ /** * @constructor HeadingCell - * @extends TextCell + * @extends Ipython.TextCell */ var HeadingCell = function () { this.placeholder = "Type Heading Here";