[FIX] doc: informal sub-params

Revert 6cb12273e2c1e1385098e38880317ae162dc902e which reverted
08d48b0fff0938e7ac004767dddfab13d3cff30b.

Issue was the support for sub-parameters (aka @param {type} foo.bar)
where the "parent" parameter was not formal (only present in a
function's docstring, but not in the function's parameters list),
subtype creation would fail to find a root parameter to attach the
sub-parameter to.

This has not actually been fixed, but for the specific case where the
formal parameters list is *completely empty* we fall back on a list of
the docstring's parameters, which works well enough for this case.

3 files changed, 17 insertions, 10 deletions

diff --git a/addons/web_tour/static/src/js/tour_manager.js b/addons/web_tour/static/src/js/tour_manager.js
index 1d89147f8a1..2bb3436f0b2 100644
--- a/addons/web_tour/static/src/js/tour_manager.js
+++ b/addons/web_tour/static/src/js/tour_manager.js
@@ -172,18 +172,18 @@ return core.Class.extend(mixins.EventDispatcherMixin, ServicesMixin, {
     /**
      * Registers a tour described by the following arguments *in order*
      *
-     * @param [string] name - tour's name
-     * @param [Object] - options (optional), available options are:
-     * @param [boolean] - true if this is only for tests
-     * @param [boolean]
+     * @param {string} name - tour's name
+     * @param {Object} [options] - options (optional), available options are:
+     * @param {boolean} [options.test=false] - true if this is only for tests
+     * @param {boolean} [options.skip_enabled=false]
      *        true to add a link in its tips to consume the whole tour
-     * @param [string]
+     * @param {string} [options.url]
      *        the url to load when manually running the tour
-     * @param [boolean]
+     * @param {boolean} [options.rainbowMan=true]
      *        whether or not the rainbowman must be shown at the end of the tour
-     * @param [Deferred]
+     * @param {Deferred} [options.wait_for]
      *        indicates when the tour can be started
-     * @param [Object] steps - steps' descriptions, each step being an object
+     * @param {Object[]} steps - steps' descriptions, each step being an object
      *                     containing a tip description
      */
     register: function() {
diff --git a/doc/_extensions/autojsdoc/ext/directives.py b/doc/_extensions/autojsdoc/ext/directives.py
index 98b3f9e8322..d127e24725b 100644
--- a/doc/_extensions/autojsdoc/ext/directives.py
+++ b/doc/_extensions/autojsdoc/ext/directives.py
@@ -565,6 +565,7 @@ def extract_subtypes(parent_name, doc):
             'name': typename,
             'doc': param.doc,
             '_members': [
+                # TODO: add default value
                 (sub.name, jsdoc.PropertyDoc(dict(sub.to_dict(), sourcemodule=doc['sourcemodule'])))
                 for sub in subs
             ],
diff --git a/doc/_extensions/autojsdoc/parser/jsdoc.py b/doc/_extensions/autojsdoc/parser/jsdoc.py
index a34a2aa9b83..55ec998c94f 100644
--- a/doc/_extensions/autojsdoc/parser/jsdoc.py
+++ b/doc/_extensions/autojsdoc/parser/jsdoc.py
@@ -122,8 +122,14 @@ class FunctionDoc(CommentDoc):
     @property
     def params(self):
         tag_texts = self.get_as_list('param')
-        if self.get('guessed_params') is None:
-            return [ParamDoc(text) for text in tag_texts]
+        # turns out guessed_params is *almost* (?) always set to a list,
+        # if empty list of guessed params fall back to @params
+        if not self['guessed_params']:
+            # only get "primary" params (no "." in name)
+            return [
+                p for p in map(ParamDoc, tag_texts)
+                if '.' not in p.name
+            ]
         else:
             param_dict = {}
             for text in tag_texts: