archive-gh-me/jsdoc
1
0
Fork 0
mirror of https://github.com/jsdoc/jsdoc.git synced 2025-12-08 19:46:11 +00:00
Code Issues Projects Releases Wiki Activity

Merge branch 'markdown-refactor'

Browse Source 
Conflicts:
	plugins/markdown.js
	rhino_modules/jsdoc/readme.js
	rhino_modules/jsdoc/tutorial.js
This commit is contained in:
Jeff Williams 2012-10-19 21:34:44 -07:00
commit cab6e29ebd
4 changed files with 110 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
plugins/markdown.js
View File

@ -1,69 +1,21 @@
/*global env: true */
/**
@overview Translate doclet descriptions from MarkDown into HTML.
@module plugins/markdown
@author Michael Mathews <micmath@gmail.com>
@author Ben Blank <ben.blank@gmail.com>
* @overview Translate doclet descriptions from MarkDown into HTML.
* @module plugins/markdown
* @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 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) {
// filters EOL of source so evilstreak/markdown doesn't screw the pooch.
source = source.replace(/(\r\n|\n|\r)/g, '\n');
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) {
@ -81,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();
@ -107,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);

62
rhino_modules/jsdoc/readme.js
View File

@ -1,69 +1,25 @@
/*global env: true */
/**
@overview
@author Michael Mathews <micmath@gmail.com>
@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 <micmath@gmail.com>
@author Ben Blank <ben.blank@gmail.com>
* Make the contents of a README file available to include in the output.
* @module jsdoc/readme
* @author Michael Mathews <micmath@gmail.com>
* @author Ben Blank <ben.blank@gmail.com>
*/
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) {
// filters EOL of source so evilstreak/markdown doesn't screw the pooch.
source = source.replace(/(\r\n|\n|\r)/g, '\n');
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;

7
rhino_modules/jsdoc/tutorial.js
View File

@ -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,9 +68,8 @@ exports.Tutorial.prototype.parse = function() {
// markdown
case exports.TYPES.MARKDOWN:
// filters EOL of source so evilstreak/markdown doesn't screw the pooch.
this.content = this.content.replace(/(\r\n|\n|\r)/g, '\n');
return mdParser.toHTML(this.content)
var mdParse = markdown.getParser();
return mdParse(this.content)
.replace(/&amp;/g, '&') // because markdown escapes these
.replace(/&lt;/g, '<')
.replace(/&gt;/g, '>');

87
rhino_modules/jsdoc/util/markdown.js Normal file
View File

@ -0,0 +1,87 @@
/*global env: true */
/**
* Provides access to Markdown-related functions.
* @module jsdoc/util/markdown
* @author Michael Mathews <micmath@gmail.com>
* @author Ben Blank <ben.blank@gmail.com>
*/
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);
}
};