add '@callback' tag (#260)

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,

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
+ */

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);
+    });
+});