[FIX] various broken JS docstrings

Resulting in sphinx warnings or ill-formatted doc all the way to the
doc not building at all.

addons/im_livechat/static/src/js/models/website_livechat.js

@@ -12,19 +12,18 @@ var WebsiteLivechat = AbstractThread.extend({
     /**
      * @override
      * @private
-     * @param {Object} params
-     * @param {Object} params.data
-     * @param {boolean} [params.data.folded] states whether the livechat is
+     * @param {Object} livechatData
+     * @param {boolean} [livechatData.folded] states whether the livechat is
      *   folded or not. It is considered only if this is defined and it is a
      *   boolean.
-     * @param {integer} params.data.id the ID of this livechat.
-     * @param {integer} [params.data.message_unread_counter=undefined] the
+     * @param {integer} livechatData.id the ID of this livechat.
+     * @param {integer} [livechatData.message_unread_counter] the
      *   unread counter of this livechat.
-     * @param {Array} params.data.operator_pid
-     * @param {string} params.data.name the name of this livechat.
-     * @param {string} [params.data.state] if 'folded', the livechat is folded.
+     * @param {Array} livechatData.operator_pid
+     * @param {string} livechatData.name the name of this livechat.
+     * @param {string} [livechatData.state] if 'folded', the livechat is folded.
      *   This is ignored if `folded` is provided and is a boolean value.
-     * @param {string} params.data.uuid the UUID of this livechat.
+     * @param {string} livechatData.uuid the UUID of this livechat.
      */
     init: function (livechatData) {
         var params = { data: livechatData };

addons/im_livechat/static/src/js/models/website_livechat_message.js

@@ -47,7 +47,7 @@ var WebsiteLivechatMessage =  AbstractMessage.extend({
     /**
      * Get the text to display for the author of the message
      *
-     * Rule of precedence for the displayed author:
+     * Rule of precedence for the displayed author::
      *
      *      author name > default usernane
      *

addons/im_livechat/static/src/js/website_livechat_window.js

@@ -11,7 +11,7 @@ var AbstractThreadWindow = require('mail.AbstractThreadWindow');
 var LivechatWindow = AbstractThreadWindow.extend({
     /**
      * @override
-     * @param {?} parent
+     * @param parent
      * @param {im_livechat.model.WebsiteLivechat} thread
      */
     init: function (parent, thread) {

addons/mail/static/src/js/discuss.js

@@ -126,10 +126,12 @@ var ModeratorRejectMessageDialog = Dialog.extend({
      * @param {Object} params
      * @param {integer[]} params.messageIDs list of message IDs to send
      *   'reject' decision reason
-     * @param {function} params.proceedReject a function to call when the
-     *   moderator confirms the reason for rejecting the messages. This
-     *   function passes an object as the reason for reject, which is
-     *   structured as follow:
+     * @param {function} params.proceedReject
+     *
+     *      a function to call when the
+     *      moderator confirms the reason for rejecting the
+     *      messages. This function passes an object as the
+     *      reason for reject, which is structured as follow::
      *
      *          {
      *              title: <string>,
@@ -602,7 +604,7 @@ var Discuss = AbstractAction.extend(ControlPanelMixin, {
      * cancel his action.
      *
      * @private
-     * @param {number[]]} messageIDs list of message IDs to reject
+     * @param {number[]} messageIDs list of message IDs to reject
      */
     _rejectMessages: function (messageIDs) {
         var self = this;

addons/mail/static/src/js/emojis.js

@@ -14,11 +14,11 @@ odoo.define('mail.emojis', function (require) {
  * This data represent all the available emojis that are supported on the web
  * client:
  *
- *    - key: this is the source representation of an emoji, i.e. its "character"
- *           representation. This is a string that can be easily typed by the
- *           user and then translated to its unicode representation (see value)
- *    - value: this is the unicode representation of an emoji, i.e. its "true"
- *             representation in the system.
+ * - key: this is the source representation of an emoji, i.e. its "character"
+ *        representation. This is a string that can be easily typed by the
+ *        user and then translated to its unicode representation (see value)
+ * - value: this is the unicode representation of an emoji, i.e. its "true"
+ *          representation in the system.
  */
 var data = {
     ":)":             "😊",

addons/mail/static/src/js/models/messages/message.js

@@ -132,7 +132,7 @@ var Message =  AbstractMessage.extend(Mixins.EventDispatcherMixin, ServicesMixin
     /**
      * Get the text to display for the author of the message
      *
-     * Rule of precedence for the displayed author:
+     * Rule of precedence for the displayed author::
      *
      *      author name > sender email > "anonymous"
      *

addons/mail/static/src/js/models/threads/channel.js

@@ -271,8 +271,8 @@ var Channel = ThreadWithCache.extend({
     /**
      * States whether this channel is a chat or not.
      * These types of channels are chat:
-     *      - direct messages (DM)
-     *      - livechat
+     * - direct messages (DM)
+     * - livechat
      *
      * @override
      * @returns {boolean}

addons/mail/static/src/js/models/threads/thread.js

@@ -19,8 +19,8 @@ var Thread = AbstractThread.extend(Mixins.EventDispatcherMixin, ServicesMixin, {
 
     /**
      * @override
-     * @param {mail.Manager} param.parent
      * @param {Object} params
+     * @param {mail.Manager} params.parent
      * @param {Object} params.data
      * @param {string} [params.data.channel_type]
      * @param {string} params.data.name
@@ -104,7 +104,7 @@ var Thread = AbstractThread.extend(Mixins.EventDispatcherMixin, ServicesMixin, {
      * the new state in the interface.
      *
      * @override
-     * @param {boolean} boolean
+     * @param {boolean} folded
      */
     fold: function (folded) {
         this._super.apply(this, arguments);

addons/web/static/src/js/core/py_utils.js

@@ -335,11 +335,13 @@ function py_eval(expr, context) {
 /**
  * Assemble domains into a single domains using an 'OR' or an 'AND' operator.
  *
- * Note: - this function does not evaluate anything inside the domain.  This is
- * actually quite critical because this allows the manipulation of unevaluated
- * (dynamic) domains.
- *       - this function gives a normalized domain as result,
- *       - applied on a list of length 1, it returns the domain normalized.
+ * .. note:
+ *
+ *      - this function does not evaluate anything inside the domain.  This
+ *        is actually quite critical because this allows the manipulation of
+ *        unevaluated (dynamic) domains.
+ *      - this function gives a normalized domain as result,
+ *      - applied on a list of length 1, it returns the domain normalized.
  *
  * @param {string[]} domains list of string representing domains
  * @param {"AND" | "OR"} operator used to combine domains (default "AND")

addons/web/static/src/js/views/basic/basic_model.js

@@ -685,12 +685,14 @@ var BasicModel = AbstractModel.extend({
      *
      * Case for not abandoning the record:
      *
-     *  1. flagged as 'no abandon' (i.e. during a `default_get`, including any
-     *     `onchange` from a `default_get`)
-     *  2. registered in a list on addition
-     *      2.1. registered as non-new addition
-     *      2.2. registered as new additon on update
-     *  3. record is not new
+     * 1. flagged as 'no abandon' (i.e. during a `default_get`, including any
+     *    `onchange` from a `default_get`)
+     * 2. registered in a list on addition
+     *
+     *    2.1. registered as non-new addition
+     *    2.2. registered as new additon on update
+     *
+     * 3. record is not new
      *
      * Otherwise, the record can be abandoned.
      *

addons/web/static/src/js/views/kanban/kanban_model.js

@@ -133,9 +133,9 @@ var KanbanModel = BasicModel.extend({
     /**
      * Add the following (kanban specific) keys when performing a `get`:
      * 
-     *  - tooltipData
-     *  - progressBarValues
-     *  - isGroupedByM2ONoColumn
+     * - tooltipData
+     * - progressBarValues
+     * - isGroupedByM2ONoColumn
      *
      * @override
      * @see _readTooltipFields

addons/web/static/src/js/widgets/dropdown_menu.js

@@ -21,24 +21,23 @@ var DropdownMenu = Widget.extend({
      * override
      *
      * @param {Widget} parent
-     * @param {Object} dropdowHeader object used to customize the dropdown menu. The keys:
-     *                      - 'title' (e.g. 'Group By')
-     *                      - 'icon' (e.g. 'fa-bars')
-     *                      - 'symbol' (e.g. 'caret')
-     *                      - 'category' (describes the type of items)
-     *                      - 'style' (button style)
-     * @param {Object} items list of menu items (type IGMenuItem below)
-     *   interface IMenuItem {
-     *      itemId: string; (optional) unique id associated with the item
-     *      description: string; label printed on screen
-     *      groupId: string;
-     *      isActive: boolean; (optional) determines if the item is considered active
-     *      isOpen: boolean; (optional) in case there are options the submenu presenting the options
-     *                                is opened or closed according to isOpen
-     *      isRemovable: boolean; (optional) can be removed from menu
-     *      options: array of objects with 'optionId' and 'description' keys; (optional)
-     *      currentOptionId: string refers to an optionId that is activated if item is active (optional)
-     *   }
+     * @param {Object} dropdownHeader object used to customize the dropdown menu.
+     * @param {String} dropdownHeader.title
+     * @param {String} dropdownHeader.icon
+     * @param {String} dropdownHeader.symbol
+     * @param {String} dropdownHeader.category descripbes the type of items
+     * @param {String} dropdownHeader.style the button style
+     * @param {Object[]} items list of menu items
+     *
+     * Menu items:
+     *
+     * * itemId: string; (optional) unique id associated with the item
+     * * description: string; label printed on screen
+     * * groupId: string;
+     * * isActive: boolean; (optional) determines if the item is considered active
+     * * isOpen: boolean; (optional) in case there are options the submenu presenting the options is opened or closed according to isOpen
+     * * isRemovable: boolean; (optional) can be removed from menu options: array of objects with 'optionId' and 'description' keys; (optional)
+     * * currentOptionId: string refers to an optionId that is activated if item is active (optional)
      */
     init: function (parent, dropdownHeader, items) {
         this._super(parent);
@@ -67,7 +66,7 @@ var DropdownMenu = Widget.extend({
     //--------------------------------------------------------------------------
 
     /**
-     * @param {Array[number]} groupIds
+     * @param {Number[]} groupIds
      */
     unsetGroups: function (groupIds) {
         var self = this;

addons/web/static/src/js/widgets/rainbow_man.js

@@ -25,13 +25,7 @@ var RainbowMan = Widget.extend({
      * @constructor
      * @param {Object} [options]
      * @param {string} [options.message] Message to be displayed on rainbowman card
-     * @param {string} [options.fadeout='medium'] Delay for rainbowman to disappear
-     *   [options.fadeout='fast'] will make rainbowman dissapear quickly,
-     *   [options.fadeout='medium'] and [options.fadeout='slow'] will wait
-     *     little longer before disappearing (can be used when [options.message]
-     *     is longer),
-     *   [options.fadeout='no'] will keep rainbowman on screen until user clicks
-     *     anywhere outside rainbowman
+     * @param {string} [options.fadeout='medium'] Delay for rainbowman to disappear. 'fast' will make rainbowman dissapear quickly, 'medium' and 'slow' will wait little longer before disappearing (can be used when options.message is longer), 'no' will keep rainbowman on screen until user clicks anywhere outside rainbowman
      * @param {string} [options.img_url] URL of the image to be displayed
      */
     init: function (options) {

doc/_extensions/autojsdoc/ext/directives.py

@@ -15,6 +15,7 @@ from sphinx.ext.autodoc import members_set_option, bool_option, ALL
 from autojsdoc.ext.extractor import read_js
 from ..parser import jsdoc, types
 
+class DocumenterError(Exception): pass
 
 @contextlib.contextmanager
 def addto(parent, newnode):
@@ -157,6 +158,11 @@ class Documenter(object):
         """
         :rtype: List[nodes.Node]
         """
+        try:
+            return self._generate(all_members=all_members)
+        except Exception as e:
+            raise DocumenterError("Failed to document %s" % self.item) from e
+    def _generate(self, all_members=False):
         objname = self.item.name
         prefixed = (self.item['sourcemodule'].name + '.' + objname) if self.item['sourcemodule'] else None
         objtype = self.objtype

doc/_extensions/autojsdoc/parser/jsdoc.py

@@ -233,6 +233,12 @@ class ModuleDoc(NSDoc):
         vars['exports'] = self.exports
         return vars
 
+    def __str__(self):
+        s = super().__str__()
+        if self['sourcefile']:
+            s += " in file " + self['sourcefile']
+        return s
+
 class ClassDoc(NSDoc):
     namekey = 'class'
     @property