From c83cd14d2848bb26460bb8e69da4c6a5701832bf Mon Sep 17 00:00:00 2001
From: Matthias BUSSONNIER <bussonniermatthias@gmail.com>
Date: Fri, 16 Nov 2012 18:46:00 +0100
Subject: [PATCH] more docs, organize in namespace

---
 .../frontend/html/notebook/static/js/cell.js  | 76 +++++++++++++++++--
 .../html/notebook/static/js/textcell.js       |  2 +
 2 files changed, 70 insertions(+), 8 deletions(-)

diff --git a/IPython/frontend/html/notebook/static/js/cell.js b/IPython/frontend/html/notebook/static/js/cell.js
index 32f45df3d..ebc112242 100644
--- a/IPython/frontend/html/notebook/static/js/cell.js
+++ b/IPython/frontend/html/notebook/static/js/cell.js
@@ -9,8 +9,10 @@
 // Cell
 //============================================================================
 /**
- * @module Cell
  * An extendable module that provide base functionnality to create cell for notebook.
+ * @module IPython
+ * @namespace IPython
+ * @submodule Cell
  */
 
 var IPython = (function (IPython) {
@@ -102,28 +104,50 @@ var IPython = (function (IPython) {
         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;
@@ -131,6 +155,10 @@ var IPython = (function (IPython) {
     };
 
 
+    /**
+     * should be overritten by subclass
+     * @method fromJSON
+     **/
     Cell.prototype.fromJSON = function (data) {
         if (data.metadata !== undefined) {
             this.metadata = data.metadata;
@@ -138,11 +166,19 @@ var IPython = (function (IPython) {
     };
 
 
+    /**
+     * 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);
@@ -151,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;
@@ -162,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
@@ -178,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);
@@ -188,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' )
diff --git a/IPython/frontend/html/notebook/static/js/textcell.js b/IPython/frontend/html/notebook/static/js/textcell.js
index 3fa43c58d..72c47e637 100644
--- a/IPython/frontend/html/notebook/static/js/textcell.js
+++ b/IPython/frontend/html/notebook/static/js/textcell.js
@@ -11,6 +11,8 @@
 
 /**
     A module that allow to create different type of Text Cell
+    @module IPython
+    @namespace IPython
  */
 var IPython = (function (IPython) {