allow any file to be used as a package or README file (#708)

cli.js

@@ -241,34 +241,69 @@ cli.main = function(cb) {
     cb(0);
 };
 
-// TODO: docs
+function readPackageJson(filepath) {
-cli.scanFiles = function() {
+    var fs = require('jsdoc/fs');
-    var Filter = require('jsdoc/src/filter').Filter;
+
+    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 packageJson;
-    var opt;
+    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
+    // load the user-specified package/README files, if any
-    for (var i = 0, l = env.opts._.length; i < l; i++) {
+    if (env.opts.package) {
-        opt = env.opts._[i];
+        packageJson = readPackageJson(env.opts.package);
-
+    }
-        if ( /\bpackage\.json$/i.test(opt) ) {
+    if (env.opts.readme) {
-            props.packageJson = fs.readFileSync(opt, 'utf8');
+        readmeHtml = new Readme(env.opts.readme).html;
-            env.opts._.splice(i--, 1);
     }
 
-        if ( /(\bREADME|\.md)$/i.test(opt) ) {
+    // source files named `package.json` or `README.md` get special treatment, unless the user
-            env.opts.readme = new Readme(opt).html;
+    // explicitly specified a package and/or README file
-            env.opts._.splice(i--, 1);
+    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 ( !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);

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.');

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();