From 33552c6e8a8b9308e066dd871911691578567dc1 Mon Sep 17 00:00:00 2001 From: Tom MacWright Date: Mon, 9 Nov 2015 12:51:15 -0500 Subject: [PATCH 1/2] Fix type merging. Fixes #233 Some params cannot be identified with only param.name. This changes the algorithm to transform parameters into doc objects first, and then using the value of doc.name, which is defined even for parameters with default values. --- lib/infer/params.js | 37 ++-- test/fixture/partial-default.input.js | 8 + test/fixture/partial-default.output.custom.md | 9 + test/fixture/partial-default.output.json | 82 ++++++++ test/fixture/partial-default.output.md | 9 + test/fixture/partial-default.output.md.json | 176 ++++++++++++++++++ 6 files changed, 303 insertions(+), 18 deletions(-) create mode 100644 test/fixture/partial-default.input.js create mode 100644 test/fixture/partial-default.output.custom.md create mode 100644 test/fixture/partial-default.output.json create mode 100644 test/fixture/partial-default.output.md create mode 100644 test/fixture/partial-default.output.md.json diff --git a/lib/infer/params.js b/lib/infer/params.js index b8efa193c..665e8afc7 100644 --- a/lib/infer/params.js +++ b/lib/infer/params.js @@ -119,25 +119,26 @@ module.exports = function () { var paramOrder = {}; var i = 0; - path.value.params.forEach(function (param, j) { - if (existingParams[param.name] === undefined) { - // This type is not explicitly documented - if (!comment.params) { - comment.params = []; + path.value.params + .map(paramToDoc) + .forEach(function (doc) { + if (existingParams[doc.name] === undefined) { + // This type is not explicitly documented + if (!comment.params) { + comment.params = []; + } + + comment.params = comment.params.concat(doc); + } else if (!existingParams[doc.name].type) { + // This param has a description, but potentially it can + // be have an inferred type. Infer its type without + // dropping the description. + if (doc.type) { + existingParams[doc.name].type = doc.type; + } } - - comment.params = comment.params.concat(paramToDoc(param, j)); - } else if (!existingParams[param.name].type) { - // This param has a description, but potentially it can - // be have an inferred type. Infer its type without - // dropping the description. - var doc = paramToDoc(param, j); - if (doc.type) { - existingParams[param.name].type = doc.type; - } - } - paramOrder[param.name] = i++; - }); + paramOrder[doc.name] = i++; + }); // Ensure that if params are specified partially or in // the wrong order, they'll be output in the order diff --git a/test/fixture/partial-default.input.js b/test/fixture/partial-default.input.js new file mode 100644 index 000000000..2b34f98fe --- /dev/null +++ b/test/fixture/partial-default.input.js @@ -0,0 +1,8 @@ +/** + * Number + * + * @param {number} x an argument + * + * @returns {number} some + */ +export const myfunc = (x = 123) => x; diff --git a/test/fixture/partial-default.output.custom.md b/test/fixture/partial-default.output.custom.md new file mode 100644 index 000000000..82e7dd6b6 --- /dev/null +++ b/test/fixture/partial-default.output.custom.md @@ -0,0 +1,9 @@ +# myfunc + +Number + +**Parameters** + +- `x` **number** an argument + +Returns **number** some diff --git a/test/fixture/partial-default.output.json b/test/fixture/partial-default.output.json new file mode 100644 index 000000000..e146f5176 --- /dev/null +++ b/test/fixture/partial-default.output.json @@ -0,0 +1,82 @@ +[ + { + "description": "Number", + "tags": [ + { + "title": "param", + "description": "an argument", + "lineNumber": 3, + "type": { + "type": "NameExpression", + "name": "number" + }, + "name": "x" + }, + { + "title": "returns", + "description": "some", + "lineNumber": 5, + "type": { + "type": "NameExpression", + "name": "number" + } + } + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 7, + "column": 3 + } + }, + "context": { + "loc": { + "start": { + "line": 8, + "column": 0 + }, + "end": { + "line": 8, + "column": 37 + } + }, + "code": "/**\n * Number\n *\n * @param {number} x an argument\n *\n * @returns {number} some\n */\nexport const myfunc = (x = 123) => x;\n" + }, + "errors": [], + "params": [ + { + "title": "param", + "description": "an argument", + "lineNumber": 3, + "type": { + "type": "NameExpression", + "name": "number" + }, + "name": "x" + } + ], + "returns": [ + { + "title": "returns", + "description": "some", + "lineNumber": 5, + "type": { + "type": "NameExpression", + "name": "number" + } + } + ], + "name": "myfunc", + "kind": "constant", + "members": { + "instance": [], + "static": [] + }, + "path": [ + "myfunc" + ] + } +] \ No newline at end of file diff --git a/test/fixture/partial-default.output.md b/test/fixture/partial-default.output.md new file mode 100644 index 000000000..82e7dd6b6 --- /dev/null +++ b/test/fixture/partial-default.output.md @@ -0,0 +1,9 @@ +# myfunc + +Number + +**Parameters** + +- `x` **number** an argument + +Returns **number** some diff --git a/test/fixture/partial-default.output.md.json b/test/fixture/partial-default.output.md.json new file mode 100644 index 000000000..9fe928b7c --- /dev/null +++ b/test/fixture/partial-default.output.md.json @@ -0,0 +1,176 @@ +{ + "type": "root", + "children": [ + { + "depth": 1, + "type": "heading", + "children": [ + { + "type": "text", + "value": "myfunc" + } + ] + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Number", + "position": { + "start": { + "line": 1, + "column": 1 + }, + "end": { + "line": 1, + "column": 7 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1 + }, + "end": { + "line": 1, + "column": 7 + }, + "indent": [] + } + }, + { + "type": "strong", + "children": [ + { + "type": "text", + "value": "Parameters" + } + ] + }, + { + "ordered": false, + "type": "list", + "children": [ + { + "type": "listItem", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "inlineCode", + "value": "x" + }, + { + "type": "text", + "value": " " + }, + { + "type": "strong", + "children": [ + { + "type": "text", + "value": "number" + } + ] + }, + { + "type": "text", + "value": " " + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "an argument", + "position": { + "start": { + "line": 1, + "column": 1 + }, + "end": { + "line": 1, + "column": 12 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1 + }, + "end": { + "line": 1, + "column": 12 + }, + "indent": [] + } + } + ] + } + ] + } + ] + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Returns " + }, + { + "type": "strong", + "children": [ + { + "type": "text", + "value": "number" + } + ] + }, + { + "type": "text", + "value": " " + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "some", + "position": { + "start": { + "line": 1, + "column": 1 + }, + "end": { + "line": 1, + "column": 5 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1 + }, + "end": { + "line": 1, + "column": 5 + }, + "indent": [] + } + } + ] + } + ] +} \ No newline at end of file From 463bb4e62f5b155ef0f3532af5e4d010a0a2f021 Mon Sep 17 00:00:00 2001 From: Tom MacWright Date: Mon, 9 Nov 2015 13:08:56 -0500 Subject: [PATCH 2/2] Improve test coverage --- lib/args.js | 10 ++-------- lib/output/json.js | 10 +++------- test/bin.js | 7 +++++++ 3 files changed, 12 insertions(+), 15 deletions(-) diff --git a/lib/args.js b/lib/args.js index 93dad204e..8199d9104 100644 --- a/lib/args.js +++ b/lib/args.js @@ -1,7 +1,6 @@ -var documentation = require('../'), - path = require('path'), +var path = require('path'), + yargs = require('yargs'), loadConfig = require('../lib/load_config.js'); -var yargs = require('yargs') function parse(args) { // reset() needs to be called at parse time because the yargs module uses an @@ -98,11 +97,6 @@ module.exports = function (args) { } } - if (!documentation.formats[argv.f]) { - yargs.showHelp(); - throw new Error('Formatter not found'); - } - if (argv.f === 'html' && argv.o === 'stdout') { yargs.showHelp(); throw new Error('The HTML output mode requires a destination directory set with -o'); diff --git a/lib/output/json.js b/lib/output/json.js index 37f90c623..760893051 100644 --- a/lib/output/json.js +++ b/lib/output/json.js @@ -13,13 +13,9 @@ var walk = require('../walk'); */ module.exports = function (comments, opts, callback) { - opts = opts || {}; - - if (!opts.preserveErrors) { - walk(comments, function (comment) { - delete comment.errors; - }); - } + walk(comments, function (comment) { + delete comment.errors; + }); return callback(null, JSON.stringify(comments, null, 2)); }; diff --git a/test/bin.js b/test/bin.js index 1873057b3..b6ae2550d 100644 --- a/test/bin.js +++ b/test/bin.js @@ -94,6 +94,13 @@ test('bad -f option', function (t) { }); }, options); +test('--version', function (t) { + documentation(['--version'], {}, function (err, output) { + t.ok(output, 'outputs version'); + t.end(); + }, false); +}, options); + test('html with no destination', function (t) { documentation(['-f html fixture/internal.input.js'], function (err) { t.ok(err.toString()