comments for docs

package.json

@@ -3,7 +3,7 @@
   "title": "X-editable",
   "description": "In-place editing with Twitter Bootstrap, jQuery UI or pure jQuery",
   "version": "1.0.0",
-  "homepage": "https://github.com/vitalets/x-editable",
+  "homepage": "http://github.com/vitalets/x-editable",
   "author": {
     "name": "Vitaliy Potapov",
     "email": "noginsk@rambler.ru"

src/containers/editable-container.js

@@ -45,10 +45,10 @@ Applied as jQuery method.
             return this.$form;
         },        
 
-        /**
+        /*
         Returns jquery object of container
         @method tip()
-        **/         
+        */         
         tip: function() {
             return this.container().$tip;
         },
@@ -82,10 +82,10 @@ Applied as jQuery method.
             this.call('hide'); 
         },
 
-        /**
+        /*
         Updates the position of container when content changed.
         @method setPosition()
-        **/       
+        */       
         setPosition: function() {
             //tbd in child class
         },
@@ -113,8 +113,17 @@ Applied as jQuery method.
             @event save 
             @param {Object} event event object
             @param {Object} params additional params
-                @param {mixed} params.newValue submitted value
+            @param {mixed} params.newValue submitted value
-                @param {Object} params.response ajax response
+            @param {Object} params.response ajax response
+            @example
+            $('#username').on('save', function(e, params) {
+                //assuming server response: '{success: true}'
+                if(params.response && params.response.success) {
+                    alert('value ' + params.newValue + ' saved!');
+                } else {
+                    alert('error!'); 
+                } 
+            });
             **/             
             this.$element.triggerHandler('save', params);
         },
@@ -141,7 +150,19 @@ Applied as jQuery method.
 
     };
 
-    //jQuery plugin definition
+    /**
+    jQuery method to initialize editableContainer.
+    
+    @method $().editableContainer(options)
+    @params {Object} options
+    @example
+    $('#edit').editableContainer({
+        type: 'text',
+        url: 'post.php',
+        pk: 1,
+        value: 'hello'
+    });
+    **/  
     $.fn.editableContainer = function (option) {
         var args = arguments;
         return this.each(function () {

src/editable-form/editable-form.js

@@ -271,7 +271,7 @@ Editableform is linked with one of input types, e.g. 'text' or 'select'.
         Url for submit
 
         @property url 
-        @type string|object|array
+        @type string|function
         @default null
         **/        
         url:null,
@@ -284,7 +284,7 @@ Editableform is linked with one of input types, e.g. 'text' or 'select'.
         **/          
         params:null,
         /**
-        Name of field. Will be submitted on server. Can be taken from id attribute.
+        Name of field. Will be submitted on server. Can be taken from <code>id</code> attribute
 
         @property name 
         @type string
@@ -301,7 +301,7 @@ Editableform is linked with one of input types, e.g. 'text' or 'select'.
         pk: null,
         /**
         Initial value. If not defined - will be taken from element's content.
-        For <i>select</i> type should be defined (as it is ID of shown text).
+        For __select__ type should be defined (as it is ID of shown text).
 
         @property value 
         @type string|object
@@ -309,7 +309,7 @@ Editableform is linked with one of input types, e.g. 'text' or 'select'.
         **/        
         value: null,
         /**
-        Strategy for sending data on server. Can be auto|always|never.
+        Strategy for sending data on server. Can be <code>auto|always|never</code>.
         When 'auto' data will be sent on server only if pk defined, otherwise new value will be stored in element.
 
         @property send 

src/element/editable-element.js

@@ -89,7 +89,7 @@ Makes editable any HTML element on the page. Applied as jQuery method.
                 }
                /**        
                Fired each time when element's text is rendered. Occurs on initialization and on each update of value.
-               Can be used for customizing display of value.
+               Can be used for display customization.
                               
                @event render 
                @param {Object} event event object
@@ -296,15 +296,15 @@ Makes editable any HTML element on the page. Applied as jQuery method.
         
         /**
         Sets new value of editable
-        @method setValue(v, convertStr)
+        @method setValue(value, convertStr)
-        @param {mixed} v new value 
+        @param {mixed} value new value 
         @param {boolean} convertStr wether to convert value from string to internal format        
         **/         
-        setValue: function(v, convertStr) {
+        setValue: function(value, convertStr) {
             if(convertStr) {
-                this.value = this.input.str2value(v);
+                this.value = this.input.str2value(value);
             } else {
-                this.value = v;
+                this.value = value;
             }
             if(this.container) {
                 this.container.option('value', this.value);
@@ -337,7 +337,7 @@ Makes editable any HTML element on the page. Applied as jQuery method.
         var result = {}, args = arguments, datakey = 'editable';
         switch (option) {
             /**
-            Runs client-side validation for all editables in jquery array
+            Runs client-side validation for all matched editables
             
             @method validate()
             @returns {Object} validation errors map
@@ -345,8 +345,8 @@ Makes editable any HTML element on the page. Applied as jQuery method.
             $('#username, #fullname').editable('validate');
             // possible result:
             {
-            username: "username is requied",
+              username: "username is requied",
-            fullname: "fullname should be minimum 3 letters length"
+              fullname: "fullname should be minimum 3 letters length"
             }
             **/             
             case 'validate':
@@ -381,14 +381,14 @@ Makes editable any HTML element on the page. Applied as jQuery method.
 
             /**  
             This method collects values from several editable elements and submit them all to server. 
-            It is designed mainly for creating new records. 
+            It is designed mainly for <a href="#newrecord">creating new records</a>. 
             
             @method submit(options)
             @param {object} options 
             @param {object} options.url url to submit data 
             @param {object} options.data additional data to submit
-            @param {function} options.error error handler (called on both client-side and server-side validation errors)
+            @param {function} options.error(obj) error handler (called on both client-side and server-side validation errors)
-            @param {function} options.success success handler 
+            @param {function} options.success(obj) success handler 
             @returns {Object} jQuery object
             **/            
             case 'submit':  //collects value, validate and submit to server for creating new record
@@ -452,7 +452,7 @@ Makes editable any HTML element on the page. Applied as jQuery method.
         Type of input. Can be <code>text|textarea|select|date</code>
 
         @property type 
-        @type String
+        @type string
         @default 'text'
         **/
         type: 'text',        
@@ -465,7 +465,15 @@ Makes editable any HTML element on the page. Applied as jQuery method.
         **/         
         disabled: false,
         /**
-        How to toggle editable. Can be click|manual.
+        How to toggle editable. Can be <code>click|manual</code>. 
+        When set to <code>manual</code> you should manually call <code>show/hide</code> methods of editable.  
+        Note: if you are calling <code>show</code> on **click** event you need to apply <code>e.stopPropagation()</code> because container has behavior to hide on any click outside.
+        
+        @example
+        $('#edit-button').click(function(e) {
+            e.stopPropagation();
+            $('#username').editable('toggle');
+        });
 
         @property toggle 
         @type string
@@ -481,10 +489,10 @@ Makes editable any HTML element on the page. Applied as jQuery method.
         **/         
         emptytext: 'Empty',
         /**
-        Allows to automatically set element's text based on it's value. Usefull for select and date.
+        Allows to automatically set element's text based on it's value. Can be <code>auto|always|never</code>. Usefull for select and date.
-        For example, if dropdown list is <code>{1: 'a', 2: 'b'}</code> and elements value set to <code>1</code>, it's html will be automatically set to <code>a</code>.
+        For example, if dropdown list is <code>{1: 'a', 2: 'b'}</code> and element's value set to <code>1</code>, it's html will be automatically set to <code>'a'</code>.  
-        Can be auto|always|never. <code>auto</code> means text will be set only if element is empty.
+        <code>auto</code> - text will be automatically set only if element is empty.  
-        <code>always|never</code> means always(never) try to set element's text.
+        <code>always|never</code> - always(never) try to set element's text.
 
         @property autotext 
         @type string

src/inputs/abstract.js

@@ -115,7 +115,7 @@ To create your own input you should inherit from this class.
         
     Abstract.defaults = {  
         /**
-        HTML template of input
+        HTML template of input. Normally you should not change it.
 
         @property tpl 
         @type string
@@ -127,7 +127,7 @@ To create your own input you should inherit from this class.
 
         @property inputclass 
         @type string
-        @default 'span2'
+        @default span2
         **/         
         inputclass: 'span2',
         /**

src/inputs/date/date.js

@@ -1,7 +1,25 @@
 /**
-* date
+Bootstrap-datepicker.  
-* based on fork: https://github.com/vitalets/bootstrap-datepicker
+Description and examples: http://vitalets.github.com/bootstrap-datepicker.  
-*/
+For localization you can include js file from here: https://github.com/eternicode/bootstrap-datepicker/tree/master/js/locales
+
+@class date
+@extends abstract
+@example
+<a href="#" id="dob" data-type="date" data-pk="1" data-url="post.php" data-original-title="Select date">15/05/1984</a>
+<script>
+$(function(){
+    $('#dob').editable({
+        format: 'yyyy-mm-dd',    
+        viewformat: 'dd/mm/yyyy',    
+        datepicker: {
+                weekStart: 1
+           }
+        }
+    });
+});
+</script>
+**/
 (function ($) {
 
     var Date = function (options) {
@@ -68,15 +86,50 @@
     });
     
     Date.defaults = $.extend({}, $.fn.editableform.types.abstract.defaults, {
+        /**
+        @property tpl 
+        @default <div style="float: left; padding: 0; margin: 0 0 9px 0"></div>
+        **/         
         tpl:'<div style="float: left; padding: 0; margin: 0 0 9px 0"></div>',
+        /**
+        @property inputclass 
+        @default well
+        **/         
         inputclass: 'well',
-        format:'yyyy-mm-dd', //format used for sending to server and converting from value
+        /**
-        viewformat: null,  //used for display date in element
+        Format used for sending value to server. Also applied when converting date from <code>data-value</code> attribute.<br>
-        //special options
+        Possible tokens are: <code>d, dd, m, mm, yy, yyyy</code>  
-        weekStart: 0,
+        
-        startView: 0,
+        @property format 
+        @type string
+        @default yyyy-mm-dd
+        **/         
+        format:'yyyy-mm-dd',
+        /**
+        Format used for displaying date. Also applied when converting date from element's text on init.   
+        If not specified equals to <code>format</code>
+        
+        @property viewformat 
+        @type string
+        @default null
+        **/          
+        viewformat: null,  
+        /**
+        Configuration of datepicker.
+        Full list of options: http://vitalets.github.com/bootstrap-datepicker
+        
+        @property datepicker 
+        @type object
+        @default {
+            weekStart: 0,
+            startView: 0,
+            autoclose: false
+        }
+        **/
         datepicker:{
-            autoclose:false
+            weekStart: 0,
+            startView: 0,
+            autoclose: false
         }
     });   
 

src/inputs/dateui/dateui.js

@@ -1,9 +1,24 @@
 /**
-jQuery UI Datepicker
+jQuery UI Datepicker.  
-Note: you can not use both date and dateui on the same page.
+Description and examples: http://jqueryui.com/datepicker.  
+Do not use it together with bootstrap-datepicker.
 
 @class dateui
 @extends abstract
+@example
+<a href="#" id="dob" data-type="date" data-pk="1" data-url="post.php" data-original-title="Select date">15/05/1984</a>
+<script>
+$(function(){
+    $('#dob').editable({
+        format: 'yyyy-mm-dd',    
+        viewformat: 'dd/mm/yyyy',    
+        datepicker: {
+                firstDay: 1
+           }
+        }
+    });
+});
+</script>
 **/
 (function ($) {
 
@@ -101,7 +116,7 @@ Note: you can not use both date and dateui on the same page.
         inputclass: '',
         /**
         Format used for sending value to server. Also applied when converting date from <code>data-value</code> attribute.<br>
-        Full <a href="http://docs.jquery.com/UI/Datepicker/formatDate">list of tokens</a>.  
+        Full list of tokens: http://docs.jquery.com/UI/Datepicker/formatDate
         
         @property format 
         @type string
@@ -109,7 +124,8 @@ Note: you can not use both date and dateui on the same page.
         **/          
         format:'yyyy-mm-dd', 
         /**
-        Format used for displaying date. If not specified equals to <code>format</code>
+        Format used for displaying date. Also applied when converting date from element's text on init.    
+        If not specified equals to <code>format</code>
         
         @property viewformat 
         @type string
@@ -119,7 +135,7 @@ Note: you can not use both date and dateui on the same page.
         
         /**
         Configuration of datepicker.
-        Full list of <a href="http://api.jqueryui.com/datepicker">possible options</a>. 
+        Full list of options: http://api.jqueryui.com/datepicker
         
         @property datepicker 
         @type object

src/inputs/select.js

@@ -1,8 +1,23 @@
 /**
-Select input
+Select (dropdown) input
 
 @class select
 @extends abstract
+@example
+<a href="#" id="status" data-type="select" data-pk="1" data-url="post.php" data-original-title="Select status"></a>
+<script>
+$(function(){
+    $('#status').editable({
+        value: 2,    
+        source: [
+              {value: 1, text: 'Active'},
+              {value: 2, text: 'Blocked'},
+              {value: 3, text: 'Deleted'}
+           ]
+        }
+    });
+});
+</script>
 **/
 (function ($) {
 
@@ -31,7 +46,7 @@ Select input
         },
 
         html2value: function (html) {
-            return null; //it's not good idea to set value by text for SELECT. better set NULL
+            return null; //it's not good idea to set value by text for SELECT. Better set NULL
         },
 
         value2html: function (value, element) {
@@ -229,8 +244,6 @@ Select input
         @property source 
         @type string|array|object
         @default null
-        @example
-        source: 'groups.php' 
         **/         
         source:null, 
         /**
@@ -253,4 +266,4 @@ Select input
 
     $.fn.editableform.types.select = Select;      
 
-}(window.jQuery));
+}(window.jQuery));

src/inputs/text.js

@@ -3,6 +3,16 @@ Text input
 
 @class text
 @extends abstract
+@example
+<a href="#" id="username" data-type="text" data-pk="1">awesome</a>
+<script>
+$(function(){
+    $('#username').editable({
+        url: 'post.php',
+        title: 'Enter username'
+    });
+});
+</script>
 **/
 (function ($) {
     var Text = function (options) {

src/inputs/textarea.js

@@ -3,7 +3,16 @@ Textarea input
 
 @class textarea
 @extends abstract
-@module inputs
+@example
+<a href="#" id="comments" data-type="textarea" data-pk="1">awesome comment!</a>
+<script>
+$(function(){
+    $('#comments').editable({
+        url: 'post.php',
+        title: 'Enter comments'
+    });
+});
+</script>
 **/
 (function ($) {
 
@@ -64,7 +73,7 @@ Textarea input
         tpl:'<textarea rows="8"></textarea>',
         /**
         @property inputclass 
-        @default 'span3'
+        @default span3
         **/          
         inputclass:'span3',
         /**