From 71e60860d9905cc1a45d5fe5f1c47243bb0b5a1d Mon Sep 17 00:00:00 2001
From: Michael Mathews <micmath@gmail.com>
Date: Sat, 15 Jan 2011 22:04:35 +0000
Subject: [PATCH] Added support for the @exception tag.

---
 main.js                                     |  2 +-
 modules/jsdoc/tag/dictionary/definitions.js | 30 ++++++++++++++-------
 test/cases/exceptiontag.js                  | 20 ++++++++++++++
 test/runner.js                              |  1 +
 test/t/cases/exceptiontag.js                | 20 ++++++++++++++
 5 files changed, 63 insertions(+), 10 deletions(-)
 create mode 100644 test/cases/exceptiontag.js
 create mode 100644 test/t/cases/exceptiontag.js

diff --git a/main.js b/main.js
index 9d981b42..c38b3e2a 100644
--- a/main.js
+++ b/main.js
@@ -159,7 +159,7 @@ function main() {
         require('jsdoc/src/handlers').attachTo(app.jsdoc.parser);
         
         docs = app.jsdoc.parser.parse(sourceFiles, env.opts.encoding);
-//dump(docs); exit(0);
+dump(docs); exit(0);
         if (env.opts.expel) {
             dump(docs);
             exit(0);
diff --git a/modules/jsdoc/tag/dictionary/definitions.js b/modules/jsdoc/tag/dictionary/definitions.js
index bd43520c..cf9df00b 100644
--- a/modules/jsdoc/tag/dictionary/definitions.js
+++ b/modules/jsdoc/tag/dictionary/definitions.js
@@ -52,15 +52,6 @@
         .synonym('extends')
         .synonym('mixes');
         
-        dictionary.defineTag('copyright', {
-            musHaveValue: true,
-            onTagged: function(doclet, tag) {
-                doclet.copyright = tag.value;
-                
-                return true;
-            }
-        });
-        
         dictionary.defineTag('class', {
             onTagged: function(doclet, tag) { // @class implies @constructor
                 doclet.addTag('kind', 'constructor');
@@ -80,6 +71,15 @@
         })
         .synonym('const');
         
+        dictionary.defineTag('copyright', {
+            musHaveValue: true,
+            onTagged: function(doclet, tag) {
+                doclet.copyright = tag.value;
+                
+                return true;
+            }
+        });
+        
         dictionary.defineTag('constructor', {
             onTagged: function(doclet, tag) {
                 setDocletKindToTitle(doclet, tag);
@@ -120,6 +120,18 @@
             mustHaveValue: true
         });
         
+        dictionary.defineTag('exception', {
+            mustHaveValue: true,
+            canHaveType: true,
+            onTagged: function(doclet, tag) {
+                if (!doclet.exceptions) { doclet.exceptions = []; }
+                doclet.exceptions.push(tag.value);
+                
+                return false;
+            }
+        })
+        .synonym('throws');
+        
         dictionary.defineTag('file', {
             mustHaveValue: true,
             onTagged: function(doclet, tag) {
diff --git a/test/cases/exceptiontag.js b/test/cases/exceptiontag.js
new file mode 100644
index 00000000..14d7d9a7
--- /dev/null
+++ b/test/cases/exceptiontag.js
@@ -0,0 +1,20 @@
+/**
+    @throws {InvalidArgumentException}
+*/
+function foo(x) {
+    
+}
+
+/**
+    @exception Will throw an error if argument is null.
+*/
+function bar(x) {
+    
+}
+
+/**
+    @exception {DivideByZero} Argument x must be non-zero.
+*/
+function pez(x) {
+    
+}
\ No newline at end of file
diff --git a/test/runner.js b/test/runner.js
index 000852bf..6dc2f0f1 100644
--- a/test/runner.js
+++ b/test/runner.js
@@ -93,6 +93,7 @@ testFile('test/t/cases/accesstag.js');
 testFile('test/t/cases/authortag.js');
 testFile('test/t/cases/copyrighttag.js');
 testFile('test/t/cases/deprecatedtag.js');
+testFile('test/t/cases/exceptiontag.js');
 testFile('test/t/cases/globaltag.js');
 
 report();
diff --git a/test/t/cases/exceptiontag.js b/test/t/cases/exceptiontag.js
new file mode 100644
index 00000000..de0ce730
--- /dev/null
+++ b/test/t/cases/exceptiontag.js
@@ -0,0 +1,20 @@
+(function() {
+    var docSet = testhelpers.getDocSetFromFile('test/cases/exceptiontag.js'),
+        foo = docSet.getByLongname('foo')[0],
+        bar = docSet.getByLongname('bar')[0],
+        pez = docSet.getByLongname('pez')[0];
+    
+    //dump(docSet.doclets);
+    
+    test('When a symbol has an @exception tag, the doclet has a exception property set to that value.', function() {
+        assert.equal(typeof foo.exceptions, 'object');
+        assert.equal(foo.exceptions.length, 1);
+        
+        assert.equal(typeof bar.exceptions, 'object');
+        assert.equal(bar.exceptions.length, 1);
+        
+        assert.equal(typeof pez.exceptions, 'object');
+        assert.equal(pez.exceptions.length, 1);
+    });
+
+})();
\ No newline at end of file