[FIX] *: fix a bunch of incorrectly documented docstring

Fix a bunch of ill-documented/incomplete/incorrect method docs
Without this, the automatic doc generation does not work.

12 files changed, 148 insertions, 118 deletions

diff --git a/addons/web/static/src/js/core/ajax.js b/addons/web/static/src/js/core/ajax.js
index 5bab96a0c1e..d69574d2e10 100644
--- a/addons/web/static/src/js/core/ajax.js
+++ b/addons/web/static/src/js/core/ajax.js
@@ -211,7 +211,7 @@ var loadJS = (function () {
  * @param {HTMLFormElement} [options.form] the form to submit in order to fetch the file
  * @param {Function} [options.success] callback in case of download success
  * @param {Function} [options.error] callback in case of request error, provided with the error body
- * @param {Function} [options.complete] called after both ``success`` and ``error` callbacks have executed
+ * @param {Function} [options.complete] called after both ``success`` and ``error`` callbacks have executed
  */
 function get_file(options) {
     // need to detect when the file is done downloading (not used
diff --git a/addons/web/static/src/js/core/bus.js b/addons/web/static/src/js/core/bus.js
index bf33c1fe01e..1f715da4df1 100644
--- a/addons/web/static/src/js/core/bus.js
+++ b/addons/web/static/src/js/core/bus.js
@@ -6,6 +6,8 @@ var mixins = require('web.mixins');
 
 /**
  * Event Bus used to bind events scoped in the current instance
+ *
+ * @class Bus
  */
 return Class.extend(mixins.EventDispatcherMixin, {
     init: function() {
diff --git a/addons/web/static/src/js/core/class.js b/addons/web/static/src/js/core/class.js
index 8e53f0ba06d..4d1e6baaa8e 100644
--- a/addons/web/static/src/js/core/class.js
+++ b/addons/web/static/src/js/core/class.js
@@ -12,46 +12,47 @@ odoo.define('web.Class', function () {
  * Defines The Class object. That object can be used to define and inherit classes using
  * the extend() method.
  *
- * Example:
+ * Example::
  *
- * var Person = Class.extend({
- *  init: function(isDancing){
- *     this.dancing = isDancing;
- *   },
- *   dance: function(){
- *     return this.dancing;
- *   }
- * });
+ *     var Person = Class.extend({
+ *      init: function(isDancing){
+ *         this.dancing = isDancing;
+ *       },
+ *       dance: function(){
+ *         return this.dancing;
+ *       }
+ *     });
  *
- * The init() method act as a constructor. This class can be instancied this way:
+ * The init() method act as a constructor. This class can be instanced this way::
  *
- * var person = new Person(true);
- * person.dance();
+ *     var person = new Person(true);
+ *     person.dance();
  *
- * The Person class can also be extended again:
+ *     The Person class can also be extended again:
  *
- * var Ninja = Person.extend({
- *   init: function(){
- *     this._super( false );
- *   },
- *   dance: function(){
- *     // Call the inherited version of dance()
- *     return this._super();
- *   },
- *   swingSword: function(){
- *     return true;
- *   }
- * });
+ *     var Ninja = Person.extend({
+ *       init: function(){
+ *         this._super( false );
+ *       },
+ *       dance: function(){
+ *         // Call the inherited version of dance()
+ *         return this._super();
+ *       },
+ *       swingSword: function(){
+ *         return true;
+ *       }
+ *     });
  *
  * When extending a class, each re-defined method can use this._super() to call the previous
  * implementation of that method.
+ *
+ * @class Class
  */
+function OdooClass(){}
+
 var initializing = false;
 var fnTest = /xyz/.test(function(){xyz();}) ? /\b_super\b/ : /.*/;
 
-// The web Class implementation (does nothing)
-function OdooClass(){};
-
 /**
  * Subclass an existing class
  *
diff --git a/addons/web/static/src/js/core/concurrency.js b/addons/web/static/src/js/core/concurrency.js
index cab9df6529e..aeef29809d9 100644
--- a/addons/web/static/src/js/core/concurrency.js
+++ b/addons/web/static/src/js/core/concurrency.js
@@ -122,7 +122,7 @@ return {
      * the last operation.
      *
      * For example, let us say that we have a _fetch method on a widget which
-     * fetches data.  We want to rerender the widget after.  We could do this:
+     * fetches data.  We want to rerender the widget after.  We could do this::
      *
      *      this._fetch().then(function (result) {
      *          self.state = result;
@@ -130,17 +130,18 @@ return {
      *      });
      *
      * Now, we have at least two problems:
+     *
      * - if this code is called twice and the second _fetch completes before the
      *   first, the end state will be the result of the first _fetch, which is
      *   not what we expect
      * - in any cases, the user interface will rerender twice, which is bad.
      *
-     * Now, if we have a DropPrevious:
+     * Now, if we have a DropPrevious::
      *
      *      this.dropPrevious = new DropPrevious();
      *
      * Then we can wrap the _fetch in a DropPrevious and have the expected
-     * result:
+     * result::
      *
      *      this.dropPrevious
      *          .add(this._fetch())
@@ -153,7 +154,7 @@ return {
         /**
          * Registers a new deferred and rejects the previous one
          *
-         * @param {Deferred} the new deferred
+         * @param {Deferred} deferred the new deferred
          * @returns {Promise}
          */
         add: function (deferred) {
@@ -171,7 +172,7 @@ return {
      *
      * Imagine that we have a function to fetch some data _load(), which returns
      * a deferred which resolves to something useful. Now, we have some code
-     * looking like this:
+     * looking like this::
      *
      *      return this._load().then(function (result) {
      *          this.state = result;
@@ -179,11 +180,11 @@ return {
      *
      * If this code is run twice, but the second execution ends before the
      * first, then the final state will be the result of the first call to
-     * _load.  However, if we have a mutex:
+     * _load.  However, if we have a mutex::
      *
      *      this.mutex = new Mutex();
      *
-     * and if we wrap the calls to _load in a mutex:
+     * and if we wrap the calls to _load in a mutex::
      *
      *      return this.mutex.exec(function() {
      *          return this._load().then(function (result) {
diff --git a/addons/web/static/src/js/core/dialog.js b/addons/web/static/src/js/core/dialog.js
index 88bfae2b545..8c75db392fb 100644
--- a/addons/web/static/src/js/core/dialog.js
+++ b/addons/web/static/src/js/core/dialog.js
@@ -9,17 +9,17 @@ var QWeb = core.qweb;
 var _t = core._t;
 
 /**
-    A useful class to handle dialogs.
-
-    Attributes:
-    - $footer: A jQuery element targeting a dom part where buttons can be added. It always exists
-    during the lifecycle of the dialog.
-*/
+ * A useful class to handle dialogs.
+ * Attributes:
+ *
+ * ``$footer``
+ *   A jQuery element targeting a dom part where buttons can be added. It
+ *   always exists during the lifecycle of the dialog.
+ **/
 var Dialog = Widget.extend({
     xmlDependencies: ['/web/static/src/xml/dialog.xml'],
 
     /**
-     * @constructor
      * @param {Widget} parent
      * @param {Object} [options]
      * @param {string} [options.title=Odoo]
diff --git a/addons/web/static/src/js/core/dom.js b/addons/web/static/src/js/core/dom.js
index 7bae1bc29a5..6ca13f18e4e 100644
--- a/addons/web/static/src/js/core/dom.js
+++ b/addons/web/static/src/js/core/dom.js
@@ -115,10 +115,14 @@ return {
         }
     },
     /**
-     * jQuery find function behavior is:
+     * jQuery find function behavior is::
+     *
      *      $('A').find('A B') <=> $('A A B')
-     * The searches behavior to find options' DOM needs to be
+     *
+     * The searches behavior to find options' DOM needs to be::
+     *
      *      $('A').find('A B') <=> $('A B')
+     *
      * This is what this function does.
      *
      * @param {jQuery} $from - the jQuery element(s) from which to search
diff --git a/addons/web/static/src/js/core/mixins.js b/addons/web/static/src/js/core/mixins.js
index cc99cc1aaa4..79de054bf10 100644
--- a/addons/web/static/src/js/core/mixins.js
+++ b/addons/web/static/src/js/core/mixins.js
@@ -10,6 +10,9 @@ var AbstractService = require('web.AbstractService');
  * relationship. Each object can a have a parent and multiple children.
  * When an object is destroyed, all its children are destroyed too releasing
  * any resource they could have reserved before.
+ *
+ * @name ParentedMixin
+ * @mixin
  */
 var ParentedMixin = {
     __parentedMixin : true,
@@ -57,21 +60,21 @@ var ParentedMixin = {
         return this.__parentedDestroyed;
     },
     /**
-        Utility method to only execute asynchronous actions if the current
-        object has not been destroyed.
-
-        @param {$.Deferred} promise The promise representing the asynchronous
-                                    action.
-        @param {bool} [reject=false] If true, the returned promise will be
-                                     rejected with no arguments if the current
-                                     object is destroyed. If false, the
-                                     returned promise will never be resolved
-                                     or rejected.
-        @returns {$.Deferred} A promise that will mirror the given promise if
-                              everything goes fine but will either be rejected
-                              with no arguments or never resolved if the
-                              current object is destroyed.
-    */
+     * Utility method to only execute asynchronous actions if the current
+     * object has not been destroyed.
+     *
+     * @param {$.Deferred} promise The promise representing the asynchronous
+     *                             action.
+     * @param {bool} [reject=false] If true, the returned promise will be
+     *                              rejected with no arguments if the current
+     *                              object is destroyed. If false, the
+     *                              returned promise will never be resolved
+     *                              or rejected.
+     * @returns {$.Deferred} A promise that will mirror the given promise if
+     *                       everything goes fine but will either be rejected
+     *                       with no arguments or never resolved if the
+     *                       current object is destroyed.
+     */
     alive: function (promise, reject) {
         var self = this;
         return $.Deferred(function (def) {
@@ -228,13 +231,16 @@ var Events = Class.extend({
 });
 
 /**
-    Mixin containing an event system. Events are also registered by specifying the target object
-    (the object which will receive the event when it is raised). Both the event-emitting object
-    and the target object store or reference to each other. This is used to correctly remove all
-    reference to the event handler when any of the object is destroyed (when the destroy() method
-    from ParentedMixin is called). Removing those references is necessary to avoid memory leak
-    and phantom events (events which are raised and sent to a previously destroyed object).
-*/
+ * Mixin containing an event system. Events are also registered by specifying the target object
+ * (the object which will receive the event when it is raised). Both the event-emitting object
+ * and the target object store or reference to each other. This is used to correctly remove all
+ * reference to the event handler when any of the object is destroyed (when the destroy() method
+ * from ParentedMixin is called). Removing those references is necessary to avoid memory leak
+ * and phantom events (events which are raised and sent to a previously destroyed object).
+ *
+ * @name EventDispatcherMixin
+ * @mixin
+ */
 var EventDispatcherMixin = _.extend({}, ParentedMixin, {
     __eventDispatcherMixin: true,
     custom_events: {},
@@ -349,6 +355,10 @@ var EventDispatcherMixin = _.extend({}, ParentedMixin, {
     }
 });
 
+/**
+ * @name PropertiesMixin
+ * @mixin
+ */
 var PropertiesMixin = _.extend({}, EventDispatcherMixin, {
     init: function () {
         EventDispatcherMixin.init.call(this);
@@ -432,6 +442,10 @@ odoo.define('web.ServicesMixin', function (require) {
 
 var rpc = require('web.rpc');
 
+/**
+ * @mixin
+ * @name ServicesMixin
+ */
 var ServicesMixin = {
     call: function (service, method) {
         var args = Array.prototype.slice.call(arguments, 2);
@@ -450,9 +464,9 @@ var ServicesMixin = {
      * Builds and executes RPC query. Returns a deferred's promise resolved with
      * the RPC result.
      *
-     * @param {string} arg1 either a route or a model
-     * @param {string} method if a model is given, this argument is a method
-     * @returns {Deferred's Promise}
+     * @param {string} params either a route or a model
+     * @param {string} options if a model is given, this argument is a method
+     * @returns {Promise}
      */
     _rpc: function (params, options) {
         var query = rpc.buildQuery(params);
diff --git a/addons/web/static/src/js/core/pyeval.js b/addons/web/static/src/js/core/pyeval.js
index 502c6a4ce90..ee4ac697fd9 100644
--- a/addons/web/static/src/js/core/pyeval.js
+++ b/addons/web/static/src/js/core/pyeval.js
@@ -530,11 +530,11 @@ datetime.date = py.type('date', null, {
     }),
 });
 /**
-    Returns the current local date, which means the date on the client (which can be different
-    compared to the date of the server).
-
-    @return {datetime.date}
-*/
+ * Returns the current local date, which means the date on the client (which can be different
+ * compared to the date of the server).
+ *
+ * @return {datetime.date}
+ */
 function context_today() {
     var d = new Date();
     return py.PY_call(
diff --git a/addons/web/static/src/js/core/session.js b/addons/web/static/src/js/core/session.js
index fc45e669407..0ecea92fb71 100644
--- a/addons/web/static/src/js/core/session.js
+++ b/addons/web/static/src/js/core/session.js
@@ -321,8 +321,6 @@ var Session = core.Class.extend(mixins.EventDispatcherMixin, {
      * @param {String} url RPC endpoint
      * @param {Object} params call parameters
      * @param {Object} options additional options for rpc call
-     * @param {Function} success_callback function to execute on RPC call success
-     * @param {Function} error_callback function to execute on RPC call failure
      * @returns {jQuery.Deferred} jquery-provided ajax deferred
      */
     rpc: function (url, params, options) {
@@ -413,7 +411,7 @@ var Session = core.Class.extend(mixins.EventDispatcherMixin, {
      * (host system settings) to UTC, for a given date. The offset is positive
      * if the local timezone is behind UTC, and negative if it is ahead.
      *
-     * @param {string || moment} date a valid string date or moment instance
+     * @param {string | moment} date a valid string date or moment instance
      * @returns {integer}
      */
     getTZOffset: function (date) {
diff --git a/addons/web/static/src/js/core/translation.js b/addons/web/static/src/js/core/translation.js
index fae44774a07..76493fdb432 100644
--- a/addons/web/static/src/js/core/translation.js
+++ b/addons/web/static/src/js/core/translation.js
@@ -71,6 +71,16 @@ var TranslationDataBase = Class.extend(/** @lends instance.TranslationDataBase#
     }
 });
 
+/**
+ * Eager translation function, performs translation immediately at call
+ * site. Beware using this outside of method bodies (before the
+ * translation database is loaded), you probably want :func:`_lt`
+ * instead.
+ *
+ * @function _t
+ * @param {String} source string to translate
+ * @returns {String} source translated into the current locale
+ */
 var _t = new TranslationDataBase().build_translation_function();
 /**
  * Lazy translation function, only performs the translation when actually
diff --git a/addons/web/static/src/js/core/utils.js b/addons/web/static/src/js/core/utils.js
index 585be4d37b8..9eefc12944c 100644
--- a/addons/web/static/src/js/core/utils.js
+++ b/addons/web/static/src/js/core/utils.js
@@ -107,7 +107,7 @@ var utils = {
     /**
      * Returns a human readable size
      *
-     * @param {Number} number of bytes
+     * @param {Number} size number of bytes
      */
     human_size: function (size) {
         var units = _t("Bytes,Kb,Mb,Gb,Tb,Pb,Eb,Zb,Yb").split(',');
@@ -271,8 +271,8 @@ var utils = {
     /**
      * performs a half up rounding with a fixed amount of decimals, correcting for float loss of precision
      * See the corresponding float_round() in server/tools/float_utils.py for more info
-     * @param {Number} the value to be rounded
-     * @param {Number} the number of decimals. eg: round_decimals(3.141592,2) -> 3.14
+     * @param {Number} value the value to be rounded
+     * @param {Number} decimals the number of decimals. eg: round_decimals(3.141592,2) -> 3.14
      */
     round_decimals: function (value, decimals) {
         return utils.round_precision(value, Math.pow(10,-decimals));
@@ -319,9 +319,9 @@ var utils = {
     },
     /**
      * Create a cookie
-     * @param {String} name : the name of the cookie
-     * @param {String} value : the value stored in the cookie
-     * @param {Integer} ttl : time to live of the cookie in millis. -1 to erase the cookie.
+     * @param {String} name the name of the cookie
+     * @param {String} value the value stored in the cookie
+     * @param {Integer} ttl time to live of the cookie in millis. -1 to erase the cookie.
      */
     set_cookie: function (name, value, ttl) {
         ttl = ttl || 24*60*60*365;
diff --git a/addons/web/static/src/js/core/widget.js b/addons/web/static/src/js/core/widget.js
index 8ef141a6020..c47deff7330 100644
--- a/addons/web/static/src/js/core/widget.js
+++ b/addons/web/static/src/js/core/widget.js
@@ -7,50 +7,51 @@ var mixins = require('web.mixins');
 var ServicesMixin = require('web.ServicesMixin');
 
 /**
- * Base class for all visual components. Provides a lot of functionalities helpful
+ * Base class for all visual components. Provides a lot of functions helpful
  * for the management of a part of the DOM.
  *
  * Widget handles:
+ *
  * - Rendering with QWeb.
- * - Life-cycle management and parenting (when a parent is destroyed, all its children are
- *     destroyed too).
+ * - Life-cycle management and parenting (when a parent is destroyed, all its
+ *   children are destroyed too).
  * - Insertion in DOM.
  *
- * Guide to create implementations of the Widget class:
- * ==============================================
+ * **Guide to create implementations of the Widget class**
  *
- * Here is a sample child class:
+ * Here is a sample child class::
  *
- * MyWidget = openerp.base.Widget.extend({
- *     // the name of the QWeb template to use for rendering
- *     template: "MyQWebTemplate",
+ *     var MyWidget = openerp.base.Widget.extend({
+ *         // the name of the QWeb template to use for rendering
+ *         template: "MyQWebTemplate",
  *
- *     init: function(parent) {
- *         this._super(parent);
- *         // stuff that you want to init before the rendering
- *     },
- *     start: function() {
- *         // stuff you want to make after the rendering, `this.$el` holds a correct value
- *         this.$(".my_button").click(/* an example of event binding * /);
+ *         init: function(parent) {
+ *             this._super(parent);
+ *             // stuff that you want to init before the rendering
+ *         },
+ *         start: function() {
+ *             // stuff you want to make after the rendering, `this.$el` holds a correct value
+ *             this.$(".my_button").click(/* an example of event binding * /);
  *
- *         // if you have some asynchronous operations, it's a good idea to return
- *         // a promise in start()
- *         var promise = this._rpc(...);
- *         return promise;
- *     }
- * });
+ *             // if you have some asynchronous operations, it's a good idea to return
+ *             // a promise in start()
+ *             var promise = this._rpc(...);
+ *             return promise;
+ *         }
+ *     });
  *
- * Now this class can simply be used with the following syntax:
+ * Now this class can simply be used with the following syntax::
  *
- * var my_widget = new MyWidget(this);
- * my_widget.appendTo($(".some-div"));
+ *     var my_widget = new MyWidget(this);
+ *     my_widget.appendTo($(".some-div"));
  *
- * With these two lines, the MyWidget instance was inited, rendered, it was inserted into the
- * DOM inside the ".some-div" div and its events were binded.
+ * With these two lines, the MyWidget instance was initialized, rendered,
+ * inserted into the DOM inside the ``.some-div`` div and its events were
+ * bound.
  *
- * And of course, when you don't need that widget anymore, just do:
+ * And of course, when you don't need that widget anymore, just do::
  *
- * my_widget.destroy();
+ *     my_widget.destroy();
  *
  * That will kill the widget in a clean way and erase its content from the dom.
  */
@@ -67,7 +68,7 @@ var Widget = core.Class.extend(mixins.PropertiesMixin, ServicesMixin, {
      * The name of the QWeb template that will be used for rendering. Must be
      * redefined in subclasses or the default render() method can not be used.
      *
-     * @type string
+     * @type {String}
      */
     template: null,
     /**
@@ -82,8 +83,6 @@ var Widget = core.Class.extend(mixins.PropertiesMixin, ServicesMixin, {
     /**
      * Constructs the widget and sets its parent if a parent is given.
      *
-     * @constructs openerp.Widget
-     *
      * @param {openerp.Widget} parent Binds the current instance to the given Widget instance.
      * When that widget is destroyed by calling destroy(), the current instance will be
      * destroyed too. Can be null.
@@ -238,7 +237,7 @@ var Widget = core.Class.extend(mixins.PropertiesMixin, ServicesMixin, {
      * (if any) by the new one in the DOM.
      *
      * @param {HTMLElement | jQuery} $el
-     * @returns {*} this
+     * @returns {Widget} this
      */
     replaceElement: function ($el) {
         var $oldel = this.$el;
@@ -257,13 +256,14 @@ var Widget = core.Class.extend(mixins.PropertiesMixin, ServicesMixin, {
      * Re-sets the widget's root element (el/$el/$el).
      *
      * Includes:
+     *
      * * re-delegating events
      * * re-binding sub-elements
      * * if the widget already had a root element, replacing the pre-existing
      *   element in the DOM
      *
      * @param {HTMLElement | jQuery} element new root element for the widget
-     * @return {*} this
+     * @return {Widget} this
      */
     setElement: function (element) {
         // NB: completely useless, as WidgetMixin#init creates a $el