Polish English and update version history.

erikrose · erikrose · commit cde306dd55e5 · 2018-03-22T09:06:45.000-04:00
diff --git a/README.rst b/README.rst
@@ -98,29 +98,16 @@ optional parameters::
 
     .. js:autofunction:: someFunction(foo, bar[, baz])
 
-Parametter's properties and destructuring parameters can also be documented::
+Parameter properties and destructuring parameters also work fine, using `standard JSDoc syntax <http://usejsdoc.org/tags-param.html#parameters-with-properties>`_::
 
     /**
      * Export an image from the given canvas and save it to the disk.
      *
-     * @param {string} filename The name of the output file.
-     * @param {Object} options Output options.
-     * @param {string} options.format The output format (``jpeg``, ``png`` or ``webp``).
-     * @param {number} options.quality The output quality when format is ``jpeg`` or ``webp`` (from ``0.00`` to ``1.00``).
+     * @param {Object} options Output options
+     * @param {string} options.format The output format (``jpeg``, ``png``, or ``webp``)
+     * @param {number} options.quality The output quality when format is ``jpeg`` or ``webp`` (from ``0.00`` to ``1.00``)
      */
-    function saveCanvas(filename, options) {
-        // ...
-    }
-
-    /**
-     * Export an image from the given canvas and save it to the disk.
-     *
-     * @param {string} filename The name of the output file.
-     * @param {Object} options Output options.
-     * @param {string} options.format The output format (``jpeg``, ``png`` or ``webp``).
-     * @param {number} options.quality The output quality when format is ``jpeg`` or ``webp`` (from ``0.00`` to ``1.00``).
-     */
-    function saveCanvas(filename, { format, quality }) {
+    function saveCanvas({ format, quality }) {
         // ...
     }
 
@@ -292,6 +279,10 @@ Run ``python setup.py test``. Run ``tox`` to test across Python versions.
 Version History
 ===============
 
+2.4.1
+  * Use documented ``@params`` to help fill out the formal param list for a
+    function. This keeps us from missing params that use destructuring. (flozz)
+
 2.4
   * Support the ``@example`` tag. (lidavidm)
 
diff --git a/sphinx_js/renderers.py b/sphinx_js/renderers.py
@@ -113,13 +113,15 @@ def _formal_params(self, doclet):
         if self._explicit_formal_params:
             return self._explicit_formal_params
 
-        # Try to use documented params (@param) first
+        # Harvest params from the @param tag unless they collide with an
+        # explicit formal param. Even look at params that are really
+        # documenting subproperties of formal params.
         params = reduce(
-                lambda l, v: l + [v] if not v in l else l,
-                [param['name'].split(".")[0] for param in doclet.get('params', [])],
-                [])
+            lambda l, v: l + [v] if not v in l else l,
+            [param['name'].split('.')[0] for param in doclet.get('params', [])],
+            [])
 
-        # Use params from js code if there is no documented params
+        # Use params from JS code if there are no documented params:
         if not params:
             params = doclet['meta']['code'].get('paramnames', [])
 
