diff --git a/bin/documentation.js b/bin/documentation.js index 454df2c..cb67d90 100755 --- a/bin/documentation.js +++ b/bin/documentation.js @@ -17,10 +17,7 @@ var documentation = require('../'), docset = require('../streams/output/docset.js'), lint = require('../streams/lint.js'), - github = require('../streams/github.js'), - normalize = require('../streams/normalize.js'), - flatten = require('../streams/flatten.js'), - filterAccess = require('../streams/filter_access.js'); + github = require('../streams/github.js'); var yargs = require('yargs') .usage('Usage: $0 [options]') @@ -108,12 +105,11 @@ if (argv.f === 'html' && argv.o === 'stdout') { throw new Error('The HTML output mode requires a destination directory set with -o'); } -var docStream = documentation(inputs) - .pipe(normalize()) +var docStream = documentation(inputs, { + private: argv.private + }) .pipe(argv.lint ? lint() : new PassThrough({ objectMode: true })) .pipe(argv.g ? github() : new PassThrough({ objectMode: true })) - .pipe(flatten()) - .pipe(filterAccess(argv.private ? [] : undefined)) .pipe(formatter); if (argv.o !== 'stdout') { diff --git a/index.js b/index.js index 0326bdc..46fb63b 100644 --- a/index.js +++ b/index.js @@ -3,7 +3,10 @@ var mdeps = require('module-deps'), path = require('path'), PassThrough = require('stream').PassThrough, + flatten = require('./streams/flatten.js'), sort = require('./streams/sort'), + normalize = require('./streams/normalize.js'), + filterAccess = require('./streams/filter_access.js'), parse = require('./streams/parse'), inferName = require('./streams/infer_name'), inferKind = require('./streams/infer_kind'), @@ -20,9 +23,12 @@ var externalModuleRegexp = process.platform === 'win32' ? * * @name documentation * @param {Array|String} indexes files to process + * @param {Object} options options * @return {Object} stream of output */ -module.exports = function (indexes) { +module.exports = function (indexes, options) { + options = options || {}; + var md = mdeps({ filter: function (id) { return externalModuleRegexp.test(id); @@ -53,5 +59,8 @@ module.exports = function (indexes) { .pipe(sort()) .pipe(deferErrors(inferKind())) .pipe(deferErrors(inferMembership())) + .pipe(normalize()) + .pipe(flatten()) + .pipe(filterAccess(options.private ? [] : undefined)) .pipe(end); }; diff --git a/streams/filter_access.js b/streams/filter_access.js index 4f773a2..ab778a4 100644 --- a/streams/filter_access.js +++ b/streams/filter_access.js @@ -7,9 +7,9 @@ var through = require('through'); * users to write documentation for non-public members by using the * `@private` tag. * + * @name access * @public * @param {Array} [levels=[private]] excluded access levels. - * @name access * @return {stream.Transform} */ module.exports = function (levels) { diff --git a/streams/output/html.js b/streams/output/html.js index 9a64ceb..90ea311 100644 --- a/streams/output/html.js +++ b/streams/output/html.js @@ -10,6 +10,17 @@ var through = require('through'), Handlebars = require('handlebars'), extend = require('extend'); +/** + * Make slugg a unary so we can use it in functions + * + * @private + * @param {string} input text + * @returns {string} output + */ +function slug(p) { + return slugg(p); +} + var BUILTINS = [ 'Array', 'ArrayBuffer', @@ -171,7 +182,7 @@ module.exports = function (opts) { } var paths = comments.map(function (comment) { - return comment.path.map(slugg).join('/'); + return comment.path.map(slug).join('/'); }).filter(function (path) { return path; }); @@ -181,7 +192,7 @@ module.exports = function (opts) { }); Handlebars.registerHelper('permalink', function () { - return this.path.map(slugg).join('/'); + return this.path.map(slug).join('/'); }); /** @@ -190,8 +201,8 @@ module.exports = function (opts) { * @returns {string} potentially linked HTML */ function autolink(text) { - if (paths.indexOf(slugg(text)) !== -1) { - return '' + text + ''; + if (paths.indexOf(slug(text)) !== -1) { + return '' + text + ''; } else if (BUILTINS[text.toLowerCase()]) { return '' + text + ''; } diff --git a/test/fixture/_multi-file-input.json b/test/fixture/_multi-file-input.json index 1ea36f6..613d950 100644 --- a/test/fixture/_multi-file-input.json +++ b/test/fixture/_multi-file-input.json @@ -35,7 +35,20 @@ }, "file": "fixture/simple.input.js", "code": "module.exports = function () {\n // this returns 1\n return 1;\n};" - } + }, + "returns": [ + { + "title": "returns", + "description": "numberone", + "type": { + "type": "NameExpression", + "name": "Number" + } + } + ], + "name": "exports", + "memberof": "module", + "scope": "static" }, { "description": "This function returns the number plus two.", @@ -79,6 +92,31 @@ }, "file": "fixture/simple-two.input.js", "code": "function returnTwo(a) {\n // this returns a + 2\n return a + 2;\n}" - } + }, + "params": [ + { + "title": "param", + "description": "the number", + "type": { + "type": "NameExpression", + "name": "Number" + }, + "name": "a" + } + ], + "returns": [ + { + "title": "returns", + "description": "numbertwo", + "type": { + "type": "NameExpression", + "name": "Number" + } + } + ], + "examples": [ + "var result = returnTwo(4);\n// result is 6" + ], + "name": "returnTwo" } ] \ No newline at end of file diff --git a/test/fixture/es6.output.json b/test/fixture/es6.output.json index 579303a..9026393 100644 --- a/test/fixture/es6.output.json +++ b/test/fixture/es6.output.json @@ -28,6 +28,17 @@ }, "file": "fixture/es6.input.js", "code": "var multiply = (a, b) => a * b;\nmodule.exports = multiply;" - } + }, + "returns": [ + { + "title": "returns", + "description": "numberone", + "type": { + "type": "NameExpression", + "name": "Number" + } + } + ], + "name": "multiply" } ] \ No newline at end of file diff --git a/test/fixture/simple-hashbang.output.json b/test/fixture/simple-hashbang.output.json index 681b763..5736b2f 100644 --- a/test/fixture/simple-hashbang.output.json +++ b/test/fixture/simple-hashbang.output.json @@ -35,6 +35,19 @@ }, "file": "fixture/simple-hashbang.input.js", "code": "module.exports = function () {\n // this returns 1\n return 1;\n};" - } + }, + "returns": [ + { + "title": "returns", + "description": "numberone", + "type": { + "type": "NameExpression", + "name": "Number" + } + } + ], + "name": "exports", + "memberof": "module", + "scope": "static" } ] \ No newline at end of file diff --git a/test/fixture/simple-private.output.json b/test/fixture/simple-private.output.json index 52c05cb..0637a08 100644 --- a/test/fixture/simple-private.output.json +++ b/test/fixture/simple-private.output.json @@ -1,47 +1 @@ -[ - { - "description": "This function returns the number plus two.", - "tags": [ - { - "title": "param", - "description": "the number", - "type": { - "type": "NameExpression", - "name": "Number" - }, - "name": "a" - }, - { - "title": "returns", - "description": "numbertwo", - "type": { - "type": "NameExpression", - "name": "Number" - } - }, - { - "title": "private", - "description": null, - "type": null - }, - { - "title": "name", - "name": "returnTwo" - } - ], - "context": { - "loc": { - "start": { - "line": 8, - "column": 0 - }, - "end": { - "line": 11, - "column": 1 - } - }, - "file": "fixture/simple-private.input.js", - "code": "function returnTwo(a) {\n // this returns a + 2\n return a + 2;\n}" - } - } -] \ No newline at end of file +[] \ No newline at end of file diff --git a/test/fixture/simple-two.output.json b/test/fixture/simple-two.output.json index 37325c5..274449c 100644 --- a/test/fixture/simple-two.output.json +++ b/test/fixture/simple-two.output.json @@ -41,6 +41,31 @@ }, "file": "fixture/simple-two.input.js", "code": "function returnTwo(a) {\n // this returns a + 2\n return a + 2;\n}" - } + }, + "params": [ + { + "title": "param", + "description": "the number", + "type": { + "type": "NameExpression", + "name": "Number" + }, + "name": "a" + } + ], + "returns": [ + { + "title": "returns", + "description": "numbertwo", + "type": { + "type": "NameExpression", + "name": "Number" + } + } + ], + "examples": [ + "var result = returnTwo(4);\n// result is 6" + ], + "name": "returnTwo" } ] \ No newline at end of file diff --git a/test/fixture/simple.output.json b/test/fixture/simple.output.json index 1333d0e..7a8e02a 100644 --- a/test/fixture/simple.output.json +++ b/test/fixture/simple.output.json @@ -35,6 +35,19 @@ }, "file": "fixture/simple.input.js", "code": "module.exports = function () {\n // this returns 1\n return 1;\n};" - } + }, + "returns": [ + { + "title": "returns", + "description": "numberone", + "type": { + "type": "NameExpression", + "name": "Number" + } + } + ], + "name": "exports", + "memberof": "module", + "scope": "static" } ] \ No newline at end of file diff --git a/test/test.js b/test/test.js index 72ed053..bddcd6d 100644 --- a/test/test.js +++ b/test/test.js @@ -3,8 +3,6 @@ var test = require('prova'), documentation = require('../'), markdown = require('../streams/output/markdown.js'), - flatten = require('../streams/flatten.js'), - filterAccess = require('../streams/filter_access.js'), hierarchy = require('../streams/hierarchy.js'), outputHtml = require('../streams/output/html.js'), glob = require('glob'), @@ -60,8 +58,6 @@ test('html', function (tt) { glob.sync(path.join(__dirname, 'fixture/html', '*.input.js')).forEach(function (file) { tt.test(path.basename(file), function (t) { documentation([file]) - .pipe(flatten()) - .pipe(filterAccess()) .pipe(hierarchy()) .pipe(outputHtml()) .pipe(concat(function (result) { @@ -83,8 +79,6 @@ test('markdown', function (tt) { glob.sync(path.join(__dirname, 'fixture', '*.input.js')).forEach(function (file) { tt.test(path.basename(file), function (t) { documentation([file]) - .pipe(flatten()) - .pipe((filterAccess())) .pipe(markdown()) .pipe(concat(function (result) { var outputfile = file.replace('.input.js', '.output.md'); @@ -96,8 +90,6 @@ test('markdown', function (tt) { }); tt.test(path.basename(file) + ' custom', function (t) { documentation([file]) - .pipe(flatten()) - .pipe((filterAccess())) .pipe(markdown({ template: path.join(__dirname, '/misc/custom.hbs') }))