Merge branch 'master' into releases/3.3

Conflicts:
	package.json

.eslintrc

@@ -35,6 +35,7 @@
         "consistent-return": 2,
         "curly": [2, "all"],
         "dot-notation": 2,
+        "eol-last": 2,
         "eqeqeq": [2, "smart"],
         "guard-for-in": 2,
         "no-alert": 2,
@@ -52,6 +53,7 @@
         "no-iterator": 2,
         "no-lone-blocks": 2,
         "no-loop-func": 2,
+        "no-mixed-spaces-and-tabs": 2,
         "no-multi-str": 2,
         "no-native-reassign": 2,
         "no-new": 2,
@@ -65,12 +67,14 @@
         "no-script-url": 2,
         "no-self-compare": 2,
         "no-sequences": 2,
+        "no-trailing-spaces": 2,
+        "no-undefined": 0,
         "no-unused-expressions": 2,
         "no-warning-comments": 0,
         "no-with": 2,
-        "no-yoda": 2,
         "radix": 2,
         "wrap-iife": [2, "inside"],
+        "yoda": 2,
 
         // Strict mode
         "no-global-strict": 0,
@@ -101,7 +105,7 @@
         "consistent-this": [2, "self"],
         "func-names": 0, // TODO: enable
         "func-style": 0,
-        "max-nested-callbacks": [2, 2],
+        "max-nested-callbacks": 0,
         "new-cap": 2,
         "new-parens": 2,
         "no-nested-ternary": 2,

.gitignore

@@ -6,6 +6,9 @@ node_modules/eslint
 node_modules/gulp*
 node_modules/istanbul
 
+# Node.js-only modules
+node_modules/requizzle
+
 # User-specific files
 conf.json
 

LICENSE.md

@@ -81,7 +81,7 @@ https://github.com/caolan/async
 
 Catharsis is distributed under the MIT license, which is reproduced above.
 
-Copyright (c) 2012-2013 Jeff Williams.
+Copyright (c) 2012-2014 Jeff Williams.
 
 The source code for Catharsis is available at:
 https://github.com/hegemonic/catharsis
@@ -96,6 +96,16 @@ Copyright (c) 2013 Dominic Tarr.
 The source code for crypto-browserify is available at:
 https://github.com/dominictarr/crypto-browserify
 
+## escape-string-regexp ##
+
+escape-string-regexp is distributed under the MIT License, which is reproduced
+above.
+
+Copyright (c) Sindre Sorhus <[email protected]>.
+
+The source code for escape-string-regexp is available at:
+https://github.com/sindresorhus/escape-string-regexp
+
 ## Esprima ##
 
 Esprima is distributed under the BSD 2-clause license:
@@ -125,6 +135,19 @@ Copyright (c) 2011-2013 Ariya Hidayat and other Esprima contributors.
 The source code for Esprima is available at:
 https://github.com/ariya/esprima
 
+## events ##
+
+Portions of the events source code are incorporated into the following files:
+
++ `rhino/events.js`
+
+events is distributed under the MIT license, which is reproduced above.
+
+Copyright Joyent, Inc. and other Node contributors. All rights reserved.
+
+The source code for events is available at:
+https://github.com/Gozala/events
+
 ## github-flavored-markdown ##
 
 github-flavored-markdown is distributed under the BSD 3-clause license:
@@ -200,38 +223,6 @@ Copyright (c) 2012 Michael Kourlas.
 The source code for js2xmlparser is available at:
 https://github.com/michaelkourlas/node-js2xmlparser
 
-## JSHint ##
-
-JSHint is distributed under the MIT license, which is reproduced above.
-
-Portions of JSHint are derived from JSLint, which is distributed under a
-modified MIT license:
-
-> Copyright (c) 2002 Douglas Crockford  (www.JSLint.com)
->
-> Permission is hereby granted, free of charge, to any person obtaining a copy
-> of this software and associated documentation files (the "Software"), to deal
-> in the Software without restriction, including without limitation the rights
-> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-> copies of the Software, and to permit persons to whom the Software is
-> furnished to do so, subject to the following conditions:
->
-> The above copyright notice and this permission notice shall be included in all
-> copies or substantial portions of the Software.
->
-> The Software shall be used for Good, not Evil.
->
-> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-> SOFTWARE.
-
-The source code for JSHint is available at:
-https://github.com/jshint/jshint
-
 ## Node.js ##
 
 Portions of the Node.js source code are incorporated into the following files:
