From 36065d22e87d40b6440a10ad1184645800c3a30d Mon Sep 17 00:00:00 2001
From: Jeff Williams <jeffrey.l.williams@gmail.com>
Date: Fri, 7 Nov 2014 15:17:52 -0800
Subject: [PATCH] add `exception`/`throws` to default tag list for Markdown
 plugin (#736)

Plus some test refactoring.

Thanks to @otakustay for suggesting this change.
---
 plugins/markdown.js                      | 21 ++++++---
 plugins/test/fixtures/markdown.js        | 24 +++++++++++
 plugins/test/fixtures/seetag-markdown.js | 11 -----
 plugins/test/specs/markdown.js           | 55 ++++++++++++++++--------
 4 files changed, 75 insertions(+), 36 deletions(-)
 create mode 100644 plugins/test/fixtures/markdown.js
 delete mode 100644 plugins/test/fixtures/seetag-markdown.js

diff --git a/plugins/markdown.js b/plugins/markdown.js
index 7c7df69d..91f918d8 100644
--- a/plugins/markdown.js
+++ b/plugins/markdown.js
@@ -1,4 +1,3 @@
-/*global env: true */
 /**
  * @overview Translate doclet descriptions from MarkDown into HTML.
  * @module plugins/markdown
@@ -7,8 +6,16 @@
  */
 'use strict';
 
-var conf = env.conf.markdown;
-var defaultTags = [ 'classdesc', 'description', 'params', 'properties', 'returns', 'see'];
+var config = global.env.conf.markdown || {};
+var defaultTags = [
+    'classdesc',
+    'description',
+    'exceptions',
+    'params',
+    'properties',
+    'returns',
+    'see'
+];
 var hasOwnProp = Object.prototype.hasOwnProperty;
 var parse = require('jsdoc/util/markdown').getParser();
 var tags = [];
@@ -58,12 +65,12 @@ function process(doclet) {
 }
 
 // set up the list of "tags" (properties) to process
-if (conf && conf.tags) {
-    tags = conf.tags.slice();
+if (config.tags) {
+    tags = config.tags.slice();
 }
 // set up the list of default tags to exclude from processing
-if (conf && conf.excludeTags) {
-    excludeTags = conf.excludeTags.slice();
+if (config.excludeTags) {
+    excludeTags = config.excludeTags.slice();
 }
 defaultTags.forEach(function(tag) {
     if (excludeTags.indexOf(tag) === -1 && tags.indexOf(tag) === -1) {
diff --git a/plugins/test/fixtures/markdown.js b/plugins/test/fixtures/markdown.js
new file mode 100644
index 00000000..a727d655
--- /dev/null
+++ b/plugins/test/fixtures/markdown.js
@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * @see [Nowhere](http://nowhere.com)
+ */
+function foo() {}
+
+/**
+ * @see AnObject#myProperty
+ */
+function bar() {}
+
+/**
+ * @classdesc My class.
+ * @description My class.
+ * @exception {Error} Some error.
+ * @param {string} myParam - My parameter.
+ * @property {string} value - Value of myParam.
+ * @return {MyClass} Class instance.
+ * @see [Example Inc.](http://example.com)
+ */
+function MyClass(myParam) {
+	this.value = myParam;
+}
diff --git a/plugins/test/fixtures/seetag-markdown.js b/plugins/test/fixtures/seetag-markdown.js
deleted file mode 100644
index 6aba419f..00000000
--- a/plugins/test/fixtures/seetag-markdown.js
+++ /dev/null
@@ -1,11 +0,0 @@
-/**
-*  @see [Nowhere](http://nowhere.com)
-*/
-function foo() {
-}
-
-/**
-*  @see AnObject#myProperty
-*/
-function bar() {
-}
diff --git a/plugins/test/specs/markdown.js b/plugins/test/specs/markdown.js
index c9d89cc1..af3a0706 100644
--- a/plugins/test/specs/markdown.js
+++ b/plugins/test/specs/markdown.js
@@ -1,29 +1,48 @@
-/*global describe: true, env: true, expect: true, it: true, jasmine: true */
+'use strict';
 
 var path = require('jsdoc/path');
 
-describe("markdown plugin", function() {
-    //TODO
-});
-
-describe("markdown see tag support", function() {
+describe('markdown plugin', function() {
     var pluginPath = 'plugins/markdown';
-    var pluginPathResolved = path.join(env.dirname, pluginPath);
+    var pluginPathResolved = path.join(global.env.dirname, pluginPath);
     var plugin = require(pluginPathResolved);
 
-    var docSet = jasmine.getDocSetFromFile('plugins/test/fixtures/seetag-markdown.js');
-    var foo = docSet.getByLongname('foo')[0];
-    var bar = docSet.getByLongname('bar')[0];
+    var docSet = jasmine.getDocSetFromFile('plugins/test/fixtures/markdown.js');
 
-    it ('should parse @see tags containing links', function() {
-        plugin.handlers.newDoclet({doclet:foo});
-        expect(typeof foo).toEqual('object');
-        expect(foo.see[0]).toEqual('<p><a href="http://nowhere.com">Nowhere</a></p>');
+    // TODO: more tests; refactor the plugin so multiple settings can be tested
+
+    it('should process the correct tags by default', function() {
+        var myClass = docSet.getByLongname('MyClass')[0];
+
+        plugin.handlers.newDoclet({ doclet: myClass });
+        [
+            myClass.classdesc,
+            myClass.description,
+            myClass.exceptions[0].description,
+            myClass.params[0].description,
+            myClass.properties[0].description,
+            myClass.returns[0].description,
+            myClass.see
+        ].forEach(function(value) {
+            // if we processed the value, it should be wrapped in a <p> tag
+            expect( /^<p>(?:.+)<\/p>$/.test(value) ).toBe(true);
+        });
     });
 
-    it ('should not parse @see tags that do not contain links', function() {
-        plugin.handlers.newDoclet({doclet:bar});
-        expect(typeof bar).toEqual('object');
-        expect(bar.see[0]).toEqual('AnObject#myProperty');
+    describe('@see tag support', function() {
+        var foo = docSet.getByLongname('foo')[0];
+        var bar = docSet.getByLongname('bar')[0];
+
+        it('should parse @see tags containing links', function() {
+            plugin.handlers.newDoclet({ doclet: foo });
+            expect(typeof foo).toEqual('object');
+            expect(foo.see[0]).toEqual('<p><a href="http://nowhere.com">Nowhere</a></p>');
+        });
+
+        it('should not parse @see tags that do not contain links', function() {
+            plugin.handlers.newDoclet({ doclet: bar });
+            expect(typeof bar).toEqual('object');
+            expect(bar.see[0]).toEqual('AnObject#myProperty');
+        });
     });
 });