Merge branch 'master' into esrijs-sdk-3.6.0

* master: (95 commits)
  update dependencies and supported Node.js versions
  3.5.5 changelog
  Prefer copyFileSync from here over native (jsdoc#1440)
  upgrade Babylon
  fix test breakage
  3.5.4 changelog
  prevent crash when an anonymous class is passed as a parameter (jsdoc#1416)
  hide the signature in the heading for classes with hidden constructors (jsdoc#1397)
  chore(package): update nyc to version 11.1.0 (jsdoc#1417)
  add `templates.useShortNamesInLinks` config option (jsdoc#738)
  allow users to specify a highlighter for Markdown code blocks (jsdoc#1412)
  document `longnamesToTree`, plus other doc improvements (jsdoc#43)
  move namespaces and interfaces up in the nav (jsdoc#1410)
  don't pretty-print code blocks that begin with "```plain" (jsdoc#1361)
  improve comment
  make the `exports` tag work correctly when combined with the `enum` tag (jsdoc#970)
  fix Node.js 4.x
  update tested Node.js versions
  use the markdown-it Markdown parser by default (jsdoc#1243)
  enable more Babylon options (jsdoc#1411)
  ...

# Conflicts:
#	.travis.yml
#	README.md
#	lib/jsdoc/src/astbuilder.js
#	lib/jsdoc/src/visitor.js
#	lib/jsdoc/util/markdown.js
#	lib/jsdoc/util/templateHelper.js
#	package.json

Author: lheberlie

.travis.yml

@@ -4,5 +4,7 @@ node_js:
   - "4"
   - "6"
   - "8"
+  - "10"
+  - "12"
 
 install: npm install -g gulp; npm install

README.md

@@ -10,8 +10,8 @@ Want to contribute to JSDoc? Please read `CONTRIBUTING.md`.
 Installation and Usage
 ----------------------
 
-JSDoc supports Node.js 4.2.0 and later. You can install JSDoc globally or in your project's
-`node_modules` folder.
+JSDoc supports stable versions of Node.js 8.15.0 and later. You can install JSDoc globally or in
+your project's `node_modules` folder.
 
 To install the latest version on npm globally (may require `sudo`; [learn how to fix
 this](https://docs.npmjs.com/getting-started/fixing-npm-permissions)):

cli.js

@@ -374,8 +374,6 @@ cli.parseFiles = function() {
     packageDocs.files = env.sourceFiles || [];
     docs.push(packageDocs);
 
-    logger.debug('Indexing doclets...');
-    borrow.indexAll(docs);
     logger.debug('Adding inherited symbols, mixins, and interface implementations...');
     augment.augmentAll(docs);
     logger.debug('Adding borrowed doclets...');

gulpfile.js

@@ -32,31 +32,39 @@ var options = {
     nodePath: process.execPath
 };
 
-gulp.task('bump', function() {
+function bump(cb) {
     gulp.src('./package.json')
         .pipe(jsonEditor({
             revision: String( Date.now() )
         }))
         .pipe(gulp.dest('./'));
-});
 
-gulp.task('coverage', function(cb) {
+    cb();
+}
+
+function coverage(cb) {
     var cmd = util.format('./node_modules/.bin/nyc --reporter=html %s -T', options.nodeBin);
 
     exec(cmd, execCb.bind(null, cb));
-});
+}
 
-gulp.task('lint', function() {
-    return gulp.src(options.lintPaths)
+function lint(cb) {
+    gulp.src(options.lintPaths)
         .pipe(eslint())
         .pipe(eslint.formatEach())
         .pipe(eslint.failOnError());
-});
 
-gulp.task('test', function(cb) {
+    cb();
+}
+
+function test(cb) {
     var cmd = util.format('%s "%s" -T', options.nodePath, options.nodeBin);
 
     exec(cmd, execCb.bind(null, cb));
-});
+}
 
-gulp.task('default', ['lint', 'test']);
+exports.bump = bump;
+exports.coverage = coverage;
+exports.default = gulp.series(lint, test);
+exports.lint = lint;
+exports.test = test;

lib/jsdoc/augment.js

@@ -6,6 +6,9 @@
  */
 
 var doop = require('jsdoc/util/doop');
+var jsdoc = {
+    doclet: require('jsdoc/doclet')
+};
 var name = require('jsdoc/name');
 
 var hasOwnProp = Object.prototype.hasOwnProperty;
@@ -75,20 +78,24 @@ function sort(dependencies) {
 }
 
 function getMembers(longname, docs, scopes) {
-    var candidate;
+    var memberof = docs.index.memberof[longname] || [];
     var members = [];
 
-    for (var i = 0, l = docs.length; i < l; i++) {
-        candidate = docs[i];
-
-        if (candidate.memberof === longname && scopes.indexOf(candidate.scope) !== -1) {
+    memberof.forEach(function(candidate) {
+        if (scopes.indexOf(candidate.scope) !== -1) {
             members.push(candidate);
         }
-    }
+    });
 
     return members;
 }
 
+function getDocumentedLongname(longname, docs) {
+    var doclets = docs.index.documented[longname] || [];
+
+    return doclets[doclets.length - 1];
+}
+
 function addDocletProperty(doclets, propName, value) {
     for (var i = 0, l = doclets.length; i < l; i++) {
         doclets[i][propName] = value;
@@ -162,6 +169,25 @@ function updateDocumentedDoclets(doclet, documented) {
     documented[doclet.longname].push(doclet);
 }
 
+/**
+ * Update the index of doclets with a `memberof` value.
+ *
+ * @private
+ * @param {module:jsdoc/doclet.Doclet} doclet - The doclet to be added to the index.
+ * @param {Object.<string, Array.<module:jsdoc/doclet.Doclet>>} memberof - The index of doclets
+ * with a `memberof` value.
+ * @return {void}
+ */
+function updateMemberofDoclets(doclet, memberof) {
+    if (doclet.memberof) {
+        if ( !hasOwnProp.call(memberof, doclet.memberof) ) {
+            memberof[doclet.memberof] = [];
+        }
+
+        memberof[doclet.memberof].push(doclet);
+    }
+}
+
 function explicitlyInherits(doclets) {
     var doclet;
     var inherits = false;
@@ -177,13 +203,24 @@ function explicitlyInherits(doclets) {
     return inherits;
 }
 
+function changeMemberof(longname, newMemberof) {
+    var atoms = name.shorten(longname);
+
+    atoms.memberof = newMemberof;
+
+    return name.combine(atoms);
+}
+
 // TODO: try to reduce overlap with similar methods
-function getInheritedAdditions(doclets, docs, documented) {
+function getInheritedAdditions(doclets, docs, index) {
     var additionIndexes;
     var additions = [];
+    var childDoclet;
+    var childLongname;
     var doc;
+    var parentDoclet;
+    var parentMembers;
     var parents;
-    var members;
     var member;
     var parts;
 
@@ -199,54 +236,64 @@ function getInheritedAdditions(doclets, docs, documented) {
             additionIndexes = {};
 
             for (var j = 0, jj = parents.length; j < jj; j++) {
-                members = getMembers(parents[j], docs, ['instance']);
+                parentMembers = getMembers(parents[j], docs, ['instance']);
+
+                for (var k = 0, kk = parentMembers.length; k < kk; k++) {
+                    parentDoclet = parentMembers[k];
 
-                for (var k = 0, kk = members.length; k < kk; k++) {
                     // We only care about symbols that are documented.
-                    if (members[k].undocumented) {
+                    if (parentDoclet.undocumented) {
                         continue;
                     }
 
-                    member = doop(members[k]);
+                    childLongname = changeMemberof(parentDoclet.longname, doc.longname);
+                    childDoclet = getDocumentedLongname(childLongname, docs) || {};
+
+                    // We don't want to fold in properties from the child doclet if it had an
+                    // `@inheritdoc` tag.
+                    if (hasOwnProp.call(childDoclet, 'inheritdoc')) {
+                        childDoclet = {};
+                    }
+
+                    member = jsdoc.doclet.combine(childDoclet, parentDoclet);
 
                     if (!member.inherited) {
                         member.inherits = member.longname;
                     }
                     member.inherited = true;
 
-                    // TODO: this will fail on longnames like: MyClass#"quoted#Longname"
-                    // and nested instance members like: MyClass#MyOtherClass#myMethod;
-                    // switch to updateLongname()!
                     member.memberof = doc.longname;
-                    parts = member.longname.split('#');
-                    parts[0] = doc.longname;
-                    member.longname = parts.join('#');
+                    parts = name.shorten(member.longname);
+                    parts.memberof = doc.longname;
+                    member.longname = name.combine(parts);
 
                     // Indicate what the descendant is overriding. (We only care about the closest
                     // ancestor. For classes A > B > C, if B#a overrides A#a, and C#a inherits B#a,
                     // we don't want the doclet for C#a to say that it overrides A#a.)
                     if ( hasOwnProp.call(docs.index.longname, member.longname) ) {
-                        member.overrides = members[k].longname;
+                        member.overrides = parentDoclet.longname;
                     }
                     else {
                         delete member.overrides;
                     }
 
                     // Add the ancestor's docs unless the descendant overrides the ancestor AND
                     // documents the override.
-                    if ( !hasOwnProp.call(documented, member.longname) ) {
+                    if ( !hasOwnProp.call(index.documented, member.longname) ) {
                         updateAddedDoclets(member, additions, additionIndexes);
-                        updateDocumentedDoclets(member, documented);
+                        updateDocumentedDoclets(member, index.documented);
+                        updateMemberofDoclets(member, index.memberof);
                     }
                     // If the descendant used an @inheritdoc or @override tag, add the ancestor's
                     // docs, and ignore the existing doclets.
-                    else if ( explicitlyInherits(documented[member.longname]) ) {
+                    else if ( explicitlyInherits(index.documented[member.longname]) ) {
                         // Ignore any existing doclets. (This is safe because we only get here if
                         // `member.longname` is an own property of `documented`.)
-                        addDocletProperty(documented[member.longname], 'ignore', true);
+                        addDocletProperty(index.documented[member.longname], 'ignore', true);
 
                         updateAddedDoclets(member, additions, additionIndexes);
-                        updateDocumentedDoclets(member, documented);
+                        updateDocumentedDoclets(member, index.documented);
+                        updateMemberofDoclets(member, index.memberof);
 
                         // Remove property that's no longer accurate.
                         if (member.virtual) {
@@ -263,8 +310,8 @@ function getInheritedAdditions(doclets, docs, documented) {
                     // If the descendant overrides the ancestor and documents the override,
                     // update the doclets to indicate what the descendant is overriding.
                     else {
-                        addDocletProperty(documented[member.longname], 'overrides',
-                            members[k].longname);
+                        addDocletProperty(index.documented[member.longname], 'overrides',
+                            parentDoclet.longname);
                     }
                 }
             }
@@ -304,9 +351,10 @@ function updateMixes(mixedDoclet, mixedLongname) {
 }
 
 // TODO: try to reduce overlap with similar methods
-function getMixedInAdditions(mixinDoclets, allDoclets, commentedDoclets) {
+function getMixedInAdditions(mixinDoclets, allDoclets, index) {
     var additionIndexes;
     var additions = [];
+    var commentedDoclets = index.documented;
     var doclet;
     var mixedDoclet;
     var mixedDoclets;
@@ -346,6 +394,7 @@ function getMixedInAdditions(mixinDoclets, allDoclets, commentedDoclets) {
 
                     updateAddedDoclets(mixedDoclet, additions, additionIndexes);
                     updateDocumentedDoclets(mixedDoclet, commentedDoclets);
+                    updateMemberofDoclets(mixedDoclet, index.memberof);
                 }
             }
         }
@@ -371,14 +420,18 @@ function updateImplements(implDoclets, implementedLongname) {
 }
 
 // TODO: try to reduce overlap with similar methods
-function getImplementedAdditions(implDoclets, allDoclets, commentedDoclets) {
+function getImplementedAdditions(implDoclets, allDoclets, index) {
     var additionIndexes;
     var additions = [];
+    var childDoclet;
+    var childLongname;
+    var commentedDoclets = index.documented;
     var doclet;
     var implementations;
     var implExists;
     var implementationDoclet;
     var interfaceDoclets;
+    var parentDoclet;
 
     // interfaceDoclets will be undefined if the implemented symbol isn't documented
     implDoclets = implDoclets || [];
@@ -395,15 +448,26 @@ function getImplementedAdditions(implDoclets, allDoclets, commentedDoclets) {
                 interfaceDoclets = getMembers(implementations[j], allDoclets, ['instance']);
 
                 for (var k = 0, kk = interfaceDoclets.length; k < kk; k++) {
+                    parentDoclet = interfaceDoclets[k];
+
                     // We only care about symbols that are documented.
-                    if (interfaceDoclets[k].undocumented) {
+                    if (parentDoclet.undocumented) {
                         continue;
                     }
 
-                    implementationDoclet = doop(interfaceDoclets[k]);
+                    childLongname = changeMemberof(parentDoclet.longname, doclet.longname);
+                    childDoclet = getDocumentedLongname(childLongname, allDoclets) || {};
+
+                    // We don't want to fold in properties from the child doclet if it had an
+                    // `@inheritdoc` tag.
+                    if (hasOwnProp.call(childDoclet, 'inheritdoc')) {
+                        childDoclet = {};
+                    }
+
+                    implementationDoclet = jsdoc.doclet.combine(childDoclet, parentDoclet);
 
                     reparentDoclet(doclet, implementationDoclet);
-                    updateImplements(implementationDoclet, interfaceDoclets[k].longname);
+                    updateImplements(implementationDoclet, parentDoclet.longname);
 
                     // If there's no implementation, move along.
                     implExists = hasOwnProp.call(allDoclets.index.longname,
@@ -416,6 +480,7 @@ function getImplementedAdditions(implDoclets, allDoclets, commentedDoclets) {
                     if ( !hasOwnProp.call(commentedDoclets, implementationDoclet.longname) ) {
                         updateAddedDoclets(implementationDoclet, additions, additionIndexes);
                         updateDocumentedDoclets(implementationDoclet, commentedDoclets);
+                        updateMemberofDoclets(implementationDoclet, index.memberof);
                     }
                     // If the implementation used an @inheritdoc or @override tag, add the
                     // interface's docs, and ignore the existing doclets.
@@ -428,6 +493,7 @@ function getImplementedAdditions(implDoclets, allDoclets, commentedDoclets) {
 
                         updateAddedDoclets(implementationDoclet, additions, additionIndexes);
                         updateDocumentedDoclets(implementationDoclet, commentedDoclets);
+                        updateMemberofDoclets(implementationDoclet, index.memberof);
 
                         // Remove property that's no longer accurate.
                         if (implementationDoclet.virtual) {
@@ -445,7 +511,7 @@ function getImplementedAdditions(implDoclets, allDoclets, commentedDoclets) {
                     // indicate what the implementation is implementing.
                     else {
                         updateImplements(commentedDoclets[implementationDoclet.longname],
-                            interfaceDoclets[k].longname);
+                            parentDoclet.longname);
                     }
                 }
             }
@@ -460,7 +526,7 @@ function augment(doclets, propertyName, docletFinder) {
     var dependencies = sort( mapDependencies(index, propertyName) );
 
     dependencies.forEach(function(depName) {
-        var additions = docletFinder(index[depName], doclets, doclets.index.documented);
+        var additions = docletFinder(index[depName], doclets, doclets.index);
 
         additions.forEach(function(addition) {
             var longname = addition.longname;
@@ -481,7 +547,7 @@ function augment(doclets, propertyName, docletFinder) {
  * calling this method creates a new doclet for `ClassB#myMethod`.
  *
  * @param {!Array.<module:jsdoc/doclet.Doclet>} doclets - The doclets generated by JSDoc.
- * @param {!Object} doclets.index - The doclet index added by {@link module:jsdoc/borrow.indexAll}.
+ * @param {!Object} doclets.index - The doclet index.
  * @return {void}
  */
 exports.addInherited = function(doclets) {
@@ -500,7 +566,7 @@ exports.addInherited = function(doclets) {
  * creates a new doclet for the instance method `ClassA#myMethod`.
  *
  * @param {!Array.<module:jsdoc/doclet.Doclet>} doclets - The doclets generated by JSDoc.
- * @param {!Object} doclets.index - The doclet index added by {@link module:jsdoc/borrow.indexAll}.
+ * @param {!Object} doclets.index - The doclet index.
  * @return {void}
  */
 exports.addMixedIn = function(doclets) {
@@ -521,7 +587,7 @@ exports.addMixedIn = function(doclets) {
  * generate a new doclet that reflects the interface's documentation for `InterfaceA#myMethod`.
  *
  * @param {!Array.<module:jsdoc/doclet.Doclet>} docs - The doclets generated by JSDoc.
- * @param {!Object} doclets.index - The doclet index added by {@link module:jsdoc/borrow.indexAll}.
+ * @param {!Object} doclets.index - The doclet index.
  * @return {void}
  */
 exports.addImplemented = function(doclets) {