Fix parameter sorting, nest properties in Markdown

tmcw · tmcw · commit b173cf14a55d · 2015-10-05T15:02:33.000-04:00
diff --git a/lib/infer/params.js b/lib/infer/params.js
@@ -21,7 +21,8 @@ module.exports = function inferParams(comment) {
         return memo;
       }, {});
 
-      var paramOrder = [];
+      var paramOrder = {};
+      var i = 0;
 
       path.value.params.forEach(function (param) {
         if (existingParams[param.name] === undefined) {
@@ -34,15 +35,15 @@ module.exports = function inferParams(comment) {
             lineNumber: param.loc.start.line
           });
         }
-        paramOrder.push(param.name);
+        paramOrder[param.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.indexOf(a.name) - paramOrder.indexOf(b.name);
+          return paramOrder[a.name] - paramOrder[b.name];
         });
       }
 
diff --git a/lib/output/markdown_ast.js b/lib/output/markdown_ast.js
@@ -9,25 +9,31 @@ function identity(x) {
 
 function commentsToAST(comments, opts, callback) {
   function generate(depth, comment) {
+
+    function paramList(params) {
+      return u('list', { ordered: false }, params.map(function (param) {
+        return u('listItem', [
+          u('paragraph', [
+            u('inlineCode', param.name),
+            u('text', ' '),
+            !!param.type && u('strong', [u('text', formatType(param.type))]),
+            u('text', ' '),
+            mdast.parse(formatInlineTags(param.description)),
+            !!param.default && u('root', [
+              u('text', ' (optional, default '),
+              u('text', param.default, 'inlineCode'),
+              u('text', ')')
+            ]),
+            param.properties && paramList(param.properties)
+          ].filter(identity))
+        ]);
+      }));
+    }
+
     function paramSection(comment) {
       return !!comment.params && u('root', [
         u('strong', [u('text', 'Parameters')]),
-        u('list', { ordered: false }, comment.params.map(function (param) {
-          return u('listItem', [
-            u('paragraph', [
-              u('inlineCode', param.name),
-              u('text', ' '),
-              !!param.type && u('strong', [u('text', formatType(param.type))]),
-              u('text', ' '),
-              mdast.parse(formatInlineTags(param.description)),
-              !!param.default && u('root', [
-                u('text', ' (optional, default '),
-                u('text', param.default, 'inlineCode'),
-                u('text', ')')
-              ])
-            ].filter(identity))
-          ]);
-        }))
+        paramList(comment.params)
       ]);
     }
 
@@ -38,13 +44,13 @@ function commentsToAST(comments, opts, callback) {
           comment.properties.map(function (property) {
             return u('listItem', [
               u('paragraph', [
-                u('inlineCode', property.title),
+                u('inlineCode', property.name),
                 u('text', ' '),
                 u('text', [u('text', formatType(property.type))]),
                 u('text', ' '),
                 mdast.parse(formatInlineTags(property.description))
               ])
-            ])
+            ].filter(identity))
           }))
       ]);
     }
diff --git a/test/fixture/class.output.custom.md b/test/fixture/class.output.custom.md
@@ -5,7 +5,7 @@ This is my class, a demo thing.
 
 **Properties**
 
--   `property`  how many things it contains
+-   `howMany`  how many things it contains
 
 
 
diff --git a/test/fixture/class.output.md b/test/fixture/class.output.md
@@ -5,7 +5,7 @@ This is my class, a demo thing.
 
 **Properties**
 
--   `property`  how many things it contains
+-   `howMany`  how many things it contains
 
 
 
