support the modifies tag (JSDoc and Closure Compiler) (jsdoc#605)

Author: hegemonic

lib/jsdoc/schema.js

@@ -436,6 +436,12 @@ var DOCLET_SCHEMA = exports.DOCLET_SCHEMA = {
                 type: STRING
             }
         },
+        modifies: {
+            type: ARRAY,
+            optional: true,
+            uniqueItems: true,
+            items: PARAM_SCHEMA
+        },
         // probably a trailing substring of the path
         name: {
             type: STRING

lib/jsdoc/tag/dictionary/definitions.js

@@ -605,6 +605,13 @@ var baseTags = exports.baseTags = {
             setDocletNameToValue(doclet, tag);
         }
     },
+    modifies: {
+        canHaveType: true,
+        onTagged: function(doclet, tag) {
+            doclet.modifies = doclet.modifies || [];
+            doclet.modifies.push(tag.value);
+        }
+    },
     module: {
         canHaveType: true,
         isNamespace: true,
@@ -910,6 +917,7 @@ exports.closureTags = {
     }),
     lends: cloneTagDef(baseTags.lends),
     license: cloneTagDef(baseTags.license),
+    modifies: cloneTagDef(baseTags.modifies),
     // Closure Compiler only
     noalias: {
         onTagged: ignore

templates/default/tmpl/method.tmpl

@@ -77,6 +77,18 @@ var self = this;
 <?js }); ?></ul>
 <?js } ?>
 
+<?js if (data.modifies && modifies.length) {?>
+<h5>Modifies:</h5>
+<?js if (modifies.length > 1) { ?><ul><?js
+    modifies.forEach(function(m) { ?>
+        <li><?js= self.partial('modifies.tmpl', m) ?></li>
+    <?js });
+?></ul><?js } else {
+    modifies.forEach(function(m) { ?>
+        <?js= self.partial('modifies.tmpl', m) ?>
+    <?js });
+} } ?>
+
 <?js if (data.exceptions && exceptions.length) { ?>
 <h5>Throws:</h5>
 <?js if (exceptions.length > 1) { ?><ul><?js

templates/default/tmpl/modifies.tmpl

@@ -0,0 +1,14 @@
+<?js
+var data = obj || {};
+?>
+
+<?js if (data.type && data.type.names) {?>
+<dl>
+    <dt>
+        Type
+    </dt>
+    <dd>
+        <?js= this.partial('type.tmpl', data.type.names) ?>
+    </dd>
+</dl>
+<?js } ?>

test/fixtures/modifiestag.js

@@ -0,0 +1,5 @@
+/**
+ * My mutator function.
+ * @modifies {(foo|bar)}
+ */
+function mutator(foo, bar) {}

test/specs/tags/modifiestag.js

@@ -0,0 +1,15 @@
+'use strict';
+
+describe('@modifies tag', function() {
+    var docSet = jasmine.getDocSetFromFile('test/fixtures/modifiestag.js');
+    var mutator = docSet.getByLongname('mutator')[0];
+
+    it('should add the specified types to the doclet\'s `modifies` property', function() {
+        expect(mutator.modifies.length).toBe(1);
+        expect(mutator.modifies[0].type).toBeDefined();
+        expect(mutator.modifies[0].type.names).toBeDefined();
+        expect(mutator.modifies[0].type.names.length).toBe(2);
+        expect(mutator.modifies[0].type.names[0]).toBe('foo');
+        expect(mutator.modifies[0].type.names[1]).toBe('bar');
+    });
+});