From 0973e636fc380ac262d6f222071304b24449879d Mon Sep 17 00:00:00 2001 From: mathematicalcoffee Date: Wed, 21 Nov 2012 09:55:13 +1000 Subject: [PATCH 1/3] fix for jsdoc3/jsdoc#259: underscores in {@link} tags should not be touched by the markdown parser --- rhino_modules/jsdoc/util/markdown.js | 15 ++++++++++-- test/specs/jsdoc/util/markdown.js | 34 +++++++++++++++++++++++++--- 2 files changed, 44 insertions(+), 5 deletions(-) diff --git a/rhino_modules/jsdoc/util/markdown.js b/rhino_modules/jsdoc/util/markdown.js index 08671712..26eda361 100644 --- a/rhino_modules/jsdoc/util/markdown.js +++ b/rhino_modules/jsdoc/util/markdown.js @@ -7,8 +7,6 @@ * @author Ben Blank */ -var conf = env.conf.markdown; - /** * Enumeration of Markdown parsers that are available. * @enum {String} @@ -50,12 +48,24 @@ function getParseFunction(parser, conf) { parser.hardwrap = !!conf.hardwrap; return function(source) { + // 1. protect underscores within inline tags {@....} + source = source.replace(/\{@[^}\r\n]+\}/g, function (wholeMatch) { + return wholeMatch.replace(/(^|[^\\])_/g, '$1\\_'); + }); + // 2. send through markdown (the protective '\' will be removed + // by the parser) return parser.parse(source, githubConf); }; } else if (parser === parsers.evilstreak) { parser = require(parser).markdown; return function(source) { + // 1. protect underscores within inline tags {@....} + source = source.replace(/\{@[^}\r\n]+\}/g, function (wholeMatch) { + return wholeMatch.replace(/(^|[^\\])_/g, '$1\\_'); + }); + // 2. send through markdown (the protective '\' will be removed + // by the parser) // evilstreak parser expects line endings to be \n source = source.replace(/\r\n|\r/g, '\n'); return parser.toHTML(source, conf.dialect); @@ -75,6 +85,7 @@ function getParseFunction(parser, conf) { * @throws {Error} If the value of `env.conf.markdown.parser` does not correspond to a known parser. */ exports.getParser = function() { + var conf = env.conf.markdown; if (conf && conf.parser) { return getParseFunction(parsers[conf.parser], conf); } else if (conf && conf.githubRepoOwner && conf.githubRepoName) { diff --git a/test/specs/jsdoc/util/markdown.js b/test/specs/jsdoc/util/markdown.js index 8a56b992..dc492bdb 100644 --- a/test/specs/jsdoc/util/markdown.js +++ b/test/specs/jsdoc/util/markdown.js @@ -30,11 +30,39 @@ describe('jsdoc/util/markdown', function() { }); it('should not apply formatting to inline tags when the evilstreak parser is enabled', function() { - // TODO + // store the old configuration + var old = (env.conf.markdown ? env.conf.markdown.parser : undefined); + env.conf.markdown = {parser: 'evilstreak'}; + + // get the evilstreak parser and do the test + var parser = markdown.getParser(); + expect(parser('{@link MyClass#_x} and {@link MyClass#_y}')).toEqual( + '