diff --git a/test/fixture/class.output.md.json b/test/fixture/class.output.md.json
@@ -84,7 +84,7 @@
                       "children": [
                         {
                           "type": "inlineCode",
-                          "value": "property"
+                          "value": "howMany"
                         },
                         {
                           "type": "text",
diff --git a/test/fixture/event.output.custom.md b/test/fixture/event.output.custom.md
@@ -5,9 +5,9 @@ Mouse event
 
 **Properties**
 
--   `property`  the pixel location of the event
+-   `point`  the pixel location of the event
 
--   `property`  the original DOM event
+-   `originalEvent`  the original DOM event
 
 
 
diff --git a/test/fixture/event.output.md b/test/fixture/event.output.md
@@ -5,9 +5,9 @@ Mouse event
 
 **Properties**
 
--   `property`  the pixel location of the event
+-   `point`  the pixel location of the event
 
--   `property`  the original DOM event
+-   `originalEvent`  the original DOM event
 
 
 
diff --git a/test/fixture/event.output.md.json b/test/fixture/event.output.md.json
@@ -84,7 +84,7 @@
                       "children": [
                         {
                           "type": "inlineCode",
-                          "value": "property"
+                          "value": "point"
                         },
                         {
                           "type": "text",
@@ -161,7 +161,7 @@
                       "children": [
                         {
                           "type": "inlineCode",
-                          "value": "property"
+                          "value": "originalEvent"
                         },
                         {
                           "type": "text",
diff --git a/test/fixture/html/nested.output.files b/test/fixture/html/nested.output.files
@@ -2041,7 +2041,7 @@ the referenced class type</p>
         <div class='collapsible' id='klass/withoptions'>
           <a href='#klass/withoptions'>
             <code>
-              #withOptions<span class='gray'>(options.foo, options.bar, options)</span>
+              #withOptions<span class='gray'>(options)</span>
             </code>
             <span class='force-inline'>
               <p>A function with an options parameter</p>
@@ -2051,30 +2051,24 @@ the referenced class type</p>
           <div class='collapser border px2'>
             <section class='py2 clearfix'>
               <h2 id='klass/withoptions' class='mt0'>
-                withOptions<span class='gray'>(options.foo, options.bar, options)</span>
+                withOptions<span class='gray'>(options)</span>
               </h2>
               <p>A function with an options parameter</p>
             
                 <h4>Parameters</h4>
                 <ul class='suppress-p-margin'>
-                    <li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code> <strong>options.foo</strong>
-                      :
-                      <span class='force-inline'>
-                        
-                      </span>
-                    </li>
-                    <li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></code> <strong>options.bar</strong>
-                      :
-                      <span class='force-inline'>
-                        
-                      </span>
-                    </li>
                     <li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object</a></code> <strong>options</strong>
                       :
                       <span class='force-inline'>
                         
                       </span>
                     </li>
+                      <ul>
+                          <li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></code> options.foo
+                            </li>
+                          <li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></code> options.bar
+                            </li>
+                      </ul>
                 </ul>
             </section>
           </div>
diff --git a/test/fixture/nested_properties.output.custom.md b/test/fixture/nested_properties.output.custom.md
@@ -6,6 +6,7 @@
 **Parameters**
 
 -   `options` **Object** some options
+    -   `options.much` **number** how much
 
 -   `bar` **number** something else
 
diff --git a/test/fixture/nested_properties.output.md b/test/fixture/nested_properties.output.md
@@ -6,6 +6,7 @@
 **Parameters**
 
 -   `options` **Object** some options
+    -   `options.much` **number** how much
 
 -   `bar` **number** something else
 
diff --git a/test/fixture/nested_properties.output.md.json b/test/fixture/nested_properties.output.md.json
@@ -116,6 +116,89 @@
                               "column": 13
                             }
                           }
+                        },
+                        {
+                          "ordered": false,
+                          "type": "list",
+                          "children": [
+                            {
+                              "type": "listItem",
+                              "children": [
+                                {
+                                  "type": "paragraph",
+                                  "children": [
+                                    {
+                                      "type": "inlineCode",
+                                      "value": "options.much"
+                                    },
+                                    {
+                                      "type": "text",
+                                      "value": " "
+                                    },
+                                    {
+                                      "type": "strong",
+                                      "children": [
+                                        {
+                                          "type": "text",
+                                          "value": "number"
+                                        }
+                                      ]
+                                    },
+                                    {
+                                      "type": "text",
+                                      "value": " "
+                                    },
+                                    {
+                                      "type": "root",
+                                      "children": [
+                                        {
+                                          "type": "paragraph",
+                                          "children": [
+                                            {
+                                              "type": "text",
+                                              "value": "how much",
+                                              "position": {
+                                                "start": {
+                                                  "line": 1,
+                                                  "column": 1
+                                                },
+                                                "end": {
+                                                  "line": 1,
+                                                  "column": 9
+                                                },
+                                                "indent": []
+                                              }
+                                            }
+                                          ],
+                                          "position": {
+                                            "start": {
+                                              "line": 1,
+                                              "column": 1
+                                            },
+                                            "end": {
+                                              "line": 1,
+                                              "column": 9
+                                            },
+                                            "indent": []
+                                          }
+                                        }
+                                      ],
+                                      "position": {
+                                        "start": {
+                                          "line": 1,
+                                          "column": 1
+                                        },
+                                        "end": {
+                                          "line": 1,
+                                          "column": 9
+                                        }
+                                      }
+                                    }
+                                  ]
+                                }
+                              ]
+                            }
+                          ]
                         }
                       ]
                     }
diff --git a/test/fixture/param_nest.input.js b/test/fixture/param_nest.input.js
@@ -0,0 +1,13 @@
+/**
+ * Create a GeoJSON data source instance given an options object
+ * @class GeoJSONSource
+ * @param {Object} [options] optional options
+ * @param {Object|string} options.data A GeoJSON data object or URL to it.
+ * The latter is preferable in case of large GeoJSON files.
+ * @param {number} [options.maxzoom=14] Maximum zoom to preserve detail at.
+ * @param {number} [options.buffer] Tile buffer on each side.
+ * @param {number} [options.tolerance] Simplification tolerance (higher means simpler).
+ */
+function GeoJSONSource(options) {
+  this.options = options;
+}
diff --git a/test/fixture/param_nest.output.custom.md b/test/fixture/param_nest.output.custom.md
@@ -0,0 +1,24 @@
+# GeoJSONSource
+
+Create a GeoJSON data source instance given an options object
+
+
+**Parameters**
+
+-   `options` **[Object]** optional options
+    -   `options.data` **Object or string** A GeoJSON data object or URL to it.
+        The latter is preferable in case of large GeoJSON files.
+
+    -   `options.maxzoom` **[number]** Maximum zoom to preserve detail at.
+         (optional, default 
+
+        inlineCode
+
+        )
+
+    -   `options.buffer` **[number]** Tile buffer on each side.
+
+    -   `options.tolerance` **[number]** Simplification tolerance (higher means simpler).
+
+
+
diff --git a/test/fixture/param_nest.output.json b/test/fixture/param_nest.output.json
diff --git a/test/fixture/param_nest.output.md b/test/fixture/param_nest.output.md
diff --git a/test/fixture/param_nest.output.md.json b/test/fixture/param_nest.output.md.json
diff --git a/test/fixture/typedef.output.custom.md b/test/fixture/typedef.output.custom.md
diff --git a/test/fixture/typedef.output.md b/test/fixture/typedef.output.md
diff --git a/test/fixture/typedef.output.md.json b/test/fixture/typedef.output.md.json

Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@ This is my class, a demo thing.`
`5`	`5`
`6`	`6`	`Properties`
`7`	`7`
`8`		-- `property` how many things it contains
	`8`	+- `howMany` how many things it contains
`9`	`9`
`10`	`10`
`11`	`11`
Original file line number	Diff line number	Diff line change
`@@ -84,7 +84,7 @@`
`84`	`84`	`"children": [`
`85`	`85`	`{`
`86`	`86`	`"type": "inlineCode",`
`87`		`- "value": "property"`
	`87`	`+ "value": "howMany"`
`88`	`88`	`},`
`89`	`89`	`{`
`90`	`90`	`"type": "text",`