diff --git a/plugins/markdown.js b/plugins/markdown.js index 3c556a38..a6ad08ac 100644 --- a/plugins/markdown.js +++ b/plugins/markdown.js @@ -1,67 +1,21 @@ /*global env: true */ /** - @overview Translate doclet descriptions from MarkDown into HTML. - @module plugins/markdown - @author Michael Mathews - @author Ben Blank + * @overview Translate doclet descriptions from MarkDown into HTML. + * @module plugins/markdown + * @author Michael Mathews + * @author Ben Blank */ var conf = env.conf.markdown; var defaultTags = [ "classdesc", "description", "params", "properties", "returns" ]; -var parse; +var parse = require('jsdoc/util/markdown').getParser(); var tags; -// Associate parser names with their actual module names. -var parsers = { - evilstreak: "markdown", - gfm: "github-flavored-markdown" -}; - /** - Pull in the selected parser and wrap it in a common interface. - - @param {String} parser The name of the selected parser. - @param {Object} [conf] Configuration for the selected parser, if any. - - @returns {Function} A function which accepts markdown source, feeds it to - the selected parser, and returns the resulting HTML. - - @throws {Exception} If the name does not correspond to a known parser. - */ -function getParser(parser, conf) { - conf = conf || {}; - - if (parser === parsers.gfm) { - parser = require(parser); - - var githubConf = { - repoName: conf.githubRepoName - }; - if (conf.githubRepoOwner && conf.githubRepoName) { - githubConf.nameWithOwner = conf.githubRepoOwner + "/" + conf.githubRepoName; - } - - parser.hardwrap = !!conf.hardwrap; - - return function(source) { - return parser.parse(source, githubConf); - }; - } else if (parser === parsers.evilstreak) { - parser = require(parser).markdown; - - return function(source) { - return parser.toHTML(source, conf.dialect); - }; - } else { - throw "unknown Markdown parser: '" + parser + "'"; - } -} - -/** - Process the markdown source in a doclet. The properties which should be - processed are configurable, but always include "classdesc", "description", - "params", "properties", and "returns". Handled properties can be bare - strings, objects, or arrays of objects. + * Process the markdown source in a doclet. The properties that should be + * processed are configurable, but always include "classdesc", "description", + * "params", "properties", and "returns". Handled properties can be bare + * strings, objects, or arrays of objects. */ function process(doclet) { tags.forEach(function(tag) { @@ -79,17 +33,6 @@ function process(doclet) { }); } -// determine which parser should be used based on configuration options, if any -if (conf && conf.parser) { - parse = getParser(parsers[conf.parser], conf); -} else if (conf && conf.githubRepoOwner && conf.githubRepoName) { - // use GitHub-friendly parser if GitHub-specific options are present - parse = getParser(parsers.gfm, conf); -} else { - // evilstreak is the default parser - parse = getParser(parsers.evilstreak, conf); -} - // set up the list of "tags" (properties) to process if (conf && conf.tags) { tags = conf.tags.slice(); @@ -105,8 +48,8 @@ if (conf && conf.tags) { exports.handlers = { /** - Translate markdown syntax in a new doclet's description into HTML. Is run - by JSDoc 3 whenever a "newDoclet" event fires. + * Translate markdown syntax in a new doclet's description into HTML. Is run + * by JSDoc 3 whenever a "newDoclet" event fires. */ newDoclet: function(e) { process(e.doclet); diff --git a/rhino_modules/jsdoc/readme.js b/rhino_modules/jsdoc/readme.js index c9d46adc..e04ed2cb 100644 --- a/rhino_modules/jsdoc/readme.js +++ b/rhino_modules/jsdoc/readme.js @@ -1,67 +1,25 @@ /*global env: true */ -/** - @overview - @author Michael Mathews - @license Apache License 2.0 - See file 'LICENSE.md' in this project. - */ /** - Make the contents of a README file available to include in the output. - @module jsdoc/readme - @author Michael Mathews - @author Ben Blank + * Make the contents of a README file available to include in the output. + * @module jsdoc/readme + * @author Michael Mathews + * @author Ben Blank */ var fs = require('fs'), - conf = env.conf.markdown; - -function getParser(parser, conf) { - conf = conf || {}; - - if (parser === 'gfm') { - parser = new (require('gfm/showdown').Converter)(); - parser.githubRepoOwner = conf.githubRepoOwner; - parser.githubRepoName = conf.githubRepoName; - parser.hardwrap = !!conf.hardwrap; - - return function(source) { - return parser.makeHtml(source); - }; - } - else if (parser === 'evilstreak') { - parser = require('markdown').markdown; - - return function(source) { - return parser.toHTML(source, conf.dialect); - }; - } - else { - throw 'unknown Markdown parser: "' + parser + '"'; - } -} + markdown = require('jsdoc/util/markdown'); /** - @class - @classdesc Represents a README file. - @param {string} path - The filepath to the README. + * @class + * @classdesc Represents a README file. + * @param {string} path - The filepath to the README. */ function ReadMe(path) { var content = fs.readFileSync(path), - parse; - - // determine which parser should be used based on configuration options, if any - if (conf && conf.parser) { - parse = getParser(conf.parser, conf); - } else if (conf && conf.githubRepoOwner && conf.githubRepoName) { - // use GitHub-friendly parser if GitHub-specific options are present - parse = getParser('gfm', conf); - } else { - // evilstreak is the default parser - parse = getParser('evilstreak', conf); - } + parse = markdown.getParser(); this.html = parse(content); - } module.exports = ReadMe; diff --git a/rhino_modules/jsdoc/tutorial.js b/rhino_modules/jsdoc/tutorial.js index da0ba751..28f794db 100644 --- a/rhino_modules/jsdoc/tutorial.js +++ b/rhino_modules/jsdoc/tutorial.js @@ -4,7 +4,7 @@ @license Apache License 2.0 - See file 'LICENSE.md' in this project. */ -var mdParser = require('markdown').markdown; +var markdown = require('jsdoc/util/markdown'); /** @module jsdoc/tutorial @@ -68,7 +68,8 @@ exports.Tutorial.prototype.parse = function() { // markdown case exports.TYPES.MARKDOWN: - return mdParser.toHTML(this.content) + var mdParse = markdown.getParser(); + return mdParse(this.content) .replace(/&/g, '&') // because markdown escapes these .replace(/</g, '<') .replace(/>/g, '>'); diff --git a/rhino_modules/jsdoc/util/markdown.js b/rhino_modules/jsdoc/util/markdown.js new file mode 100644 index 00000000..08671712 --- /dev/null +++ b/rhino_modules/jsdoc/util/markdown.js @@ -0,0 +1,87 @@ +/*global env: true */ + +/** + * Provides access to Markdown-related functions. + * @module jsdoc/util/markdown + * @author Michael Mathews + * @author Ben Blank + */ + +var conf = env.conf.markdown; + +/** + * Enumeration of Markdown parsers that are available. + * @enum {String} + */ +var parsers = { + /** The "[markdown-js](https://github.com/evilstreak/markdown-js)" (aka "evilstreak") parser. */ + evilstreak: "markdown", + /** + * The "[GitHub-flavored Markdown](https://github.com/hegemonic/github-flavored-markdown)" + * parser. + */ + gfm: "github-flavored-markdown" +}; + +/** + * 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. + * + * @private + * @param {String} parser The name of the selected parser. + * @param {Object} [conf] Configuration for the selected parser, if any. + * @returns {Function} A function that accepts Markdown source, feeds it to the selected parser, and + * returns the resulting HTML. + * @throws {Error} If the name does not correspond to a known parser. + */ +function getParseFunction(parser, conf) { + conf = conf || {}; + + if (parser === parsers.gfm) { + parser = require(parser); + + var githubConf = { + repoName: conf.githubRepoName + }; + if (conf.githubRepoOwner && conf.githubRepoName) { + githubConf.nameWithOwner = conf.githubRepoOwner + "/" + conf.githubRepoName; + } + + parser.hardwrap = !!conf.hardwrap; + + return function(source) { + return parser.parse(source, githubConf); + }; + } else if (parser === parsers.evilstreak) { + parser = require(parser).markdown; + + return function(source) { + // evilstreak parser expects line endings to be \n + source = source.replace(/\r\n|\r/g, '\n'); + return parser.toHTML(source, conf.dialect); + }; + } else { + throw new Error("unknown Markdown parser: '" + parser + "'"); + } +} + +/** + * Retrieve a Markdown parsing function based on the value of the `conf.json` file's + * `env.conf.markdown` property. The parsing function accepts a single parameter containing Markdown + * source. The function uses the parser specified in `conf.json` to transform the Markdown source to + * HTML, then returns the HTML as a string. + * @returns {Function} A function that accepts Markdown source, feeds it to the selected parser, and + * returns the resulting HTML. + * @throws {Error} If the value of `env.conf.markdown.parser` does not correspond to a known parser. + */ +exports.getParser = function() { + if (conf && conf.parser) { + return getParseFunction(parsers[conf.parser], conf); + } else if (conf && conf.githubRepoOwner && conf.githubRepoName) { + // use GitHub-friendly parser if GitHub-specific options are present + return getParseFunction(parsers.gfm, conf); + } else { + // evilstreak is the default parser + return getParseFunction(parsers.evilstreak, conf); + } +};