@@ -262,18 +253,6 @@ above.
 The source code for node-browser-builtins is available at:
 https://github.com/alexgorbatchev/node-browser-builtins
 
-## node-browserify ##
-
-Portions of the node-browserify source code are incorporated into the following
-files:
-
-- `rhino/events.js`
-
-node-browserify is distributed under the MIT license, which is reproduced above.
-
-The source code for node-browserify is available at:
-https://github.com/substack/node-browserify
-
 ## Requizzle ##
 
 Requizzle is distributed under the MIT license, which is reproduced above.

README.md

@@ -29,11 +29,6 @@ To install the latest development version:
 
     npm install git+https://github.com/jsdoc3/jsdoc.git
 
-**Note**: If you install JSDoc globally, do not use `sudo npm install`. This may
-prevent you from running JSDoc as a normal user. If you cannot install global
-packages without `sudo`, please
-[fix your npm directory permissions](http://howtonode.org/introduction-to-npm).
-
 #### Running JSDoc with Node.js
 
 If you installed JSDoc locally, the JSDoc command-line tool is available in
@@ -115,10 +110,11 @@ generate and customize your documentation. Here are just a few:
 For More Information
 --------------------
 
-Project Documentation: <http://usejsdoc.org/>  
-Project Documentation Source: <https://github.com/jsdoc3/jsdoc3.github.com>  
-JSDoc User's Group: <http://groups.google.com/group/jsdoc-users>  
-Project Announcements: <http://twitter.com/jsdoc3>
++ Documentation is available at [Use JSDoc](http://usejsdoc.org).
++ Contribute to the docs at [jsdoc3/jsdoc3.github.com](https://github.com/jsdoc3/jsdoc3.github.com).
++ Ask for help on the [JSDoc Users mailing list](http://groups.google.com/group/jsdoc-users).
++ Post questions tagged `jsdoc` to [Stack
+Overflow](http://stackoverflow.com/questions/tagged/jsdoc).
 
 License
 -------

cli.js

@@ -241,41 +241,69 @@ cli.main = function(cb) {
     cb(0);
 };
 
-function getRandomId() {
-    var MIN = 100000;
-    var MAX = 999999;
+function readPackageJson(filepath) {
+    var fs = require('jsdoc/fs');
 
-    return Math.floor(Math.random() * (MAX - MIN + 1) + MIN);
+    try {
+        return stripJsonComments( fs.readFileSync(filepath, 'utf8') );
+    }
+    catch (e) {
+        logger.error('Unable to read the package file "%s"', filepath);
+        return null;
+    }
 }
 
-// TODO: docs
-cli.scanFiles = function() {
-    var Filter = require('jsdoc/src/filter').Filter;
+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);
+    }
+
+    // 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;
     }
 
-    // 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];
+    // 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 ( /\bpackage\.json$/i.test(opt) ) {
-            props.packageJson = fs.readFileSync(opt, 'utf8');
-            env.opts._.splice(i--, 1);
+        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);
@@ -290,7 +318,6 @@ cli.scanFiles = function() {
 function resolvePluginPaths(paths) {
     var path = require('jsdoc/path');
 
-    var isNode = require('jsdoc/util/runtime').isNode();
     var pluginPaths = [];
 
     paths.forEach(function(plugin) {
@@ -345,6 +372,7 @@ cli.parseFiles = function() {
     logger.debug('Adding inherited symbols...');
     borrow.indexAll(docs);
     augment.addInherited(docs);
+    augment.addImplemented(docs);
     borrow.resolveBorrows(docs);
 
     app.jsdoc.parser.fireProcessingComplete(docs);
@@ -389,7 +417,6 @@ cli.generateDocs = function() {
     var template;
 
     env.opts.template = (function() {
-        var isNode = require('jsdoc/util/runtime').isNode();
         var publish = env.opts.template || 'templates/default';
         var templatePath = path.getResourcePath(publish);
 

jsdoc.js

@@ -98,7 +98,10 @@ global.env = {
         // plugins, and within JSDoc itself. It also allows external templates and plugins to
         // require JSDoc's module dependencies without installing them locally.
         require = require('requizzle')({
-            requirePaths: [path.join(__dirname, 'lib'), path.join(__dirname, 'node_modules')],
+            requirePaths: {
+                before: [path.join(__dirname, 'lib')],
+                after: [path.join(__dirname, 'node_modules')]
+            },
             infect: true
         });
     }