From 0f47f2d9c15d46ca95b6b025eaaa860dc8e034f8 Mon Sep 17 00:00:00 2001 From: Lloyd Brookes Date: Sat, 8 Oct 2016 16:23:20 +0100 Subject: [PATCH] switch 'cache' option with 'no-cache'.. guaranteed exit.. linting, more tests --- docs/API.md | 2 +- es5/bin/cli.js | 8 +-- es5/lib/dmd-options.js | 34 +--------- es5/lib/jsdoc-options.js | 5 +- es5/lib/jsdoc-to-markdown.js | 1 - es5/test/async.js | 117 +++++++++++++++++++++++++++-------- es5/test/sync.js | 43 +++++++------ package.json | 4 +- src/bin/cli.js | 11 ++-- src/lib/dmd-options.js | 104 +------------------------------ src/lib/jsdoc-options.js | 5 +- src/lib/jsdoc-to-markdown.js | 3 +- src/test/async.js | 114 ++++++++++++++++++++++++++-------- src/test/sync.js | 43 +++++++------ 14 files changed, 243 insertions(+), 251 deletions(-) diff --git a/docs/API.md b/docs/API.md index 332c0ffb..69ffc1c6 100644 --- a/docs/API.md +++ b/docs/API.md @@ -93,7 +93,7 @@ Returns raw data direct from the underlying [jsdoc3](https://github.com/jsdoc3/j | Param | Type | Description | | --- | --- | --- | | [options] | object | the options | -| [options.cache] | boolean | Set to false to disable memoisation cache. Defaults to true. | +| [options.no-cache] | boolean | By default results are cached to speed up repeat invocations. Set to true to disable this. | | [options.files] | string | Array.<string> | One or more filenames to process. Accepts globs (e.g. `*.js`). Either `files`, `source` or `data` must be supplied. | | [options.source] | string | A string containing source code to process. Either `files`, `source` or `data` must be supplied. | | [options.configure] | string | The path to the [jsdoc configuration file](http://usejsdoc.org/about-configuring-jsdoc.html). Default: path/to/jsdoc/conf.json. | diff --git a/es5/bin/cli.js b/es5/bin/cli.js index 87864a48..fbefbadc 100755 --- a/es5/bin/cli.js +++ b/es5/bin/cli.js @@ -7,11 +7,6 @@ var cli = parseCommandLine(); var options = cli.options._all; options = loadStoredConfig(options); -if (options['no-cache']) { - options.cache = false; - delete options['no-cache']; -} - if (options.help) { tool.printOutput(cli.usage); } else if (options.version) { @@ -55,7 +50,8 @@ if (options.help) { if (options.template) options.template = fs.readFileSync(options.template, 'utf8'); _jsdoc2md.render(options).then(function (output) { - return process.stdout.write(output); + process.stdout.write(output); + process.exit(0); }).catch(handleError); } } diff --git a/es5/lib/dmd-options.js b/es5/lib/dmd-options.js index 03789f10..91523027 100644 --- a/es5/lib/dmd-options.js +++ b/es5/lib/dmd-options.js @@ -5,37 +5,9 @@ function _classCallCheck(instance, Constructor) { if (!(instance instanceof Cons var DmdOptions = function DmdOptions(options) { _classCallCheck(this, DmdOptions); - var arrayify = require('array-back'); - - this.template = options.template || '{{>main}}'; - - this['heading-depth'] = options['heading-depth'] || 2; - - this['example-lang'] = options['example-lang'] || 'js'; - - this.plugin = arrayify(options.plugin); - - this.helper = arrayify(options.helper); - - this.partial = arrayify(options.partial); - - this['name-format'] = options['name-format']; - - this['no-gfm'] = options['no-gfm']; - - this.separators = options.separators; - - this['module-index-format'] = options['module-index-format'] || 'dl'; - - this['global-index-format'] = options['global-index-format'] || 'dl'; - - this['param-list-format'] = options['param-list-format'] || 'table'; - - this['property-list-format'] = options['property-list-format'] || 'table'; - - this['member-index-format'] = options['member-index-format'] || 'grouped'; - - this.private = options.private; + Object.assign(this, options); + this.noCache = options['no-cache']; + delete this['no-cache']; }; module.exports = DmdOptions; \ No newline at end of file diff --git a/es5/lib/jsdoc-options.js b/es5/lib/jsdoc-options.js index 4dedd5c2..2ca0057a 100644 --- a/es5/lib/jsdoc-options.js +++ b/es5/lib/jsdoc-options.js @@ -6,7 +6,10 @@ var JsdocOptions = function JsdocOptions(options) { _classCallCheck(this, JsdocOptions); Object.assign(this, options); - this.cache = options.cache === undefined ? true : options.cache; + if (options['no-cache']) { + this.cache = !options['no-cache']; + delete this['no-cache']; + } }; module.exports = JsdocOptions; \ No newline at end of file diff --git a/es5/lib/jsdoc-to-markdown.js b/es5/lib/jsdoc-to-markdown.js index f07accae..2957064d 100644 --- a/es5/lib/jsdoc-to-markdown.js +++ b/es5/lib/jsdoc-to-markdown.js @@ -7,7 +7,6 @@ function _classCallCheck(instance, Constructor) { if (!(instance instanceof Cons var stats = require('jsdoc2md-stats'); var jsdocApi = require('jsdoc-api'); var dmd = require('dmd'); -var os = require('os'); var DmdOptions = require('./dmd-options'); var JsdocOptions = require('./jsdoc-options'); diff --git a/es5/test/async.js b/es5/test/async.js index 013d6a0b..9f73ed5a 100644 --- a/es5/test/async.js +++ b/es5/test/async.js @@ -18,64 +18,127 @@ var runner = new TestRunner(); var inputFile = 'src/test/fixture/ignore.js'; runner.test('.render({ files })', function () { - return jsdoc2md.render({ files: inputFile, cache: false }).then(function (result) { + return jsdoc2md.render({ files: inputFile }).then(function (result) { return a.ok(/a visible global/.test(result)); }); }); runner.test('.render({ data })', function () { var data = [{ - "id": "visible", - "longname": "visible", - "name": "visible", - "kind": "member", - "scope": "global", - "description": "a visible global", - "meta": { - "lineno": 4, - "filename": "ignore.js" + id: 'visible', + longname: 'visible', + name: 'visible', + kind: 'member', + scope: 'global', + description: 'a visible global', + meta: { + lineno: 4, + filename: 'ignore.js' }, - "order": 0 + order: 0 }, { - "id": "invisible", - "longname": "invisible", - "name": "invisible", - "kind": "member", - "scope": "global", - "description": "an ignored global", - "ignore": true, - "meta": { - "lineno": 10, - "filename": "ignore.js" + id: 'invisible', + longname: 'invisible', + name: 'invisible', + kind: 'member', + scope: 'global', + description: 'an ignored global', + ignore: true, + meta: { + lineno: 10, + filename: 'ignore.js' }, - "order": 1 + order: 1 }]; - return jsdoc2md.render({ data: data, cache: false }).then(function (result) { + return jsdoc2md.render({ data: data }).then(function (result) { return a.ok(/a visible global/.test(result)); }); }); runner.test('.render({ files, heading-depth: 4 })', function () { - return jsdoc2md.render({ files: inputFile, cache: false, 'heading-depth': 4 }).then(function (result) { + return jsdoc2md.render({ files: inputFile, 'heading-depth': 4 }).then(function (result) { return a.ok(/#### visible/.test(result)); }); }); runner.test('.render({ files, param-list-format: list })', function () { var inputFile = 'src/test/fixture/params.js'; - return jsdoc2md.render({ files: inputFile, cache: false, 'param-list-format': 'list' }).then(function (result) { + return jsdoc2md.render({ files: inputFile, 'param-list-format': 'list' }).then(function (result) { return a.ok(/- one/.test(result)); }); }); runner.test('.getTemplateData({ files })', function () { - return jsdoc2md.getTemplateData({ files: inputFile, cache: false }).then(function (result) { + return jsdoc2md.getTemplateData({ files: inputFile }).then(function (result) { return a.ok(result[0].id); }); }); runner.test('.getJsdocData({ files })', function () { - return jsdoc2md.getJsdocData({ files: inputFile, cache: false }).then(function (result) { + return jsdoc2md.getJsdocData({ files: inputFile }).then(function (result) { + return a.ok(result[0].longname); + }); +}); + +runner.test('.render({ files, noCache })', function () { + return jsdoc2md.render({ files: inputFile, noCache: true }).then(function (result) { + return a.ok(/a visible global/.test(result)); + }); +}); + +runner.test('.render({ data, noCache })', function () { + var data = [{ + id: 'visible', + longname: 'visible', + name: 'visible', + kind: 'member', + scope: 'global', + description: 'a visible global', + meta: { + lineno: 4, + filename: 'ignore.js' + }, + order: 0 + }, { + id: 'invisible', + longname: 'invisible', + name: 'invisible', + kind: 'member', + scope: 'global', + description: 'an ignored global', + ignore: true, + meta: { + lineno: 10, + filename: 'ignore.js' + }, + order: 1 + }]; + return jsdoc2md.render({ data: data, noCache: true }).then(function (result) { + return a.ok(/a visible global/.test(result)); + }); +}); + +runner.test('.render({ files, heading-depth: 4, noCache })', function () { + return jsdoc2md.render({ files: inputFile, 'heading-depth': 4, noCache: true }).then(function (result) { + return a.ok(/#### visible/.test(result)); + }); +}); + +runner.test('.render({ files, param-list-format: list, noCache })', function () { + var inputFile = 'src/test/fixture/params.js'; + return jsdoc2md.render({ files: inputFile, 'param-list-format': 'list', noCache: true }).then(function (result) { + return a.ok(/- one/.test(result)); + }); +}); + +runner.test('.getTemplateData({ files, noCache })', function () { + return jsdoc2md.getTemplateData({ files: inputFile, noCache: true }).then(function (result) { + return a.ok(result[0].id); + }); +}); + +runner.test('.getJsdocData({ files, noCache })', function () { + return jsdoc2md.getJsdocData({ files: inputFile, noCache: true }).then(function (result) { return a.ok(result[0].longname); }); }); \ No newline at end of file diff --git a/es5/test/sync.js b/es5/test/sync.js index 9c6764b7..235d3a2a 100644 --- a/es5/test/sync.js +++ b/es5/test/sync.js @@ -5,7 +5,6 @@ if (!require('child_process').spawnSync) process.exit(0); var TestRunner = require('test-runner'); var jsdoc2md = require('../../'); var a = require('assert'); -var path = require('path'); var fs = require('fs'); try { @@ -21,30 +20,30 @@ runner.test('.renderSync({ files })', function () { runner.test('.renderSync({ data })', function () { var data = [{ - "id": "visible", - "longname": "visible", - "name": "visible", - "kind": "member", - "scope": "global", - "description": "a visible global", - "meta": { - "lineno": 4, - "filename": "ignore.js" + id: 'visible', + longname: 'visible', + name: 'visible', + kind: 'member', + scope: 'global', + description: 'a visible global', + meta: { + lineno: 4, + filename: 'ignore.js' }, - "order": 0 + order: 0 }, { - "id": "invisible", - "longname": "invisible", - "name": "invisible", - "kind": "member", - "scope": "global", - "description": "an ignored global", - "ignore": true, - "meta": { - "lineno": 10, - "filename": "ignore.js" + id: 'invisible', + longname: 'invisible', + name: 'invisible', + kind: 'member', + scope: 'global', + description: 'an ignored global', + ignore: true, + meta: { + lineno: 10, + filename: 'ignore.js' }, - "order": 1 + order: 1 }]; var result = jsdoc2md.renderSync({ data: data, cache: false }); a.ok(/a visible global/.test(result)); diff --git a/package.json b/package.json index b23dcb97..f5c4b017 100644 --- a/package.json +++ b/package.json @@ -29,9 +29,9 @@ "command-line-tool": "^0.6.4", "config-master": "^2.0.4", "core-js": "^2.4.1", - "dmd": "^2.0.3", + "dmd": "^2.1.0", "feature-detect-es6": "^1.3.1", - "jsdoc-api": "^2.0.3", + "jsdoc-api": "^2.0.5", "jsdoc-parse": "^2.0.5", "jsdoc2md-stats": "^1.0.1", "walk-back": "^2.0.1" diff --git a/src/bin/cli.js b/src/bin/cli.js index 5929f049..552ccd86 100755 --- a/src/bin/cli.js +++ b/src/bin/cli.js @@ -6,12 +6,6 @@ const cli = parseCommandLine() let options = cli.options._all options = loadStoredConfig(options) -/* jsdoc2md --no-cache */ -if (options['no-cache']) { - options.cache = false - delete options['no-cache'] -} - /* jsdoc2md --help */ if (options.help) { tool.printOutput(cli.usage) @@ -79,7 +73,10 @@ if (options.help) { jsdoc2md .render(options) - .then(output => process.stdout.write(output)) + .then(output => { + process.stdout.write(output) + process.exit(0) + }) .catch(handleError) } } diff --git a/src/lib/dmd-options.js b/src/lib/dmd-options.js index 652ef5f4..858118d8 100644 --- a/src/lib/dmd-options.js +++ b/src/lib/dmd-options.js @@ -5,107 +5,9 @@ */ class DmdOptions { constructor (options) { - const arrayify = require('array-back') - - /** - * The template the supplied documentation will be rendered into. Use the default or supply your own template for full control over the output. - * @type {string} - * @default - */ - this.template = options.template || '{{>main}}' - - /** - * The initial heading depth. For example, with a value of `2` the top-level markdown headings look like `"## The heading"`. - * @type number - * @default - */ - this['heading-depth'] = options['heading-depth'] || 2 - - /** - * Specifies the default language used in @example blocks (for [syntax-highlighting](https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting) purposes). In gfm mode, each @example is wrapped in a fenced-code block. Example usage: `--example-lang js`. Use the special value `none` for no specific language. While using this option, you can override the supplied language for any @example by specifying the `@lang` subtag, e.g `@example @lang hbs`. Specifying `@example @lang off` will disable code blocks for that example. - * @type {string} - * @default - */ - this['example-lang'] = options['example-lang'] || 'js' - - /** - * Use an installed package containing helper and/or partial overrides - * @type {array} - */ - this.plugin = arrayify(options.plugin) - - /** - * handlebars helper files to override or extend the default set - * @type {array} - */ - this.helper = arrayify(options.helper) - - /** - * handlebars partial files to override or extend the default set - * @type {array} - */ - this.partial = arrayify(options.partial) - - /** - * Format identifier names in the [code](http://daringfireball.net/projects/markdown/syntax#code) style, (i.e. format using backticks or ``) - * @type {string} - */ - this['name-format'] = options['name-format'] - - /** - * By default, dmd generates github-flavoured markdown. Not all markdown parsers render gfm correctly. If your generated docs look incorrect on sites other than Github (e.g. npmjs.org) try enabling this option to disable Github-specific syntax. - * @type {boolean} - */ - this['no-gfm'] = options['no-gfm'] - - /** - * Put `
` breaks between identifiers. Improves readability on bulky docs. - * @type {boolean} - * @default false - */ - this.separators = options.separators - - /** - * none, grouped, table, dl - * @type {string} - * @default - */ - this['module-index-format'] = options['module-index-format'] || 'dl' - - /** - * none, grouped, table, dl - * @type {string} - * @default - */ - this['global-index-format'] = options['global-index-format'] || 'dl' - - /** - * Two options to render parameter lists: 'list' or 'table' (default). Table format works well in most cases but switch to list if things begin to look crowded / squashed. - * @type {string} - * @default - */ - this['param-list-format'] = options['param-list-format'] || 'table' - - /** - * list, table - * @type {string} - * @default - */ - this['property-list-format'] = options['property-list-format'] || 'table' - - /** - * grouped, list - * @type {string} - * @default - */ - this['member-index-format'] = options['member-index-format'] || 'grouped' - - /** - * Show identifiers marked `@private` in the output. - * @type {boolean} - * @default false - */ - this.private = options.private + Object.assign(this, options) + this.noCache = options['no-cache'] + delete this['no-cache'] } } diff --git a/src/lib/jsdoc-options.js b/src/lib/jsdoc-options.js index b0e1be13..928ae070 100644 --- a/src/lib/jsdoc-options.js +++ b/src/lib/jsdoc-options.js @@ -3,7 +3,10 @@ class JsdocOptions { constructor (options) { Object.assign(this, options) - this.cache = options.cache === undefined ? true : options.cache + if (options['no-cache']) { + this.cache = !options['no-cache'] + delete this['no-cache'] + } } } diff --git a/src/lib/jsdoc-to-markdown.js b/src/lib/jsdoc-to-markdown.js index 614a622b..128a8681 100644 --- a/src/lib/jsdoc-to-markdown.js +++ b/src/lib/jsdoc-to-markdown.js @@ -2,7 +2,6 @@ const stats = require('jsdoc2md-stats') const jsdocApi = require('jsdoc-api') const dmd = require('dmd') -const os = require('os') const DmdOptions = require('./dmd-options') const JsdocOptions = require('./jsdoc-options') @@ -109,7 +108,7 @@ class JsdocToMarkdown { * Returns raw data direct from the underlying [jsdoc3](https://github.com/jsdoc3/jsdoc). * * @param [options] {object} - the options - * @param [options.cache] {boolean} - Set to false to disable memoisation cache. Defaults to true. + * @param [options.no-cache] {boolean} - By default results are cached to speed up repeat invocations. Set to true to disable this. * @param [options.files] {string|string[]} - One or more filenames to process. Accepts globs (e.g. `*.js`). Either `files`, `source` or `data` must be supplied. * @param [options.source] {string} - A string containing source code to process. Either `files`, `source` or `data` must be supplied. * @param [options.configure] {string} - The path to the [jsdoc configuration file](http://usejsdoc.org/about-configuring-jsdoc.html). Default: path/to/jsdoc/conf.json. diff --git a/src/test/async.js b/src/test/async.js index e0bc53a7..da75f14b 100644 --- a/src/test/async.js +++ b/src/test/async.js @@ -17,61 +17,121 @@ const runner = new TestRunner() const inputFile = 'src/test/fixture/ignore.js' runner.test('.render({ files })', function () { - return jsdoc2md.render({ files: inputFile, cache: false }) + return jsdoc2md.render({ files: inputFile }) .then(result => a.ok(/a visible global/.test(result))) }) runner.test('.render({ data })', function () { const data = [ { - "id": "visible", - "longname": "visible", - "name": "visible", - "kind": "member", - "scope": "global", - "description": "a visible global", - "meta": { - "lineno": 4, - "filename": "ignore.js" + id: 'visible', + longname: 'visible', + name: 'visible', + kind: 'member', + scope: 'global', + description: 'a visible global', + meta: { + lineno: 4, + filename: 'ignore.js' }, - "order": 0 + order: 0 }, { - "id": "invisible", - "longname": "invisible", - "name": "invisible", - "kind": "member", - "scope": "global", - "description": "an ignored global", - "ignore": true, - "meta": { - "lineno": 10, - "filename": "ignore.js" + id: 'invisible', + longname: 'invisible', + name: 'invisible', + kind: 'member', + scope: 'global', + description: 'an ignored global', + ignore: true, + meta: { + lineno: 10, + filename: 'ignore.js' }, - "order": 1 + order: 1 } ] - return jsdoc2md.render({ data: data, cache: false }) + return jsdoc2md.render({ data: data }) .then(result => a.ok(/a visible global/.test(result))) }) runner.test('.render({ files, heading-depth: 4 })', function () { - return jsdoc2md.render({ files: inputFile, cache: false, 'heading-depth': 4 }) + return jsdoc2md.render({ files: inputFile, 'heading-depth': 4 }) .then(result => a.ok(/#### visible/.test(result))) }) runner.test('.render({ files, param-list-format: list })', function () { const inputFile = 'src/test/fixture/params.js' - return jsdoc2md.render({ files: inputFile, cache: false, 'param-list-format': 'list' }) + return jsdoc2md.render({ files: inputFile, 'param-list-format': 'list' }) .then(result => a.ok(/- one/.test(result))) }) runner.test('.getTemplateData({ files })', function () { - return jsdoc2md.getTemplateData({ files: inputFile, cache: false }) + return jsdoc2md.getTemplateData({ files: inputFile }) .then(result => a.ok(result[0].id)) }) runner.test('.getJsdocData({ files })', function () { - return jsdoc2md.getJsdocData({ files: inputFile, cache: false }) + return jsdoc2md.getJsdocData({ files: inputFile }) + .then(result => a.ok(result[0].longname)) +}) + +runner.test('.render({ files, noCache })', function () { + return jsdoc2md.render({ files: inputFile, noCache: true }) + .then(result => a.ok(/a visible global/.test(result))) +}) + +runner.test('.render({ data, noCache })', function () { + const data = [ + { + id: 'visible', + longname: 'visible', + name: 'visible', + kind: 'member', + scope: 'global', + description: 'a visible global', + meta: { + lineno: 4, + filename: 'ignore.js' + }, + order: 0 + }, + { + id: 'invisible', + longname: 'invisible', + name: 'invisible', + kind: 'member', + scope: 'global', + description: 'an ignored global', + ignore: true, + meta: { + lineno: 10, + filename: 'ignore.js' + }, + order: 1 + } + ] + return jsdoc2md.render({ data: data, noCache: true }) + .then(result => a.ok(/a visible global/.test(result))) +}) + +runner.test('.render({ files, heading-depth: 4, noCache })', function () { + return jsdoc2md.render({ files: inputFile, 'heading-depth': 4, noCache: true }) + .then(result => a.ok(/#### visible/.test(result))) +}) + +runner.test('.render({ files, param-list-format: list, noCache })', function () { + const inputFile = 'src/test/fixture/params.js' + return jsdoc2md.render({ files: inputFile, 'param-list-format': 'list', noCache: true }) + .then(result => a.ok(/- one/.test(result))) +}) + +runner.test('.getTemplateData({ files, noCache })', function () { + return jsdoc2md.getTemplateData({ files: inputFile, noCache: true }) + .then(result => a.ok(result[0].id)) +}) + +runner.test('.getJsdocData({ files, noCache })', function () { + return jsdoc2md.getJsdocData({ files: inputFile, noCache: true }) .then(result => a.ok(result[0].longname)) }) diff --git a/src/test/sync.js b/src/test/sync.js index ff47a9f7..5d0a574d 100644 --- a/src/test/sync.js +++ b/src/test/sync.js @@ -5,7 +5,6 @@ if (!require('child_process').spawnSync) process.exit(0) const TestRunner = require('test-runner') const jsdoc2md = require('../../') const a = require('assert') -const path = require('path') const fs = require('fs') try { @@ -24,31 +23,31 @@ runner.test('.renderSync({ files })', function () { runner.test('.renderSync({ data })', function () { const data = [ { - "id": "visible", - "longname": "visible", - "name": "visible", - "kind": "member", - "scope": "global", - "description": "a visible global", - "meta": { - "lineno": 4, - "filename": "ignore.js" + id: 'visible', + longname: 'visible', + name: 'visible', + kind: 'member', + scope: 'global', + description: 'a visible global', + meta: { + lineno: 4, + filename: 'ignore.js' }, - "order": 0 + order: 0 }, { - "id": "invisible", - "longname": "invisible", - "name": "invisible", - "kind": "member", - "scope": "global", - "description": "an ignored global", - "ignore": true, - "meta": { - "lineno": 10, - "filename": "ignore.js" + id: 'invisible', + longname: 'invisible', + name: 'invisible', + kind: 'member', + scope: 'global', + description: 'an ignored global', + ignore: true, + meta: { + lineno: 10, + filename: 'ignore.js' }, - "order": 1 + order: 1 } ] const result = jsdoc2md.renderSync({ data: data, cache: false })