start docummenting kernel

IPython/frontend/html/notebook/static/js/codecell.js

@@ -8,6 +8,12 b''
 //============================================================================
 // 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 b' 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 b' 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 =  $('<div></div>').addClass('cell border-box-sizing code_cell vbox');
         cell.attr('tabindex','2');
@@ -69,11 +87,14 b' 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 b' 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 b' 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 b' var IPython = (function (IPython) {'
     };
 
 
-
-
-
     CodeCell.input_prompt_classical = function (prompt_value, lines_number) {
         var ns = prompt_value || "&nbsp;";
         return 'In&nbsp;[' + 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('</br>')
     };
-    
+
     CodeCell.input_prompt_function = CodeCell.input_prompt_classical;
 
 

IPython/frontend/html/notebook/static/js/kernel.js

@@ -9,12 +9,22 b''
 // 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 b' 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 b' 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 b' 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 b' 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 b' 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 b' 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 b' 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 : '',

IPython/frontend/html/notebook/static/js/textcell.js

@@ -25,7 +25,7 b' 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 b' var IPython = (function (IPython) {'
     /**
      * @constructor HtmlCell
      * @class HtmlCell
-     * @extends TextCell
+     * @extends Ipython.TextCell
      */
     var HTMLCell = function () {
         this.placeholder = "Type <strong>HTML</strong> and LaTeX: $\\alpha^2$";
@@ -290,7 +290,7 b' 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 b' 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 b' 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";