From c45fdaa0c36410cfe53464b9192e9ec2d2bbcda3 Mon Sep 17 00:00:00 2001 From: Jeff Williams Date: Fri, 17 Oct 2014 12:46:52 -0700 Subject: [PATCH] allow any file to be used as a package or README file (#708) --- cli.js | 65 +++++++++++++++++++++++++++-------- lib/jsdoc/opts/args.js | 2 ++ test/specs/jsdoc/opts/args.js | 32 ++++++++++++++++- 3 files changed, 83 insertions(+), 16 deletions(-) diff --git a/cli.js b/cli.js index e29912f9..854829d2 100644 --- a/cli.js +++ b/cli.js @@ -241,34 +241,69 @@ cli.main = function(cb) { cb(0); }; -// TODO: docs -cli.scanFiles = function() { - var Filter = require('jsdoc/src/filter').Filter; +function readPackageJson(filepath) { + var fs = require('jsdoc/fs'); + + try { + return stripJsonComments( fs.readFileSync(filepath, 'utf8') ); + } + catch (e) { + logger.error('Unable to read the package file "%s"', filepath); + return null; + } +} + +function buildSourceList() { var fs = require('jsdoc/fs'); var Readme = require('jsdoc/readme'); - var filter; - var opt; + var packageJson; + var readmeHtml; + var sourceFile; + var sourceFiles = env.opts._ ? env.opts._.slice(0) : []; if (env.conf.source && env.conf.source.include) { - env.opts._ = (env.opts._ || []).concat(env.conf.source.include); + sourceFiles = sourceFiles.concat(env.conf.source.include); } - // source files named `package.json` or `README.md` get special treatment - for (var i = 0, l = env.opts._.length; i < l; i++) { - opt = env.opts._[i]; + // load the user-specified package/README files, if any + if (env.opts.package) { + packageJson = readPackageJson(env.opts.package); + } + if (env.opts.readme) { + readmeHtml = new Readme(env.opts.readme).html; + } - if ( /\bpackage\.json$/i.test(opt) ) { - props.packageJson = fs.readFileSync(opt, 'utf8'); - env.opts._.splice(i--, 1); + // source files named `package.json` or `README.md` get special treatment, unless the user + // explicitly specified a package and/or README file + for (var i = 0, l = sourceFiles.length; i < l; i++) { + sourceFile = sourceFiles[i]; + + if ( !env.opts.package && /\bpackage\.json$/i.test(sourceFile) ) { + packageJson = readPackageJson(sourceFile); + sourceFiles.splice(i--, 1); } - if ( /(\bREADME|\.md)$/i.test(opt) ) { - env.opts.readme = new Readme(opt).html; - env.opts._.splice(i--, 1); + if ( !env.opts.readme && /(\bREADME|\.md)$/i.test(sourceFile) ) { + readmeHtml = new Readme(sourceFile).html; + sourceFiles.splice(i--, 1); } } + props.packageJson = packageJson; + env.opts.readme = readmeHtml; + + return sourceFiles; +} + +// TODO: docs +cli.scanFiles = function() { + var Filter = require('jsdoc/src/filter').Filter; + + var filter; + + env.opts._ = buildSourceList(); + // are there any files to scan and parse? if (env.conf.source && env.opts._.length) { filter = new Filter(env.conf.source); diff --git a/lib/jsdoc/opts/args.js b/lib/jsdoc/opts/args.js index bddd5650..4748680d 100644 --- a/lib/jsdoc/opts/args.js +++ b/lib/jsdoc/opts/args.js @@ -84,6 +84,8 @@ argParser.addOption('h', 'help', false, 'Print this message and quit.'); argParser.addOption('X', 'explain', false, 'Dump all found doclet internals to console and quit.'); argParser.addOption('q', 'query', true, 'A query string to parse and store in env.opts.query. Example: foo=bar&baz=true', false, parseQuery); argParser.addOption('u', 'tutorials', true, 'Directory in which JSDoc should search for tutorials.'); +argParser.addOption('P', 'package', true, 'The path to the project\'s package file. Default: path/to/sourcefiles/package.json'); +argParser.addOption('R', 'readme', true, 'The path to the project\'s README file. Default: path/to/sourcefiles/README.md'); argParser.addOption('v', 'version', false, 'Display the version number and quit.'); argParser.addOption('', 'debug', false, 'Log information for debugging JSDoc. On Rhino, launches the debugger when passed as the first option.'); argParser.addOption('', 'verbose', false, 'Log detailed information to the console as JSDoc runs.'); diff --git a/test/specs/jsdoc/opts/args.js b/test/specs/jsdoc/opts/args.js index d3c81839..16cd77ba 100644 --- a/test/specs/jsdoc/opts/args.js +++ b/test/specs/jsdoc/opts/args.js @@ -1,4 +1,6 @@ -/*global describe: true, expect: true, it: true */ +/*global describe, expect, it */ +'use strict'; + describe('jsdoc/opts/args', function() { var args = require('jsdoc/opts/args'); var querystring = require('querystring'); @@ -247,6 +249,34 @@ describe('jsdoc/opts/args', function() { expect(r.nocolor).toBe(true); }); + it('should accept a "-P" option and return an object with a "package" property', function() { + args.parse(['-P', 'path/to/package/file.json']); + var r = args.get(); + + expect(r.package).toBe('path/to/package/file.json'); + }); + + it('should accept a "--package" option and return an object with a "package" property', function() { + args.parse(['--package', 'path/to/package/file.json']); + var r = args.get(); + + expect(r.package).toBe('path/to/package/file.json'); + }); + + it('should accept a "-R" option and return an object with a "readme" property', function() { + args.parse(['-R', 'path/to/readme/file.md']); + var r = args.get(); + + expect(r.readme).toBe('path/to/readme/file.md'); + }); + + it('should accept a "--readme" option and return an object with a "readme" property', function() { + args.parse(['--readme', 'path/to/readme/file.md']); + var r = args.get(); + + expect(r.readme).toBe('path/to/readme/file.md'); + }); + it('should accept a "-v" option and return an object with a "version" property', function() { args.parse(['-v']); var r = args.get();