From 9e5a47f195dba3bff8452ebc81988cc4f00c58ec Mon Sep 17 00:00:00 2001
From: Jeff Williams <jeffrey.l.williams@gmail.com>
Date: Wed, 23 Jan 2013 22:56:21 -0800
Subject: [PATCH] add '@callback' tag (#260)

---
 lib/jsdoc/tag/dictionary/definitions.js | 14 +++++++++++--
 test/fixtures/callbacktag.js            | 21 +++++++++++++++++++
 test/specs/documentation/callback.js    | 27 +++++++++++++++++++++++++
 3 files changed, 60 insertions(+), 2 deletions(-)
 create mode 100644 test/fixtures/callbacktag.js
 create mode 100644 test/specs/documentation/callback.js

diff --git a/lib/jsdoc/tag/dictionary/definitions.js b/lib/jsdoc/tag/dictionary/definitions.js
index e7c0a320..db3ca55f 100644
--- a/lib/jsdoc/tag/dictionary/definitions.js
+++ b/lib/jsdoc/tag/dictionary/definitions.js
@@ -625,12 +625,22 @@ exports.defineTags = function(dictionary) {
                 if (tag.value.name) {
                     doclet.addTag('name', tag.value.name);
                 }
-                if (tag.value.type) {
+
+                // callbacks are always type {function}
+                if (tag.originalTitle === 'callback') {
+                    doclet.type = {
+                        names: [
+                            'function'
+                        ]
+                    };
+                }
+                else if (tag.value.type) {
                     doclet.type = tag.value.type;
                 }
             }
         }
-    });
+    })
+    .synonym('callback');
     
     dictionary.defineTag('undocumented', {
         mustNotHaveValue: true,
diff --git a/test/fixtures/callbacktag.js b/test/fixtures/callbacktag.js
new file mode 100644
index 00000000..5dd468d5
--- /dev/null
+++ b/test/fixtures/callbacktag.js
@@ -0,0 +1,21 @@
+/**
+ * @param {requestResponseCallback} cb
+ */
+function makeSpecialRequest(cb) {
+}
+
+/**
+ * @param {wrongTypeCallback} cb
+ */
+function makeExtraSpecialRequest(cb) {
+}
+
+/**
+ * @callback requestResponseCallback
+ * @param {number} responseCode
+ * @param {string} responseText
+ */
+
+/**
+ * @callback {(object|string)} wrongTypeCallback
+ */
\ No newline at end of file
diff --git a/test/specs/documentation/callback.js b/test/specs/documentation/callback.js
new file mode 100644
index 00000000..d8e14412
--- /dev/null
+++ b/test/specs/documentation/callback.js
@@ -0,0 +1,27 @@
+/*global describe: true, expect: true, it: true, jasmine: true */
+describe('callback tag', function() {
+    var docSet = jasmine.getDocSetFromFile('test/fixtures/callbacktag.js');
+
+    function callbackTests(callback) {
+        expect(callback).toBeDefined();
+
+        expect(callback.type).toBeDefined();
+        expect(typeof callback.type).toEqual('object');
+
+        expect(callback.type.names).toBeDefined();
+        expect(callback.type.names instanceof Array).toEqual(true);
+        expect(callback.type.names.length).toEqual(1);
+
+        expect(callback.type.names[0]).toEqual('function');
+    }
+
+    it('correctly handles callbacks that do not define a {type}', function() {
+        var callback = docSet.getByLongname('requestResponseCallback')[0];
+        callbackTests(callback);
+    });
+
+    it('correctly handles callbacks that define an incorrect {type}', function() {
+        var callback = docSet.getByLongname('wrongTypeCallback')[0];
+        callbackTests(callback);
+    });
+});