From 427a46177da8fea42d15c8b7d5a771c8fac631bd Mon Sep 17 00:00:00 2001 From: phasmal Date: Thu, 3 Jan 2013 11:43:46 +1100 Subject: [PATCH 1/4] Added support for @see tag in markdown plugin, including adding 'see' to default list and fixing recursion into Arrays --- plugins/markdown.js | 21 ++++++++++++++------- plugins/test/fixtures/seetag-markdown.js | 12 ++++++++++++ plugins/test/specs/markdown.js | 21 ++++++++++++++++++++- 3 files changed, 46 insertions(+), 8 deletions(-) create mode 100644 plugins/test/fixtures/seetag-markdown.js diff --git a/plugins/markdown.js b/plugins/markdown.js index a6ad08aca..cf5945521 100644 --- a/plugins/markdown.js +++ b/plugins/markdown.js @@ -5,9 +5,8 @@ * @author Michael Mathews * @author Ben Blank */ - 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; @@ -22,12 +21,20 @@ function process(doclet) { if (!doclet.hasOwnProperty(tag)) { 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); - } else if (doclet[tag]) { + 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]); } }); @@ -54,4 +61,4 @@ exports.handlers = { newDoclet: function(e) { process(e.doclet); } -}; \ No newline at end of file +}; diff --git a/plugins/test/fixtures/seetag-markdown.js b/plugins/test/fixtures/seetag-markdown.js new file mode 100644 index 000000000..571376169 --- /dev/null +++ b/plugins/test/fixtures/seetag-markdown.js @@ -0,0 +1,12 @@ +/** +* @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 c7c6db8e9..13bb0cebc 100644 --- a/plugins/test/specs/markdown.js +++ b/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('

Nowhere

'); + }) + + 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'); + }) }); \ No newline at end of file From 20a4bb43b035f336710a716c16e8f3b16c8f9b75 Mon Sep 17 00:00:00 2001 From: phasmal Date: Thu, 3 Jan 2013 12:38:27 +1100 Subject: [PATCH 2/4] Fixed jshint-clean issues reported on github --- plugins/test/specs/markdown.js | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/plugins/test/specs/markdown.js b/plugins/test/specs/markdown.js index 13bb0cebc..ce08324fb 100644 --- a/plugins/test/specs/markdown.js +++ b/plugins/test/specs/markdown.js @@ -1,22 +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'); + 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('

Nowhere

'); - }) - - 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'); - }) + }) + + 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'); + }) }); \ No newline at end of file From 554917137bf7a08f6a8b13da8c04849d207faa20 Mon Sep 17 00:00:00 2001 From: phasmal Date: Thu, 3 Jan 2013 12:38:27 +1100 Subject: [PATCH 3/4] Fixed jshint-clean issues reported on github .. again --- plugins/markdown.js | 22 +++++++++++----------- plugins/test/specs/markdown.js | 30 +++++++++++++++--------------- 2 files changed, 26 insertions(+), 26 deletions(-) diff --git a/plugins/markdown.js b/plugins/markdown.js index cf5945521..702318bd8 100644 --- a/plugins/markdown.js +++ b/plugins/markdown.js @@ -21,20 +21,20 @@ function process(doclet) { if (!doclet.hasOwnProperty(tag)) { return; } - - 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))) { + + 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(function(value, index, original){ - var inner = {} - inner[tag] = value - process(inner) - original[index] = inner[tag] - }); - } else if (doclet[tag]) { + var inner = {}; + inner[tag] = value; + process(inner); + original[index] = inner[tag]; + }); + } else if (doclet[tag]) { process(doclet[tag]); } }); diff --git a/plugins/test/specs/markdown.js b/plugins/test/specs/markdown.js index 13bb0cebc..ce08324fb 100644 --- a/plugins/test/specs/markdown.js +++ b/plugins/test/specs/markdown.js @@ -1,22 +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'); + 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('

Nowhere

'); - }) - - 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'); - }) + }) + + 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'); + }) }); \ No newline at end of file From d7ea22b6f2b1a4c6235044f380cf1c9cd0d56349 Mon Sep 17 00:00:00 2001 From: phasmal Date: Thu, 3 Jan 2013 13:14:51 +1100 Subject: [PATCH 4/4] removed some tab chars --- plugins/markdown.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/markdown.js b/plugins/markdown.js index 702318bd8..a6b92d194 100644 --- a/plugins/markdown.js +++ b/plugins/markdown.js @@ -23,7 +23,7 @@ function process(doclet) { } if (typeof doclet[tag] === "string" && - (tag != 'see' || + (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]);