[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.

1 files changed, 34 insertions, 34 deletions

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