[FIX] doc: build errors & some warnings

closes odoo/odoo#30835

8 files changed, 43 insertions, 27 deletions

diff --git a/addons/mass_mailing/static/src/js/mass_mailing_widget.js b/addons/mass_mailing/static/src/js/mass_mailing_widget.js
index cf97d3fd9a0..e87c6a11f70 100644
--- a/addons/mass_mailing/static/src/js/mass_mailing_widget.js
+++ b/addons/mass_mailing/static/src/js/mass_mailing_widget.js
@@ -35,9 +35,9 @@ var MassMailingFieldHtml = FieldHtml.extend({
     //--------------------------------------------------------------------------
 
     /**
-     * Commit the change in 'style-inline' on an other field
-     * nodeOptions:
-     *      - inline-field: fieldName to save the html value converted into inline code
+     * Commit the change in 'style-inline' on an other field nodeOptions:
+     *
+     * - inline-field: fieldName to save the html value converted into inline code
      *
      * @override
      */
diff --git a/addons/web/static/src/js/widgets/name_and_signature.js b/addons/web/static/src/js/widgets/name_and_signature.js
index 53355fc7aa4..c860b0a4361 100644
--- a/addons/web/static/src/js/widgets/name_and_signature.js
+++ b/addons/web/static/src/js/widgets/name_and_signature.js
@@ -52,8 +52,9 @@ var NameAndSignature = Widget.extend({
      * @param {string} [options.mode='draw'] - @see this.setMode
      * @param {string} [options.signatureType='signature'] - The type of
      *  signature used in 'auto' mode. Can be one of the following values:
+     *
      *  - 'signature': it will adapt the characters width to fit the whole
-     *      text in the image.
+     *    text in the image.
      *  - 'initial': it will adapt the space between characters to fill
      *      the image with the text. The text will be the first letter of
      *      every word in the name, separated by dots.
diff --git a/addons/web_editor/static/src/js/wysiwyg/plugin/helper.js b/addons/web_editor/static/src/js/wysiwyg/plugin/helper.js
index 68542d7a4f8..9d346d42a27 100644
--- a/addons/web_editor/static/src/js/wysiwyg/plugin/helper.js
+++ b/addons/web_editor/static/src/js/wysiwyg/plugin/helper.js
@@ -125,7 +125,7 @@ var HelperPlugin = AbstractPlugin.extend({
      * Returns the number of leading breakable space in the textNode.
      * Note: returns 0 if the node is not a textNode.
      *
-     * @param {Node}
+     * @param {Node} node
      */
     countLeadingBreakableSpace: function (node) {
         if (!dom.isText(node)) {
@@ -151,19 +151,20 @@ var HelperPlugin = AbstractPlugin.extend({
     },
     /**
      * Remove the dom between 2 points (respecting unbreakable rules).
-     * Returns an object:
-     * {
-     *  node: pointA.node (updated if necessary),
-     *  offset: pointA.offset (updated if necessary),
-     *  changed: bool (whether changes were applied)
-     * }
+     * Returns an object::
+     *
+     *     {
+     *         node: pointA.node (updated if necessary),
+     *         offset: pointA.offset (updated if necessary),
+     *         changed: bool (whether changes were applied)
+     *     }
      * 
      * @param {Object} pointA
      * @param {Node} pointA.node
-     * @param {Integer} pointA.offset
+     * @param {number} pointA.offset
      * @param {Object} pointB
      * @param {Node} pointB.node
-     * @param {Integer} pointB.offset
+     * @param {number} pointB.offset
      * @returns {Object} {node, offset, changed}
      */
     deleteBetween: function (pointA, pointB) {
@@ -704,7 +705,7 @@ var HelperPlugin = AbstractPlugin.extend({
     /**
      * Returns the node targeted by a path
      *
-     * @param {Object[]} list of object (tagName, offset)
+     * @param {Object[]} path list of object (tagName, offset)
      * @returns {Node}
      */
     fromPath: function (path) {
diff --git a/addons/web_editor/static/src/js/wysiwyg/plugin/unbreakable.js b/addons/web_editor/static/src/js/wysiwyg/plugin/unbreakable.js
index 81a90d55413..388a3b2b2c9 100644
--- a/addons/web_editor/static/src/js/wysiwyg/plugin/unbreakable.js
+++ b/addons/web_editor/static/src/js/wysiwyg/plugin/unbreakable.js
@@ -33,7 +33,9 @@ var Unbreakable = AbstractPlugin.extend({
     //--------------------------------------------------------------------------
 
     /**
-     * Change the selection if it breaks an unbreakable node.
+     * Change the selection if it breaks an unbreakable node:
+     *
+     * .. code-block:: xml
      *
         <unbreakable id="a">
             content_1
@@ -56,6 +58,8 @@ var Unbreakable = AbstractPlugin.extend({
             </allow>
         </unbreakable>
 
+     * .. code-block: none
+
         START            END            RESIZE START     RESIZE END
 
         content_1       content_1       content_3       content_3   (find the first allowed node)
@@ -70,9 +74,9 @@ var Unbreakable = AbstractPlugin.extend({
         content_6       content_8       -               content_6
         content_7       content_8       -               content_8
         content_9       content_12      content_10      -
-        *
-        * @returns {WrappedRange}
-        */
+     *
+     * @returns {WrappedRange}
+     */
     secureRange: function () {
         var self = this;
         var range = this.context.invoke('editor.createRange');
diff --git a/addons/web_editor/static/src/js/wysiwyg/wysiwyg_iframe.js b/addons/web_editor/static/src/js/wysiwyg/wysiwyg_iframe.js
index 9de5c6b4cb7..be6ac41e5cb 100644
--- a/addons/web_editor/static/src/js/wysiwyg/wysiwyg_iframe.js
+++ b/addons/web_editor/static/src/js/wysiwyg/wysiwyg_iframe.js
@@ -193,10 +193,6 @@ Wysiwyg.include({
  *
  * @param {Node} [DOM]
  * @returns {Object}
- * @returns {Node} sc - start container
- * @returns {Number} so - start offset
- * @returns {Node} ec - end container
- * @returns {Number} eo - end offset
 */
 Wysiwyg.getRange = function (DOM) {
     var summernote = (DOM.defaultView || DOM.ownerDocument.defaultView)._summernoteSlave || _summernoteMaster;
diff --git a/addons/web_editor/static/src/js/wysiwyg_snippets/wysiwyg_snippets.js b/addons/web_editor/static/src/js/wysiwyg_snippets/wysiwyg_snippets.js
index 5df48ebf2f9..f88ae46376f 100644
--- a/addons/web_editor/static/src/js/wysiwyg_snippets/wysiwyg_snippets.js
+++ b/addons/web_editor/static/src/js/wysiwyg_snippets/wysiwyg_snippets.js
@@ -50,7 +50,6 @@ Wysiwyg.include({
      * snippets can by url begin with '/' or an view xml_id.
      *
      * @override
-     * @param {string} [options.snippets]
      */
     start: function () {
         var self = this;
diff --git a/doc/_extensions/autojsdoc/parser/jsdoc.py b/doc/_extensions/autojsdoc/parser/jsdoc.py
index e6bd609f298..9e9b0ba441d 100644
--- a/doc/_extensions/autojsdoc/parser/jsdoc.py
+++ b/doc/_extensions/autojsdoc/parser/jsdoc.py
@@ -275,11 +275,26 @@ class ClassDoc(NSDoc):
         d['mixins'] = self.mixins
         return d
 
+DEFAULT = object()
 class UnknownNS(NSDoc):
+    params = () # TODO: log warning when (somehow) trying to access / document an unknown object as ctor?
     def get_property(self, name):
         return super(UnknownNS, self).get_property(name) or \
            UnknownNS({'name': '{}.{}'.format(self.name, name)})
 
+    def __getitem__(self, item):
+        if self._probably_not_property(item):
+            return super().__getitem__(item)
+        return self.get_property(item)
+
+    def _probably_not_property(self, item):
+        return (
+            not isinstance(item, str)
+            or item in (self.namekey, 'name', 'params')
+            or item.startswith(('_', 'guessed_'))
+            or item in self.parsed
+        )
+
 class Unknown(CommentDoc):
     @classmethod
     def from_(cls, source):
@@ -325,7 +340,7 @@ def parse_comments(comments, doctype=None):
     # in case a specific doctype is given, allow overriding it anyway
     return guess(parsed, default=doctype)
 
-def guess(parsed, default=NSDoc):
+def guess(parsed, default=UnknownNS):
     if 'class' in parsed:
         return ClassDoc(parsed)
     if 'function' in parsed:
diff --git a/doc/conf.py b/doc/conf.py
index 3563433ff9d..0390c443e15 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -6,11 +6,11 @@ import sphinx
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 DIR = os.path.dirname(__file__)
-sys.path.append(
+sys.path.insert(0,
     os.path.abspath(
         os.path.join(DIR, '_extensions')))
-# autodoc
-sys.path.append(os.path.abspath(os.path.join(DIR, '..')))
+# put current odoo's source on PYTHONPATH for autodoc
+sys.path.insert(0, os.path.abspath(os.path.join(DIR, '..')))
 
 # -- General configuration -----------------------------------------------------