From 5ffaaff61982f177f532cf7af5b803852db2e14f Mon Sep 17 00:00:00 2001
From: mathematicalcoffee <mathematical.coffee@gmail.com>
Date: Fri, 15 Feb 2013 16:27:02 +1000
Subject: [PATCH] added @listens tag (need to add to template too)

---
 lib/jsdoc/tag/dictionary/definitions.js |  9 +++++++++
 test/specs/tags/listenstag.js           | 11 +++++++++++
 2 files changed, 20 insertions(+)
 create mode 100644 test/specs/tags/listenstag.js

diff --git a/lib/jsdoc/tag/dictionary/definitions.js b/lib/jsdoc/tag/dictionary/definitions.js
index db3ca55f..1fff2b14 100644
--- a/lib/jsdoc/tag/dictionary/definitions.js
+++ b/lib/jsdoc/tag/dictionary/definitions.js
@@ -404,6 +404,15 @@ exports.defineTags = function(dictionary) {
             doclet.license = tag.value;
         }
     });
+
+    dictionary.defineTag('listens', {
+        mustHaveValue: true,
+        onTagged: function (doclet, tag) {
+            if (!doclet.listens) { doclet.listens = []; }
+            doclet.listens.push(tag.value);
+            // TODO: verify that parameters match the event parameters?
+        }
+    });
     
     dictionary.defineTag('member', {
         canHaveType: true,
diff --git a/test/specs/tags/listenstag.js b/test/specs/tags/listenstag.js
new file mode 100644
index 00000000..468b0b12
--- /dev/null
+++ b/test/specs/tags/listenstag.js
@@ -0,0 +1,11 @@
+describe("@listens tag", function() {
+    var doclet = require('jsdoc/doclet'),
+        doc = new doclet.Doclet('/** An event handler\n@function handler\n@listens Foo\n@listens Bar */', {});
+
+    it("should create a 'listens' property on the doclet, an array, with the events that are listened to", function() {
+        expect(Array.isArray(doc.listens)).toBeTruthy();
+        expect(doc.listens.length).toBe(2);
+        expect(doc.listens).toContain('Foo');
+        expect(doc.listens).toContain('Bar');
+    });
+});