{@link MyClass#_x} and {@link MyClass#_y}

'); + + // restore the old value + if (old === undefined) { + env.conf.markdown.parser = old; + } else { + delete env.conf.markdown; + } }); it('should not apply formatting to inline tags when the GFM parser is enabled', function() { - // TODO + // store the old configuration + var old = (env.conf.markdown ? env.conf.markdown.parser : undefined); + env.conf.markdown = {parser: 'gfm'}; + + // get the evilstreak parser and do the test + var parser = markdown.getParser(); + expect(parser('{@link MyClass#_x} and {@link MyClass#_y}')).toEqual( + '

{@link MyClass#_x} and {@link MyClass#_y}

'); + + // restore the old value + if (old === undefined) { + env.conf.markdown.parser = old; + } else { + delete env.conf.markdown; + } }); }); -}); \ No newline at end of file +}); From 280d98f00a36fb574f3504fe06859bb2a8f2a892 Mon Sep 17 00:00:00 2001 From: mathematicalcoffee Date: Wed, 21 Nov 2012 15:52:59 +1000 Subject: [PATCH 2/3] Moved underscore escaping to a dedicated function, fixed typo in test comment (evilstreak -> gfm) --- rhino_modules/jsdoc/util/markdown.js | 27 ++++++++++++++++----------- test/specs/jsdoc/util/markdown.js | 2 +- 2 files changed, 17 insertions(+), 12 deletions(-) diff --git a/rhino_modules/jsdoc/util/markdown.js b/rhino_modules/jsdoc/util/markdown.js index 26eda361..c676352e 100644 --- a/rhino_modules/jsdoc/util/markdown.js +++ b/rhino_modules/jsdoc/util/markdown.js @@ -21,6 +21,20 @@ var parsers = { gfm: "github-flavored-markdown" }; +/** + * Escape underscores that occur within {@ ... } in order to protect them + * from the markdown parser(s). + * @param {String} source the source text to sanitize. + * @returns {String} `source` where underscores within {@ ... } have been + * protected with a preceding backslash (i.e. \_) -- the markdown parsers + * will strip the backslash and protect the underscore. + */ +function escapeUnderscores(source) { + return source.replace(/\{@[^}\r\n]+\}/g, function (wholeMatch) { + return wholeMatch.replace(/(^|[^\\])_/g, '$1\\_'); + }); +} + /** * Retrieve a function that accepts a single parameter containing Markdown source. The function uses * the specified parser to transform the Markdown source to HTML, then returns the HTML as a string. @@ -48,11 +62,7 @@ function getParseFunction(parser, conf) { parser.hardwrap = !!conf.hardwrap; return function(source) { - // 1. protect underscores within inline tags {@....} - source = source.replace(/\{@[^}\r\n]+\}/g, function (wholeMatch) { - return wholeMatch.replace(/(^|[^\\])_/g, '$1\\_'); - }); - // 2. send through markdown (the protective '\' will be removed + source = escapeUnderscores(source); // by the parser) return parser.parse(source, githubConf); }; @@ -60,12 +70,7 @@ function getParseFunction(parser, conf) { parser = require(parser).markdown; return function(source) { - // 1. protect underscores within inline tags {@....} - source = source.replace(/\{@[^}\r\n]+\}/g, function (wholeMatch) { - return wholeMatch.replace(/(^|[^\\])_/g, '$1\\_'); - }); - // 2. send through markdown (the protective '\' will be removed - // by the parser) + source = escapeUnderscores(source); // evilstreak parser expects line endings to be \n source = source.replace(/\r\n|\r/g, '\n'); return parser.toHTML(source, conf.dialect); diff --git a/test/specs/jsdoc/util/markdown.js b/test/specs/jsdoc/util/markdown.js index dc492bdb..f6ae402a 100644 --- a/test/specs/jsdoc/util/markdown.js +++ b/test/specs/jsdoc/util/markdown.js @@ -52,7 +52,7 @@ describe('jsdoc/util/markdown', function() { var old = (env.conf.markdown ? env.conf.markdown.parser : undefined); env.conf.markdown = {parser: 'gfm'}; - // get the evilstreak parser and do the test + // get the gfm parser and do the test var parser = markdown.getParser(); expect(parser('{@link MyClass#_x} and {@link MyClass#_y}')).toEqual( '

{@link MyClass#_x} and {@link MyClass#_y}

'); From bc94dd03aa2424ba472fa8c26680f6ad55c017a2 Mon Sep 17 00:00:00 2001 From: mathematicalcoffee Date: Wed, 21 Nov 2012 15:54:15 +1000 Subject: [PATCH 3/3] oops - left a stub of half of a comment. removed it. --- rhino_modules/jsdoc/util/markdown.js | 1 - 1 file changed, 1 deletion(-) diff --git a/rhino_modules/jsdoc/util/markdown.js b/rhino_modules/jsdoc/util/markdown.js index c676352e..0711d4d9 100644 --- a/rhino_modules/jsdoc/util/markdown.js +++ b/rhino_modules/jsdoc/util/markdown.js @@ -63,7 +63,6 @@ function getParseFunction(parser, conf) { return function(source) { source = escapeUnderscores(source); - // by the parser) return parser.parse(source, githubConf); }; } else if (parser === parsers.evilstreak) {