From a56372a4caa8b716ac0a4c36b3265ddce2d7b8d1 Mon Sep 17 00:00:00 2001 From: Xavier Morel Date: Tue, 24 Jul 2018 12:06:13 +0200 Subject: [PATCH] [FIX] various broken JS docstrings Resulting in sphinx warnings or ill-formatted doc all the way to the doc not building at all. --- .../static/src/js/models/website_livechat.js | 17 ++++----- .../src/js/models/website_livechat_message.js | 2 +- .../static/src/js/website_livechat_window.js | 2 +- addons/mail/static/src/js/discuss.js | 12 +++--- addons/mail/static/src/js/emojis.js | 10 ++--- .../static/src/js/models/messages/message.js | 2 +- .../static/src/js/models/threads/channel.js | 4 +- .../static/src/js/models/threads/thread.js | 4 +- addons/web/static/src/js/core/py_utils.js | 12 +++--- .../static/src/js/views/basic/basic_model.js | 14 ++++--- .../src/js/views/kanban/kanban_model.js | 6 +-- .../static/src/js/widgets/dropdown_menu.js | 37 +++++++++---------- .../web/static/src/js/widgets/rainbow_man.js | 8 +--- doc/_extensions/autojsdoc/ext/directives.py | 6 +++ doc/_extensions/autojsdoc/parser/jsdoc.py | 6 +++ 15 files changed, 76 insertions(+), 66 deletions(-) diff --git a/addons/im_livechat/static/src/js/models/website_livechat.js b/addons/im_livechat/static/src/js/models/website_livechat.js index cdb83c10c81..a21f2ee2f49 100644 --- a/addons/im_livechat/static/src/js/models/website_livechat.js +++ b/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 }; diff --git a/addons/im_livechat/static/src/js/models/website_livechat_message.js b/addons/im_livechat/static/src/js/models/website_livechat_message.js index cc03123952e..f8854ba7655 100644 --- a/addons/im_livechat/static/src/js/models/website_livechat_message.js +++ b/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 * diff --git a/addons/im_livechat/static/src/js/website_livechat_window.js b/addons/im_livechat/static/src/js/website_livechat_window.js index 656fcebd1b5..4e34be60557 100644 --- a/addons/im_livechat/static/src/js/website_livechat_window.js +++ b/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) { diff --git a/addons/mail/static/src/js/discuss.js b/addons/mail/static/src/js/discuss.js index bdf78d291b4..4208fb41cfe 100644 --- a/addons/mail/static/src/js/discuss.js +++ b/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: , @@ -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; diff --git a/addons/mail/static/src/js/emojis.js b/addons/mail/static/src/js/emojis.js index 4fedb5647a6..dcd53a3c5d1 100644 --- a/addons/mail/static/src/js/emojis.js +++ b/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 = { ":)": "😊", diff --git a/addons/mail/static/src/js/models/messages/message.js b/addons/mail/static/src/js/models/messages/message.js index 06b776ea580..9bf7a79d1b9 100644 --- a/addons/mail/static/src/js/models/messages/message.js +++ b/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" * diff --git a/addons/mail/static/src/js/models/threads/channel.js b/addons/mail/static/src/js/models/threads/channel.js index 86482a71a6d..a2775297cb2 100644 --- a/addons/mail/static/src/js/models/threads/channel.js +++ b/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} diff --git a/addons/mail/static/src/js/models/threads/thread.js b/addons/mail/static/src/js/models/threads/thread.js index 76d840a6100..fe9d23678d0 100644 --- a/addons/mail/static/src/js/models/threads/thread.js +++ b/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); diff --git a/addons/web/static/src/js/core/py_utils.js b/addons/web/static/src/js/core/py_utils.js index 83e24b207c6..9bcd66864e5 100644 --- a/addons/web/static/src/js/core/py_utils.js +++ b/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") diff --git a/addons/web/static/src/js/views/basic/basic_model.js b/addons/web/static/src/js/views/basic/basic_model.js index e0c516f02fb..186d0798e8f 100644 --- a/addons/web/static/src/js/views/basic/basic_model.js +++ b/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. * diff --git a/addons/web/static/src/js/views/kanban/kanban_model.js b/addons/web/static/src/js/views/kanban/kanban_model.js index 6c4ea1f133c..6cd3fb836fd 100644 --- a/addons/web/static/src/js/views/kanban/kanban_model.js +++ b/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 diff --git a/addons/web/static/src/js/widgets/dropdown_menu.js b/addons/web/static/src/js/widgets/dropdown_menu.js index 6fb8aab9bb4..a3a83519678 100644 --- a/addons/web/static/src/js/widgets/dropdown_menu.js +++ b/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; diff --git a/addons/web/static/src/js/widgets/rainbow_man.js b/addons/web/static/src/js/widgets/rainbow_man.js index e46201584bc..99a8f9dba79 100644 --- a/addons/web/static/src/js/widgets/rainbow_man.js +++ b/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) { diff --git a/doc/_extensions/autojsdoc/ext/directives.py b/doc/_extensions/autojsdoc/ext/directives.py index 649de9d151c..c666b07a20d 100644 --- a/doc/_extensions/autojsdoc/ext/directives.py +++ b/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 diff --git a/doc/_extensions/autojsdoc/parser/jsdoc.py b/doc/_extensions/autojsdoc/parser/jsdoc.py index 55ec998c94f..ff6d3196254 100644 --- a/doc/_extensions/autojsdoc/parser/jsdoc.py +++ b/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