Merge branch 'original-master'

Author: Duc Tri Le

.eslintrc

@@ -48,12 +48,11 @@
         "no-caller": 2,
         "no-div-regex": 2,
         "no-else-return": 0,
-        "no-empty-label": 2,
         "no-eq-null": 2,
         "no-eval": 2,
         "no-extra-bind": 2,
         "no-extend-native": 2,
-        "no-fallthrough": 2,
+        "no-fallthrough": 0, // disabled due to ESLint bug
         "no-floating-decimal": 2,
         "no-implied-eval": 2,
         "no-iterator": 2,
@@ -156,12 +155,11 @@
         "semi": [2, "always"],
         "semi-spacing": 2,
         "sort-vars": 0,
-        "space-after-keywords": [2, "always"],
+        "keyword-spacing": 2,
         "space-before-blocks": [2, "always"],
         "space-in-brackets": 0, // TODO: enable?
         "space-in-parens": 0, // TODO: enable?
         "space-infix-ops": 2,
-        "space-return-throw-case": 2,
         "space-unary-ops": 2,
         "spaced-comment": [2, "always"],
         "wrap-regex": 0,

.travis.yml

@@ -1,7 +1,8 @@
 language: node_js
 
 node_js:
-  - "0.10"
-  - "0.12"
+  - "6"
+  - "5"
+  - "4"
 
 install: npm install -g gulp; npm install

CHANGES.md

