Fix parameter sorting: avoid nesting errors and keep params together

Author: tmcw

Diff for: lib/infer/params.js

@@ -152,6 +152,18 @@ function paramToDoc(param, comment, i, prefix) {
   return addPrefix(newParam);
 }
 
+function insertBeforeDependents(comment, comments) {
+  var dependentNamePrefix = comment.name + '.';
+  for (var insertionIndex = 0; insertionIndex < comments.length; insertionIndex++) {
+    if (comments[insertionIndex].name.indexOf(dependentNamePrefix) === 0) {
+      break;
+    }
+  }
+  return comments.slice(0, insertionIndex)
+    .concat(comment)
+    .concat(comments.slice(insertionIndex));
+}
+
 /**
  * Infers param tags by reading function parameter names
  *
@@ -193,7 +205,7 @@ function inferParams() {
             comment.params = [];
           }
 
-          comment.params = comment.params.concat(doc);
+          comment.params = insertBeforeDependents(doc, comment.params);
         } else if (!existingParams[doc.name].type) {
           // This param has a description, but potentially it can
           // be have an inferred type. Infer its type without
@@ -212,15 +224,6 @@ function inferParams() {
         paramOrder[doc.name] = i++;
       });
 
-    // Ensure that if params are specified partially or in
-    // the wrong order, they'll be output in the order
-    // they actually appear in code
-    if (comment.params) {
-      comment.params.sort(function (a, b) {
-        return paramOrder[a.name] - paramOrder[b.name];
-      });
-    }
-
     return comment;
   });
 }

Diff for: test/fixture/nest_params.input.js

@@ -4,7 +4,7 @@
  * @param {string} employees[].department - The employee's department.
  * @param {string} [type=minion] - The employee's type.
  */
-function foo(employee, type) {
+function foo(employees, type) {
 }
 
 /**

Diff for: test/fixture/nest_params.output.json

@@ -271,11 +271,6 @@
           }
         ]
       },
-      {
-        "title": "param",
-        "name": "employee",
-        "lineNumber": 7
-      },
       {
         "name": "type",
         "lineNumber": 4,

Diff for: test/fixture/nest_params.output.md

@@ -7,7 +7,6 @@
 -   `employees` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** The employees who are responsible for the project.
     -   `employees[].name` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The name of an employee.
     -   `employees[].department` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** The employee's department.
--   `employee`  
 -   `type` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** The employee's type. (optional, default `minion`)
 
 # foo

Diff for: test/fixture/nest_params.output.md.json

@@ -272,28 +272,6 @@
             }
           ]
         },
-        {
-          "type": "listItem",
-          "children": [
-            {
-              "type": "paragraph",
-              "children": [
-                {
-                  "type": "inlineCode",
-                  "value": "employee"
-                },
-                {
-                  "type": "text",
-                  "value": " "
-                },
-                {
-                  "type": "text",
-                  "value": " "
-                }
-              ]
-            }
-          ]
-        },
         {
           "type": "listItem",
           "children": [

Diff for: test/fixture/params.output.json

@@ -88,11 +88,6 @@
     },
     "errors": [],
     "params": [
-      {
-        "title": "param",
-        "name": "a",
-        "lineNumber": 5
-      },
       {
         "name": "b",
         "lineNumber": 2,
@@ -153,6 +148,11 @@
           "name": "number"
         }
       },
+      {
+        "title": "param",
+        "name": "a",
+        "lineNumber": 5
+      },
       {
         "title": "param",
         "name": "c",

Diff for: test/fixture/params.output.md

@@ -6,8 +6,8 @@ This function returns the number one.
 
 **Parameters**
 
--   `a`  
 -   `b` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the second param
+-   `a`  
 -   `c`  
 -   `$3` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
     -   `$3.d`  

Diff for: test/fixture/params.output.md.json

@@ -63,28 +63,6 @@
       "ordered": false,
       "type": "list",
       "children": [
-        {
-          "type": "listItem",
-          "children": [
-            {
-              "type": "paragraph",
-              "children": [
-                {
-                  "type": "inlineCode",
-                  "value": "a"
-                },
-                {
-                  "type": "text",
-                  "value": " "
-                },
-                {
-                  "type": "text",
-                  "value": " "
-                }
-              ]
-            }
-          ]
-        },
         {
           "type": "listItem",
           "children": [
@@ -158,6 +136,28 @@
             }
           ]
         },
+        {
+          "type": "listItem",
+          "children": [
+            {
+              "type": "paragraph",
+              "children": [
+                {
+                  "type": "inlineCode",
+                  "value": "a"
+                },
+                {
+                  "type": "text",
+                  "value": " "
+                },
+                {
+                  "type": "text",
+                  "value": " "
+                }
+              ]
+            }
+          ]
+        },
         {
           "type": "listItem",
           "children": [

Diff for: test/fixture/sync/lots-of-options.input.js

@@ -0,0 +1,23 @@
+/**
+ * Global spectra deconvolution
+ * @param {Array<Number>} x - Independent variable
+ * @param {Array<Number>} yIn - Dependent variable
+ * @param {Object} [options] - Options object
+ * @param {Object} [options.sgOptions] - Options object for Savitzky-Golay filter. See https://github.com/mljs/savitzky-golay-generalized#options
+ * @param {Number} [options.minMaxRatio = 0.00025] - Threshold to determine if a given peak should be considered as a noise
+ * @param {Number} [options.broadRatio = 0.00] - If `broadRatio` is higher than 0, then all the peaks which second derivative
+ * smaller than `broadRatio * maxAbsSecondDerivative` will be marked with the soft mask equal to true.
+ * @param {Number} [options.noiseLevel = 3] - Noise threshold in spectrum units
+ * @param {Boolean} [options.maxCriteria = true] - Peaks are local maximum(true) or minimum(false)
+ * @param {Boolean} [options.smoothY = true] - Select the peak intensities from a smoothed version of the independent variables
+ * @param {Boolean} [options.realTopDetection = false] - Use a quadratic optimizations with the peak and its 3 closest neighbors
+ * to determine the true x,y values of the peak?
+ * @param {Number} [options.heightFactor = 0] - Factor to multiply the calculated height (usually 2)
+ * @param {Boolean} [options.boundaries = false] - Return also the inflection points of the peaks
+ * @param {Number} [options.derivativeThreshold = 0] - Filters based on the amplitude of the first derivative
+ * @return {Array<Object>}
+ */
+function gsd(x, yIn, options) {
+}
+
+module.exports = gsd;