Start to document Javascript

IPython/frontend/html/notebook/static/js/README.md

@@ -0,0 +1,48 @@
+Documentation
+=============
+
+How to Build/ view the doc for javascript.
+
+Javascript documentation should follow a style close to JSDoc one, so you
+should be able to build them with your favorite documentation builder.
+
+Still the documentation comment are mainly written to be read with YUI doc. 
+
+You can either build a static version, or start a YUIdoc server that will live
+update the doc at every page request. 
+
+To do so, you will need to install YUIdoc.
+
+## Install NodeJS
+
+Node is a browser less javascript interpreter. To install it please refer to
+the documentation for your platform. Install also NPM (node package manager) if
+it does not come bundled with it.  
+
+## Get YUIdoc
+
+npm does by default install package in `./node_modules` instead of doing a
+system wide install. I'll leave you to yuidoc docs if you want to make a system
+wide install.
+
+First, cd into js directory :
+```bash
+cd IPython/frontend/html/notebook/static/js/
+# install yuidoc
+npm install yuidoc
+```
+
+
+## Run YUIdoc server
+
+From IPython/frontend/html/notebook/static/js/
+```bash
+# run yuidoc for install dir 
+./node_modules/yuidocjs/lib/cli.js --server .
+```
+
+Follow the instruction and the documentation should be available on localhost:3000
+
+Omitting `--server` will build a static version in the `out` folder by default.
+
+

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

@@ -8,12 +8,25 @@
 //============================================================================
 // Cell
 //============================================================================
+/**
+ * An extendable module that provide base functionnality to create cell for notebook.
+ * @module IPython
+ * @namespace IPython
+ * @submodule Cell
+ */
 
 var IPython = (function (IPython) {
 
     var utils = IPython.utils;
 
+    /**
+     * The Base `Cell` class from which to inherit
+     * @class Cell
+     */
 
+    /*
+     * @constructor
+     */
     var Cell = function () {
         this.placeholder = this.placeholder || '';
         this.read_only = false;
@@ -31,10 +44,21 @@ var IPython = (function (IPython) {
     };
 
 
-    // Subclasses must implement create_element.
+    /**
+     * Empty. Subclasses must implement create_element.
+     * This should contain all the code to create the DOM element in notebook
+     * and will be called by Base Class constructor.
+     * @method create_element
+     */
     Cell.prototype.create_element = function () {};
 
 
+    /**
+     * Subclasses can implement override bind_events.
+     * Be carefull to call the parent method when overwriting as it fires event.
+     * this will be triggerd after create_element in constructor.
+     * @method bind_events
+     */
     Cell.prototype.bind_events = function () {
         var that = this;
         // We trigger events so that Cell doesn't have to depend on Notebook.
@@ -50,65 +74,111 @@ var IPython = (function (IPython) {
         });
     };
 
+    /**
+     * Triger typsetting of math by mathjax on current cell element
+     * @method typeset
+     */
     Cell.prototype.typeset = function () {
         if (window.MathJax){
             var cell_math = this.element.get(0);
             MathJax.Hub.Queue(["Typeset",MathJax.Hub,cell_math]);
         }
     };
 
+    /**
+     * should be triggerd when cell is selected
+     * @method select
+     */
     Cell.prototype.select = function () {
         this.element.addClass('ui-widget-content ui-corner-all');
         this.selected = true;
     };
 
 
+    /**
+     * should be triggerd when cell is unselected
+     * @method unselect
+     */
     Cell.prototype.unselect = function () {
         this.element.removeClass('ui-widget-content ui-corner-all');
         this.selected = false;
     };
 
-
+    /**
+     * should be overritten by subclass
+     * @method get_text
+     */
     Cell.prototype.get_text = function () {
     };
 
-
+    /**
+     * should be overritten by subclass
+     * @method set_text
+     * @param {string} text
+     */
     Cell.prototype.set_text = function (text) {
     };
 
-
+    /**
+     * Refresh codemirror instance
+     * @method refresh
+     */
     Cell.prototype.refresh = function () {
         this.code_mirror.refresh();
     };
 
 
+    /**
+     * should be overritten by subclass
+     * @method  edit
+     **/
     Cell.prototype.edit = function () {
     };
 
 
+    /**
+     * should be overritten by subclass
+     * @method render
+     **/
     Cell.prototype.render = function () {
     };
 
-
+    /**
+     * should be overritten by subclass
+     * serialise cell to json.
+     * @method toJSON
+     **/
     Cell.prototype.toJSON = function () {
         var data = {};
         data.metadata = this.metadata;
         return data;
     };
 
 
+    /**
+     * should be overritten by subclass
+     * @method fromJSON
+     **/
     Cell.prototype.fromJSON = function (data) {
         if (data.metadata !== undefined) {
             this.metadata = data.metadata;
         }
     };
 
 
+    /**
+     * can the cell be splitted in 2 cells.
+     * @method is_splittable
+     **/
     Cell.prototype.is_splittable = function () {
         return true;
     };
 
 
+    /**
+     * @return {String} - the text before the cursor
+     * @method get_pre_cursor
+     **/
     Cell.prototype.get_pre_cursor = function () {
         var cursor = this.code_mirror.getCursor();
         var text = this.code_mirror.getRange({line:0,ch:0}, cursor);
@@ -117,6 +187,10 @@ var IPython = (function (IPython) {
     }
 
 
+    /**
+     * @return {String} - the text after the cursor
+     * @method get_post_cursor
+     **/
     Cell.prototype.get_post_cursor = function () {
         var cursor = this.code_mirror.getCursor();
         var last_line_num = this.code_mirror.lineCount()-1;
@@ -128,9 +202,15 @@ var IPython = (function (IPython) {
     };
 
 
+    /** Grow the cell by hand. This is used upon reloading from JSON, when the
+     *  autogrow handler is not called.
+     *
+     *  could be made static
+     *
+     *  @param {Dom element} - element
+     *  @method grow
+     **/
     Cell.prototype.grow = function(element) {
-        // Grow the cell by hand. This is used upon reloading from JSON, when the
-        // autogrow handler is not called.
         var dom = element.get(0);
         var lines_count = 0;
         // modified split rule from
@@ -144,7 +224,10 @@ var IPython = (function (IPython) {
         }
     };
 
-
+    /**
+     * Toggle  CodeMirror LineNumber
+     * @method toggle_line_numbers
+     **/
     Cell.prototype.toggle_line_numbers = function () {
         if (this.code_mirror.getOption('lineNumbers') == false) {
             this.code_mirror.setOption('lineNumbers', true);
@@ -154,11 +237,22 @@ var IPython = (function (IPython) {
         this.code_mirror.refresh();
     };
 
+    /**
+     * force codemirror highlight mode
+     * @method force_highlight
+     * @param {object} - CodeMirror mode
+     **/
     Cell.prototype.force_highlight = function(mode) {
         this.user_highlight = mode;
         this.auto_highlight();
     };
 
+    /**
+     * Try to autodetect cell highlight mode, or use selected mode
+     * @methods _auto_highlight
+     * @private
+     * @param {String|object|undefined} - CodeMirror mode | 'auto'
+     **/
     Cell.prototype._auto_highlight = function (modes) {
         //Here we handle manually selected modes
         if( this.user_highlight != undefined &&  this.user_highlight != 'auto' )

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 =  $('<div></div>').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 || "&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;