Merge remote-tracking branch 'origin/master' into releases/3.3

Conflicts:
	package.json

.eslintrc

@@ -101,7 +101,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
 

README.md

@@ -115,10 +115,12 @@ 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).
++ ~~Post questions to the [JSDoc Users mailing list](http://groups.google.com/group/jsdoc-users).~~
+(temporarily unavailable)
++ Post questions tagged `jsdoc` to [Stack
+Overflow](http://stackoverflow.com/questions/tagged/jsdoc).
 
 License
 -------

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

lib/jsdoc/doclet.js

@@ -394,8 +394,13 @@ Doclet.prototype.setMeta = function(meta) {
             /** The type of the symbol in the source code. */
             this.meta.code.type = meta.code.type;
         }
+        // the AST node is only enumerable in debug mode, which reduces clutter for the
+        // --explain/-X option
         if (meta.code.node) {
-            this.meta.code.node = meta.code.node;
+            Object.defineProperty(this.meta.code, 'node', {
+                value: meta.code.node,
+                enumerable: global.env.opts.debug ? true : false
+            });
         }
         if (meta.code.funcscope) {
             this.meta.code.funcscope = meta.code.funcscope;

lib/jsdoc/src/astnode.js

@@ -258,12 +258,15 @@ var getInfo = exports.getInfo = function(node) {
     var info = {};
 
     switch (node.type) {
-        // like: "foo = 'bar'" (after foo has been declared)
+        // like: "foo = 'bar'" (after declaring foo)
+        // like: "MyClass.prototype.myMethod = function() {}" (after declaring MyClass)
         case Syntax.AssignmentExpression:
             info.node = node.right;
             info.name = nodeToString(node.left);
             info.type = info.node.type;
             info.value = nodeToString(info.node);
+            // if the assigned value is a function, we need to capture the parameter names here
+            info.paramnames = getParamNames(node.right);
             break;
 
         // like: "function foo() {}"

lib/jsdoc/src/handlers.js

@@ -86,8 +86,20 @@ exports.attachTo = function(parser) {
         var memberofName = null,
             newDoclet = getNewDoclet(docletSrc, e);
 
-        // an undocumented symbol right after a virtual comment? rhino mistakenly connected the two
-        if (newDoclet.name) { // there was a @name in comment
+        // A JSDoc comment can define a symbol name by including:
+        //
+        // + A `@name` tag
+        // + Another tag that accepts a name, such as `@function`
+        //
+        // When the JSDoc comment defines a symbol name, we treat it as a "virtual comment" for a
+        // symbol that isn't actually present in the code. And if a virtual comment is attached to
+        // a symbol, it's quite possible that the comment and symbol have nothing to do with one
+        // another.
+        //
+        // As a result, if we create a doclet for a `symbolFound` event, and we've already added a
+        // name attribute by parsing the JSDoc comment, we need to create a new doclet that ignores
+        // the attached JSDoc comment and only looks at the code.
+        if (newDoclet.name) {
             // try again, without the comment
             e.comment = '@undocumented';
             newDoclet = getNewDoclet(e.comment, e);

lib/jsdoc/tag.js

@@ -123,7 +123,6 @@ var Tag = exports.Tag = function(tagTitle, tagBody, meta) {
     if (this.text) {
         try {
             processTagText(this, tagDef);
-            jsdoc.tag.validator.validate(this, tagDef, meta);
         }
         catch (e) {
             // probably a type-parsing error
@@ -136,4 +135,6 @@ var Tag = exports.Tag = function(tagTitle, tagBody, meta) {
             );
         }
     }
+
+    jsdoc.tag.validator.validate(this, tagDef, meta);
 };

lib/jsdoc/tag/dictionary/definitions.js

@@ -8,6 +8,7 @@
  */
 'use strict';
 
+var hasOwnProp = Object.prototype.hasOwnProperty;
 var jsdoc = {
     name: require('jsdoc/name'),
     src: {
@@ -96,9 +97,12 @@ function setDocletDescriptionToValue(doclet, tag) {
 
 function setDocletTypeToValueType(doclet, tag) {
     if (tag.value && tag.value.type) {
-        // add the type names and other type properties (such as `optional`)
+        // Add the type names and other type properties (such as `optional`).
+        // Don't overwrite existing properties.
         Object.keys(tag.value).forEach(function(prop) {
-            doclet[prop] = tag.value[prop];
+            if ( !hasOwnProp.call(doclet, prop) ) {
+                doclet[prop] = tag.value[prop];
+            }
         });
     }
 }
@@ -380,17 +384,6 @@ exports.defineTags = function(dictionary) {
         }
     });
 
-    dictionary.defineTag('exception', {
-        mustHaveValue: true,
-        canHaveType: true,
-        onTagged: function(doclet, tag) {
-            if (!doclet.exceptions) { doclet.exceptions = []; }
-            doclet.exceptions.push(tag.value);
-            setDocletTypeToValueType(doclet, tag);
-        }
-    })
-    .synonym('throws');
-
     dictionary.defineTag('exports', {
         mustHaveValue: true,
         onTagged: function(doclet, tag) {
@@ -698,6 +691,17 @@ exports.defineTags = function(dictionary) {
         }
     });
 
+    dictionary.defineTag('throws', {
+        mustHaveValue: true,
+        canHaveType: true,
+        onTagged: function(doclet, tag) {
+            if (!doclet.exceptions) { doclet.exceptions = []; }
+            doclet.exceptions.push(tag.value);
+            setDocletTypeToValueType(doclet, tag);
+        }
+    })
+    .synonym('exception');
+
     dictionary.defineTag('tutorial', {
         mustHaveValue: true,
         onTagged: function(doclet, tag) {

lib/jsdoc/util/markdown.js

@@ -1,4 +1,4 @@
-/*global env: true */
+/*global env */
 
 /**
  * Provides access to Markdown-related functions.
@@ -8,6 +8,8 @@
  */
 'use strict';
 
+var util = require('util');
+
 /**
  * Enumeration of Markdown parsers that are available.
  * @enum {String}
@@ -64,6 +66,18 @@ function unescapeUrls(source) {
     return source.replace(/(https?)\:\\\/\\\//g, '$1://');
 }
 
+/**
+ * Escape characters in text within a code block.
+ *
+ * @param {string} source - The source text to escape.
+ * @return {string} The escaped source text.
+ */
+function escapeCode(source) {
+    return source.replace(/</g, '&lt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
 /**
  * Retrieve a function that accepts a single parameter containing Markdown source. The function uses
  * the specified parser to transform the Markdown source to HTML, then returns the HTML as a string.
@@ -86,14 +100,17 @@ function getParseFunction(parserName, conf) {
     if (parserName === parserNames.marked) {
         // Marked generates an "id" attribute for headers; this custom renderer suppresses it
         markedRenderer = new marked.Renderer();
-        markedRenderer.heading = function(text, level) {
-            var util = require('util');
 
+        markedRenderer.heading = function(text, level) {
             return util.format('<h%s>%s</h%s>', level, text, level);
         };
+
         // Allow prettyprint to work on inline code samples
         markedRenderer.code = function(code, language) {
-          return '<pre class="prettyprint source"><code>' + code + '</code></pre>';
+            var langClass = language ? ' lang-' + language : '';
+
+            return util.format( '<pre class="prettyprint source%s"><code>%s</code></pre>',
+                langClass, escapeCode(code) );
         };
 
         parserFunction = function(source) {

lib/jsdoc/util/templateHelper.js

@@ -141,6 +141,11 @@ function hasUrlPrefix(text) {
     return (/^(http|ftp)s?:\/\//).test(text);
 }
 
+function isComplexTypeExpression(expr) {
+    // record types, type unions, and type applications all count as "complex"
+    return expr.search(/[{(|]/) !== -1 || expr.search(/</) > 0;
+}
+
 /**
  * Build an HTML link to the symbol with the specified longname. If the longname is not
  * associated with a URL, this method simply returns the link text, if provided, or the longname.
@@ -185,7 +190,7 @@ function buildLink(longname, linkText, options) {
     }
     // handle complex type expressions that may require multiple links
     // (but skip anything that looks like an inline tag)
-    else if (longname && longname.search(/[<{(]/) !== -1 && /\{\@.+\}/.test(longname) === false) {
+    else if (longname && isComplexTypeExpression(longname) && /\{\@.+\}/.test(longname) === false) {
         parsedType = parseType(longname);
         return stringifyType(parsedType, options.cssClass, options.linkMap);
     }
@@ -435,19 +440,19 @@ var find = exports.find = function(data, spec) {
 };
 
 /**
- * Check whether a symbol is a function and is the only symbol exported by a module (as in
+ * Check whether a symbol is the only symbol exported by a module (as in
  * `module.exports = function() {};`).
  *
  * @private
  * @param {module:jsdoc/doclet.Doclet} doclet - The doclet for the symbol.
- * @return {boolean} `true` if the symbol is a function and is the only symbol exported by a module;
- * otherwise, `false`.
+ * @return {boolean} `true` if the symbol is the only symbol exported by a module; otherwise,
+ * `false`.
  */
-function isModuleFunction(doclet) {
+function isModuleExports(doclet) {
     var MODULE_PREFIX = require('jsdoc/name').MODULE_PREFIX;
 
     return doclet.longname && doclet.longname === doclet.name &&
-        doclet.longname.indexOf(MODULE_PREFIX) === 0 && doclet.kind === 'function';
+        doclet.longname.indexOf(MODULE_PREFIX) === 0 && doclet.kind !== 'module';
 }
 
 /**
@@ -480,7 +485,7 @@ exports.getMembers = function(data) {
 
     // functions that are also modules (as in "module.exports = function() {};") are not globals
     members.globals = members.globals.filter(function(doclet) {
-        return !isModuleFunction(doclet);
+        return !isModuleExports(doclet);
     });
 
     return members;
@@ -737,7 +742,7 @@ exports.createLink = function(doclet) {
     }
 
     // the doclet gets its own HTML file
-    if ( containers.indexOf(doclet.kind) !== -1 || isModuleFunction(doclet) ) {
+    if ( containers.indexOf(doclet.kind) !== -1 || isModuleExports(doclet) ) {
         filename = getFilename(longname);
     }
     // mistagged version of a doclet that gets its own HTML file