@@ -3,6 +3,26 @@
 This file describes notable changes in each version of JSDoc 3. To download a specific version of JSDoc 3, see [GitHub's tags page](https://github.com/jsdoc3/jsdoc/tags).
 
 
+## 3.4.1 (September 2016)
+
+### Enhancements
++ When installing JSDoc from NPM, all dependencies are now pulled from NPM. (#961)
++ The configuration setting `tags.allowUnknownTags` may now contain an array of tag names that should be allowed. (#1159)
+
+### Bug fixes
++ When an ES2015 module's default export is a class, JSDoc now documents the class correctly. (#1113, #1120)
++ JSDoc no longer crashes when an ES2015 module exports an anonymous class. (#1113)
++ JSDoc no longer crashes when the experimental object spread operator is used. (#1141)
++ In ES2015 methods, JSDoc now autodetects whether a parameter is a default or repeatable parameter. (#1144)
++ The Markdown plugin now works correctly with inline tags that contain special characters, such as `{@link chat."#channel"}`. (#1035)
++ When JSDoc is run in a directory that has a `plugins/` or `templates/` directory, JSDoc can now discover plugins and templates in other directories. (#1081)
+
+### Templates
++ The default template now uses appropriate styles for displaying tables. (#1064)
++ The default template's CSS file no longer uses the same style for both `<h2>` and `<h3>` elements. (#1108)
++ JSDoc now includes a `silent` template that generates no output. This template makes it easier to use JSDoc as a linter to check for syntax errors and unrecognized tags in documentation comments. (#1160)
+
+
 ## 3.4.0 (November 2015)
 
 ### Major changes

LICENSE.md

@@ -4,7 +4,7 @@ JSDoc 3 is free software, licensed under the Apache License, Version 2.0 (the
 "License"). Commercial and non-commercial use are permitted in compliance with
 the License.
 
-Copyright (c) 2011-2015 Michael Mathews <[email protected]> and the
+Copyright (c) 2011-present Michael Mathews <[email protected]> and the
 [contributors to JSDoc](https://github.com/jsdoc3/jsdoc/graphs/contributors).
 All rights reserved.
 

README.md

@@ -49,12 +49,13 @@ generate and customize your documentation. Here are just a few:
 + [jsdoc3Template](https://github.com/DBCDK/jsdoc3Template)
   ([example](https://github.com/danyg/jsdoc3Template/wiki#wiki-screenshots))
 + [minami](https://github.com/Nijikokun/minami)
++ [docdash](https://github.com/clenemt/docdash)([example](http://clenemt.github.io/docdash/))
 
 ### Build Tools
 
++ [JSDoc Ant task](https://github.com/jannon/jsdoc3-ant-task)
 + [JSDoc Grunt plugin](https://github.com/krampstudio/grunt-jsdoc)
-+ [JSDoc ant task](https://github.com/jannon/jsdoc3-ant-task)
-
++ [JSDoc Gulp plugin](https://github.com/mlucool/gulp-jsdoc3)
 
 For More Information
 --------------------
@@ -68,7 +69,7 @@ Overflow](http://stackoverflow.com/questions/tagged/jsdoc).
 License
 -------
 
-JSDoc 3 is copyright (c) 2011-2015 Michael Mathews <[email protected]> and the
+JSDoc 3 is copyright (c) 2011-present Michael Mathews <[email protected]> and the
 [contributors to JSDoc](https://github.com/jsdoc3/jsdoc/graphs/contributors).
 
 JSDoc 3 is free software, licensed under the Apache License, Version 2.0. See

cli.js

@@ -314,17 +314,11 @@ function resolvePluginPaths(paths) {
     paths.forEach(function(plugin) {
         var basename = path.basename(plugin);
         var dirname = path.dirname(plugin);
-        // convoluted way to detect the correct path for the plugins; done this round-about way to cope
-        // with scenarios where JSDoc is executed in another project's working directory where that
-        // project has plugins of itself in a similar directory structure (plugins/*)
-        var pluginPath = path.getResourcePath(dirname, basename + ".js");
+        var pluginPath = path.getResourcePath(dirname);
 
         if (!pluginPath) {
             logger.error('Unable to find the plugin "%s"', plugin);
             return;
-        } else {
-            // correct the path to the plugin:
-            pluginPath = path.dirname(pluginPath);
         }
 
         pluginPaths.push( path.join(pluginPath, basename) );
@@ -416,18 +410,7 @@ cli.generateDocs = function() {
 
     env.opts.template = (function() {
         var publish = env.opts.template || 'templates/default';
-        // convoluted way to detect the correct path for the templates; done this round-about way to cope
-        // with scenarios where JSDoc is executed in another project's working directory where that
-        // project has templates of itself in a similar directory structure (templates/<name>/)
-        var templatePath = path.getResourcePath(publish, "publish.js");
-
-        if (!templatePath) {
-            logger.error('Unable to find the template "%s"', publish);
-            return publish;
-        } else {
-            // correct the path to the template:
-            templatePath = path.dirname(templatePath);
-        }
+        var templatePath = path.getResourcePath(publish);
 
         // if we didn't find the template, keep the user-specified value so the error message is
         // useful

gulpfile.js

@@ -48,7 +48,7 @@ gulp.task('coverage', function(cb) {
 });
 
 gulp.task('lint', function() {
-    var pipeline = gulp.src(options.lintPaths)
+    return gulp.src(options.lintPaths)
         .pipe(eslint())
         .pipe(eslint.formatEach())
         .pipe(eslint.failOnError());

lib/jsdoc/fs.js

@@ -7,7 +7,7 @@
 var fs = require('fs');
 var path = require('path');
 var stream = require('stream');
-var wrench = require('wrench');
+var fse = require('fs-extra');
 
 var ls = exports.ls = function(dir, recurse, _allFiles, _path) {
     var file;
@@ -91,7 +91,7 @@ exports.mkPath = function(_path) {
         _path = _path.join('');
     }
 
-    wrench.mkdirSyncRecursive(_path);
+    fse.mkdirsSync(_path);
 };
 
 // adapted from http://procbits.com/2011/11/15/synchronous-file-copy-in-node-js
@@ -106,7 +106,7 @@ exports.copyFileSync = function(inFile, outDir, fileName) {
     var outFile = path.join( outDir, fileName || path.basename(inFile) );
     var pos = 0;
 
-    wrench.mkdirSyncRecursive(outDir);
+    fse.mkdirsSync(outDir);
     read = fs.openSync(inFile, 'r');
     write = fs.openSync(outFile, 'w');
 

lib/jsdoc/opts/args.js

@@ -86,4 +86,5 @@ exports.get = function(name) {
     else if ( hasOwnProp.call(ourOptions, name) ) {
         return ourOptions[name];
     }
+    return undefined;
 };

lib/jsdoc/path.js

@@ -111,25 +111,11 @@ exports.getResourcePath = function(filepath, filename) {
         return true;
     }
 
-    function fileExists(_path) {
-        // see also:
-        // - http://stackoverflow.com/questions/4482686/check-synchronously-if-file-directory-exists-in-node-js
-        // - https://nodejs.org/api/fs.html#fs_fs_existssync_path
-        try {
-            var stats = fs.lstatSync(_path);
-
-            return stats.isFile();
-        }
-        catch (e) {
-            return false;
-        }
-    }
-
     // absolute paths are normalized by path.resolve on the first pass
     [path.dirname(env.opts.configure || ''), env.pwd, env.dirname].forEach(function(_path) {
         if (!result && _path) {
             _path = path.resolve(_path, filepath);
-            if ( pathExists(_path) && (filename ? fileExists(path.join(_path, filename)) : true)) {
+            if ( pathExists(_path) ) {
                 result = _path;
             }
         }