From 2f99af8fbbfb7f19d9f962c40884a13ce38696da Mon Sep 17 00:00:00 2001
From: Jeff Williams <jeffrey.l.williams@gmail.com>
Date: Fri, 21 Jul 2017 17:29:47 -0700
Subject: [PATCH] support the `modifies` tag (JSDoc and Closure Compiler)
 (#605)

---
 lib/jsdoc/schema.js                     |  6 ++++++
 lib/jsdoc/tag/dictionary/definitions.js |  8 ++++++++
 templates/default/tmpl/method.tmpl      | 12 ++++++++++++
 templates/default/tmpl/modifies.tmpl    | 14 ++++++++++++++
 test/fixtures/modifiestag.js            |  5 +++++
 test/specs/tags/modifiestag.js          | 15 +++++++++++++++
 6 files changed, 60 insertions(+)
 create mode 100644 templates/default/tmpl/modifies.tmpl
 create mode 100644 test/fixtures/modifiestag.js
 create mode 100644 test/specs/tags/modifiestag.js

diff --git a/lib/jsdoc/schema.js b/lib/jsdoc/schema.js
index 1b9364d7..8d4c50e6 100644
--- a/lib/jsdoc/schema.js
+++ b/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
diff --git a/lib/jsdoc/tag/dictionary/definitions.js b/lib/jsdoc/tag/dictionary/definitions.js
index 469ddbde..e37e143a 100644
--- a/lib/jsdoc/tag/dictionary/definitions.js
+++ b/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
diff --git a/templates/default/tmpl/method.tmpl b/templates/default/tmpl/method.tmpl
index 718a29ed..0125fe29 100644
--- a/templates/default/tmpl/method.tmpl
+++ b/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
diff --git a/templates/default/tmpl/modifies.tmpl b/templates/default/tmpl/modifies.tmpl
new file mode 100644
index 00000000..16ccbf8d
--- /dev/null
+++ b/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 } ?>
diff --git a/test/fixtures/modifiestag.js b/test/fixtures/modifiestag.js
new file mode 100644
index 00000000..31c24fe1
--- /dev/null
+++ b/test/fixtures/modifiestag.js
@@ -0,0 +1,5 @@
+/**
+ * My mutator function.
+ * @modifies {(foo|bar)}
+ */
+function mutator(foo, bar) {}
diff --git a/test/specs/tags/modifiestag.js b/test/specs/tags/modifiestag.js
new file mode 100644
index 00000000..946a29e4
--- /dev/null
+++ b/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');
+    });
+});