Merge pull request #297 from phasmal/add-see-tag-support

Added support for @see tag in markdown plugin

plugins/markdown.js

@@ -5,9 +5,8 @@
  * @author Michael Mathews <micmath@gmail.com>
  * @author Ben Blank <ben.blank@gmail.com>
  */
-
 var conf = env.conf.markdown;
-var defaultTags = [ "classdesc", "description", "params", "properties", "returns" ];
+var defaultTags = [ "classdesc", "description", "params", "properties", "returns", "see"];
 var parse = require('jsdoc/util/markdown').getParser();
 var tags = [];
 var excludeTags = [];
@@ -24,10 +23,18 @@ function process(doclet) {
             return;
         }
 
-        if (typeof doclet[tag] === "string") {
+        if (typeof doclet[tag] === "string" &&
+              (tag != 'see' ||
+                  // treat '@see' specially, since we only want to process @see text that contains links
+                  (tag == 'see' && doclet[tag].indexOf('[') != -1))) {
             doclet[tag] = parse(doclet[tag]);
         } else if (doclet[tag] instanceof Array) {
-            doclet[tag].forEach(process);
+            doclet[tag].forEach(function(value, index, original){
+                var inner = {};
+                inner[tag] = value;
+                process(inner);
+                original[index] = inner[tag];
+            });
         } else if (doclet[tag]) {
             process(doclet[tag]);
         }
@@ -56,4 +63,4 @@ exports.handlers = {
     newDoclet: function(e) {
         process(e.doclet);
     }
-};
+};

plugins/test/fixtures/seetag-markdown.js

@@ -0,0 +1,12 @@
+/**
+*  @see [Nowhere](http://nowhere.com)
+*/
+function foo() {
+}
+
+/**
+*  @see AnObject#myProperty
+*/
+function bar() {
+}
+

plugins/test/specs/markdown.js

@@ -1,3 +1,22 @@
 describe("markdown plugin", function() {
-    // TODO
+    //TODO
+});
+
+describe("markdown see tag support", function() {
+    var plugin = require('plugins/markdown'),
+        docSet = jasmine.getDocSetFromFile('plugins/test/fixtures/seetag-markdown.js'),
+        foo = docSet.getByLongname('foo')[0],
+        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');
+    })
 });