diff --git a/lib/parse.js b/lib/parse.js index cf9fa52..e2e2b3f 100644 --- a/lib/parse.js +++ b/lib/parse.js @@ -154,6 +154,10 @@ var flatteners = { param.type = tag.type; } + if (tag.default) { + param.default = tag.default; + } + result.params.push(param); }, 'private': function (result) { diff --git a/lib/sort.js b/lib/sort.js index 46a77ee..e1137d9 100644 --- a/lib/sort.js +++ b/lib/sort.js @@ -11,50 +11,49 @@ function parseMarkdown(string) { * Sort two documentation objects, given an optional order object. Returns * a numeric sorting value that is compatible with stream-sort. * - * @param {Object} a documentation object - * @param {Object} b documentation object + * @param {Array} comments all comments + * @param {Object} options options from documentation.yml * @return {number} sorting value * @private */ module.exports = function sortDocs(comments, options) { - if (!options.toc) { + if (!options || !options.toc) { return comments.sort(function (a, b) { return a.context.sortKey.localeCompare(b.context.sortKey); }); - } else { - var indexes = options.toc.reduce(function (memo, val, i) { - if (typeof val === 'object' && val.name) { - val.kind = 'note'; - memo[val.name] = i; - } else { - memo[val] = i; - } - return memo; - }, {}); - var fixed = options.toc.filter(function (val) { - return typeof val === 'object' && val.name; - }).map(function (val) { - if (val.description) { - val.description = parseMarkdown(val.description); - } - return val; - }); - var unfixed = []; - comments.forEach(function (comment) { - if (!comment.memberof && indexes[comment.name] !== undefined) { - fixed.push(comment); - } else { - unfixed.push(comment); - } - }); - fixed.sort(function (a, b) { - if (indexes[a.name] !== undefined && indexes[b.name] !== undefined) { - return indexes[a.name] - indexes[b.name]; - } - }); - unfixed.sort(function (a, b) { - return a.context.sortKey.localeCompare(b.context.sortKey); - }); - return fixed.concat(unfixed); } + var indexes = options.toc.reduce(function (memo, val, i) { + if (typeof val === 'object' && val.name) { + val.kind = 'note'; + memo[val.name] = i; + } else { + memo[val] = i; + } + return memo; + }, {}); + var fixed = options.toc.filter(function (val) { + return typeof val === 'object' && val.name; + }).map(function (val) { + if (val.description) { + val.description = parseMarkdown(val.description); + } + return val; + }); + var unfixed = []; + comments.forEach(function (comment) { + if (!comment.memberof && indexes[comment.name] !== undefined) { + fixed.push(comment); + } else { + unfixed.push(comment); + } + }); + fixed.sort(function (a, b) { + if (indexes[a.name] !== undefined && indexes[b.name] !== undefined) { + return indexes[a.name] - indexes[b.name]; + } + }); + unfixed.sort(function (a, b) { + return a.context.sortKey.localeCompare(b.context.sortKey); + }); + return fixed.concat(unfixed); }; diff --git a/test/fixture/html/nested.output.files b/test/fixture/html/nested.output.files index 16bf134..cb20579 100644 --- a/test/fixture/html/nested.output.files +++ b/test/fixture/html/nested.output.files @@ -26,10 +26,7 @@
  • + class=" toggle-sibling"> Klass ▸ @@ -103,8 +100,7 @@
  • + class=""> bar @@ -114,8 +110,7 @@
  • + class=""> bar @@ -125,8 +120,7 @@
  • + class=""> bar @@ -136,10 +130,7 @@
  • + class=" toggle-sibling"> Foo ▸ @@ -170,7 +161,8 @@
    -
    + +

    Klass @@ -401,7 +393,9 @@ the referenced class type

    • -
  • size ([number]): size +
  • size ([number] + (default 0) + ): size
    • @@ -758,8 +752,10 @@ k.isArrayOfBuffers(); + -
    + +

    bar @@ -806,8 +802,10 @@ like a klass

    + -
    + +

    bar @@ -861,8 +859,10 @@ like a klass

    + -
    + +

    bar @@ -909,8 +909,10 @@ like a klass. This needs a number inp

    + -
    + +

    Foo @@ -1003,6 +1005,7 @@ like a klass. This needs a number inp

    +
    diff --git a/test/fixture/nest_params.input.js b/test/fixture/nest_params.input.js index 9e31827..497c1fd 100644 --- a/test/fixture/nest_params.input.js +++ b/test/fixture/nest_params.input.js @@ -2,8 +2,9 @@ * @param {Object[]} employees - The employees who are responsible for the project. * @param {string} employees[].name - The name of an employee. * @param {string} employees[].department - The employee's department. + * @param {string} [type=minion] - The employee's type. */ -function foo(employee) { +function foo(employee, type) { } /** diff --git a/test/fixture/nest_params.output.json b/test/fixture/nest_params.output.json index a30beac..97bd9f3 100644 --- a/test/fixture/nest_params.output.json +++ b/test/fixture/nest_params.output.json @@ -40,6 +40,20 @@ "name": "string" }, "name": "employees[].department" + }, + { + "title": "param", + "description": "The employee's type.", + "lineNumber": 4, + "type": { + "type": "OptionalType", + "expression": { + "type": "NameExpression", + "name": "string" + } + }, + "name": "type", + "default": "minion" } ], "loc": { @@ -48,22 +62,22 @@ "column": 0 }, "end": { - "line": 5, + "line": 6, "column": 3 } }, "context": { "loc": { "start": { - "line": 6, + "line": 7, "column": 0 }, "end": { - "line": 7, + "line": 8, "column": 1 } }, - "code": "/**\n * @param {Object[]} employees - The employees who are responsible for the project.\n * @param {string} employees[].name - The name of an employee.\n * @param {string} employees[].department - The employee's department.\n */\nfunction foo(employee) {\n}\n\n/**\n * @name foo\n * @param {Object} options some options\n * @param {number} options.much how much\n * @param {number} bar something else\n * @property {Object} theTime the current time\n * @property {number} theTime.hours\n * @property {number} theTime.minutes\n * @property {number} theTime.seconds\n * @returns {Object} foo something else\n */\n" + "code": "/**\n * @param {Object[]} employees - The employees who are responsible for the project.\n * @param {string} employees[].name - The name of an employee.\n * @param {string} employees[].department - The employee's department.\n * @param {string} [type=minion] - The employee's type.\n */\nfunction foo(employee, type) {\n}\n\n/**\n * @name foo\n * @param {Object} options some options\n * @param {number} options.much how much\n * @param {number} bar something else\n * @property {Object} theTime the current time\n * @property {number} theTime.hours\n * @property {number} theTime.minutes\n * @property {number} theTime.seconds\n * @returns {Object} foo something else\n */\n" }, "errors": [], "params": [ @@ -261,7 +275,71 @@ { "title": "param", "name": "employee", - "lineNumber": 6 + "lineNumber": 7 + }, + { + "name": "type", + "lineNumber": 4, + "description": { + "type": "root", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "The employee's type.", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 21, + "offset": 20 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 21, + "offset": 20 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 21, + "offset": 20 + } + } + }, + "type": { + "type": "OptionalType", + "expression": { + "type": "NameExpression", + "name": "string" + } + }, + "default": "minion" } ], "name": "foo", @@ -369,22 +447,22 @@ ], "loc": { "start": { - "line": 9, + "line": 10, "column": 0 }, "end": { - "line": 19, + "line": 20, "column": 3 } }, "context": { "loc": { "start": { - "line": 6, + "line": 7, "column": 0 }, "end": { - "line": 7, + "line": 8, "column": 1 } } diff --git a/test/fixture/nest_params.output.md b/test/fixture/nest_params.output.md index e573e9b..ddfaec3 100644 --- a/test/fixture/nest_params.output.md +++ b/test/fixture/nest_params.output.md @@ -6,6 +6,7 @@ - `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 --git a/test/fixture/nest_params.output.md.json b/test/fixture/nest_params.output.md.json index 3b76fb9..f018a83 100644 --- a/test/fixture/nest_params.output.md.json +++ b/test/fixture/nest_params.output.md.json @@ -289,6 +289,104 @@ ] } ] + }, + { + "type": "listItem", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "inlineCode", + "value": "type" + }, + { + "type": "text", + "value": " " + }, + { + "type": "strong", + "children": [ + { + "type": "text", + "value": "[" + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "type": "link", + "children": [ + { + "type": "text", + "value": "string" + } + ] + }, + { + "type": "text", + "value": "]" + } + ] + }, + { + "type": "text", + "value": " " + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "The employee's type.", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 21, + "offset": 20 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 21, + "offset": 20 + }, + "indent": [] + } + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": " (optional, default " + }, + { + "type": "inlineCode", + "value": "minion" + }, + { + "type": "text", + "value": ")" + } + ] + } + ] + } + ] } ] }, diff --git a/test/fixture/params.output.json b/test/fixture/params.output.json index a8ff1f7..97db036 100644 --- a/test/fixture/params.output.json +++ b/test/fixture/params.output.json @@ -1064,7 +1064,8 @@ "type": "NameExpression", "name": "number" } - } + }, + "default": "8" }, { "name": "third", @@ -1191,7 +1192,8 @@ "type": "NameExpression", "name": "Array" } - } + }, + "default": "[1]" } ], "examples": [ @@ -1604,7 +1606,8 @@ "type": "NameExpression", "name": "number" } - } + }, + "default": "14" }, { "name": "options.buffer", diff --git a/test/fixture/params.output.md b/test/fixture/params.output.md index 65c3097..5d071b1 100644 --- a/test/fixture/params.output.md +++ b/test/fixture/params.output.md @@ -51,9 +51,9 @@ This tests our support of optional parameters **Parameters** - `address` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** An IPv6 address string -- `groups` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** How many octets to parse +- `groups` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** How many octets to parse (optional, default `8`) - `third` **?[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** A third argument -- `foo` **\[[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)]** to properly be parsed +- `foo` **\[[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)]** to properly be parsed (optional, default `[1]`) **Examples** @@ -72,7 +72,7 @@ This tests our support of nested parameters - `options` **\[[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)]** optional options - `options.data` **([Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String))** A GeoJSON data object or URL to it. The latter is preferable in case of large GeoJSON files. - - `options.maxzoom` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** Maximum zoom to preserve detail at. + - `options.maxzoom` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** Maximum zoom to preserve detail at. (optional, default `14`) - `options.buffer` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** Tile buffer on each side. - `options.tolerance` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** Simplification tolerance (higher means simpler). diff --git a/test/fixture/params.output.md.json b/test/fixture/params.output.md.json index dabe479..d659e86 100644 --- a/test/fixture/params.output.md.json +++ b/test/fixture/params.output.md.json @@ -1017,6 +1017,23 @@ }, "indent": [] } + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": " (optional, default " + }, + { + "type": "inlineCode", + "value": "8" + }, + { + "type": "text", + "value": ")" + } + ] } ] } @@ -1175,6 +1192,23 @@ }, "indent": [] } + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": " (optional, default " + }, + { + "type": "inlineCode", + "value": "[1]" + }, + { + "type": "text", + "value": ")" + } + ] } ] } @@ -1548,6 +1582,23 @@ }, "indent": [] } + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": " (optional, default " + }, + { + "type": "inlineCode", + "value": "14" + }, + { + "type": "text", + "value": ")" + } + ] } ] } diff --git a/test/lib/sort.js b/test/lib/sort.js index 76f6358..fccb1b8 100644 --- a/test/lib/sort.js +++ b/test/lib/sort.js @@ -8,15 +8,15 @@ test('sort stream alphanumeric', function (t) { var carrot = { context: { sortKey: 'b' }, name: 'carrot' }; var banana = { context: { sortKey: 'c' }, name: 'bananas' }; - t.deepEqual([ + t.deepEqual(sort([ apples, carrot, banana - ].sort(sort), [ + ]), [ apples, carrot, banana ], 'sort stream alphanumeric'); - t.deepEqual([ + t.deepEqual(sort([ carrot, apples, banana - ].sort(sort), [ + ]), [ apples, carrot, banana ], 'sort stream alphanumeric');