Added support for @chainable

Squashed commit of the following:

commit ab7299b
Author: Duc Tri Le <[email protected]>
Date:   Mon Feb 22 14:29:55 2016 -0500

    Adding new @chainable tag for methods to use to specify that it is returning itself

Author: Duc Tri Le

lib/jsdoc/augment.js

@@ -455,6 +455,26 @@ function getImplementedAdditions(implDoclets, allDoclets, commentedDoclets) {
     return additions;
 }
 
+// Add a @return tag with the type being the current class
+function augumentChainableMethodReturn(doclets, docs, documented) {
+    doclets.forEach(function(doclet) {
+        var members = getMembers(doclet.longname, docs, ['instance']);
+        if (!members) { return; }
+
+        members.forEach(function(member) {
+            if (member.chainable) {
+                addDocletProperty(
+                    documented[member.longname],
+                    'returns',
+                    [{ type: { names: [member.longname.split('#')[0]] } }]
+                );
+            }
+        });
+    });
+
+    return [];
+}
+
 function augment(doclets, propertyName, docletFinder) {
     var index = doclets.index.longname;
     var dependencies = sort( mapDependencies(index, propertyName) );
@@ -528,6 +548,17 @@ exports.addImplemented = function(doclets) {
     augment(doclets, 'implements', getImplementedAdditions);
 };
 
+/**
+ * Update the doclets for all methods with `@chainable` so that the return type is the current class.
+ *
+ * @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}.
+ * @return {void}
+ */
+exports.addChainableMethodReturn = function(doclets) {
+    augment(doclets, 'chainable', augumentChainableMethodReturn);
+};
+
 /**
  * Add and update doclets to reflect all of the following:
  *
@@ -545,4 +576,5 @@ exports.augmentAll = function(doclets) {
     exports.addInherited(doclets);
     // look for implemented doclets again, in case we inherited an interface
     exports.addImplemented(doclets);
+    exports.addChainableMethodReturn(doclets);
 };

lib/jsdoc/tag/dictionary/definitions.js

@@ -258,6 +258,13 @@ var baseTags = exports.baseTags = {
             doclet.borrow(borrows.target, borrows.source);
         }
     },
+    chainable: {
+        mustNotHaveValue: true,
+        mustNotHaveDescription: true,
+        onTagged: function(doclet, tag) {
+            doclet.chainable = true;
+        }
+    },
     class: {
         onTagged: function(doclet, tag) {
             doclet.addTag('kind', 'class');