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

replace GFM parser; package.json cleanup

Browse Source
This commit is contained in:
Jeff Williams 2012-10-16 09:16:20 -07:00
parent 508e4776cb
commit 3c8437b9d9
7 changed files with 124 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
Jake/templates/package.json.tmpl
View File

@ -17,6 +17,7 @@
}
],
"dependencies": {
"github-flavored-markdown": "git://github.com/hegemonic/github-flavored-markdown.git",
"js2xmlparser": "0.1.0",
"jsMD5": "git://github.com/hegemonic/jsMD5.git",
"markdown": "0.4.0",
@ -28,11 +29,11 @@
"jshint": "0.9.1"
},
"bugs": "https://github.com/jsdoc3/jsdoc/issues",
"author": {
"name": "Michael Mathews",
"email": "micmath@gmail.com"
},
"contributors" : [
{
"name": "Michael Mathews",
"email": "micmath@gmail.com"
},
{
"name": "Rafa\u0105 Wrzeszcz",
"email": "rafal.wrzeszcz@wrzasq.pl"
@ -43,10 +44,6 @@
}
],
"maintainers": [
{
"name": "Michael Mathews",
"email": "micmath@gmail.com"
},
{
"name": "Jannon Frank",
"email": "jannon@jannon.net"

2
node_modules/github-flavored-markdown/.npmignore generated vendored Normal file
View File

@ -0,0 +1,2 @@
_site
.DS_Store

21
node_modules/github-flavored-markdown/package.json generated vendored Normal file
View File

@ -0,0 +1,21 @@
{
"name": "github-flavored-markdown",
"version": "1.0.1",
"description": "The port of Showdown used on github.com",
"author": {
"name": "tekkup",
"email": "git@tekkub.net",
"url": "http://tekkub.net/"
},
"main": "./scripts/showdown.js",
"repository": {
"type": "git",
"url": "http://github.com/isaacs/github-flavored-markdown"
},
"readme": "See:\n[github-flavored-markdown](http://github.github.com/github-flavored-markdown/)\n\nAs an npm package:\n\n npm install github-flavored-markdown\n\nAnd then in your node program:\n\n var ghm = require(\"github-flavored-markdown\")\n ghm.parse(\"I **love** GHM.\\n\\n#2\", \"isaacs/npm\")\n // returns:\n // '<p>I <strong>love</strong> GHM. '+\n // '<a href=\\'http://github.com/isaacs/npm/issues/#issue/2\\'>#2</a></p>'\n\nTo get the sha/issue/fork links, pass in a second argument specifying\nthe current project that things should be relative to.\n",
"_id": "github-flavored-markdown@1.0.1",
"dist": {
"shasum": "2811101367391ff989a14d58e88c79f0c4169ce4"
},
"_from": "git://github.com/hegemonic/github-flavored-markdown.git"
}

83
nodejs_modules/gfm/showdown.js → node_modules/github-flavored-markdown/scripts/showdown.js generated vendored
View File

@ -68,18 +68,42 @@
// Modifications are tagged with "GFM"
// **************************************************
// ==================================================
// CommonJS modifications by benblank
// http://www.commonjs.org/specs/modules/1.0/
// **************************************************
// Node.JS port by Isaac Z. Schlueter
//
// Modifications are tagged with "CJS"
// ==================================================
// Modifications are tagged with "isaacs"
// **************************************************
// **************************************************
// Line-breaking modifications by benblank
//
// Modifications are tagged with "benblank"
// **************************************************
//
// Showdown namespace
//
var Showdown = {};
//
// isaacs: export the Showdown object
//
if (typeof exports === "object") {
Showdown = exports;
// isaacs: expose top-level parse() method, like other to-html parsers.
Showdown.parse = function (md, gh) {
var converter = new Showdown.converter();
return converter.makeHtml(md, gh);
};
}
//
// isaacs: Declare "GitHub" object in here, since Node modules
// execute in a closure or separate context, rather than right
// in the global scope. If in the browser, this does nothing.
//
var GitHub;
//
// converter
//
@ -101,10 +125,16 @@ var g_html_blocks;
// (see _ProcessListItems() for details):
var g_list_level = 0;
// == CJS == Allow hardwrapping to be disabled.
// benblank - Allow hardwrapping to be disabled.
var g_hardwrap;
this.makeHtml = function(text) {
// isaacs - Allow passing in the GitHub object as an argument.
this.makeHtml = function(text, gh) {
if (typeof gh !== "undefined") {
if (typeof gh === "string") gh = {nameWithOwner:gh};
GitHub = gh;
}
//
// Main function. The order in which other subs are called here is
// essential. Link and image substitutions need to happen before
@ -120,7 +150,7 @@ this.makeHtml = function(text) {
g_titles = new Array();
g_html_blocks = new Array();
// == CJS == Allow hardwrapping to be disabled.
// benblank - Allow hardwrapping to be disabled.
g_hardwrap = typeof this.hardwrap === "undefined" || this.hardwrap;
// attacklab: Replace ~ with ~T
@ -166,18 +196,11 @@ this.makeHtml = function(text) {
// attacklab: Restore tildes
text = text.replace(/~T/g,"~");
// == CJS == Create local `GitHub` object for use by GFM
var GitHub = this.githubRepoName && this.githubRepoOwner ? {
nameWithOwner: this.githubRepoOwner + "/" + this.githubRepoName,
repoName: this.githubRepoName
} : typeof window !== "undefined" ? window.GitHub : undefined;
// ** GFM ** Auto-link URLs and emails
text = text.replace(/https?\:\/\/[^"\s\<\>]*[^.,;'">\:\s\<\>\)\]\!]/g, function(wholeMatch,matchIndex){
var left = text.slice(0, matchIndex), right = text.slice(matchIndex)
if (left.match(/<[^>]+$/) && right.match(/^[^>]*>/)) {return wholeMatch}
href = wholeMatch.replace(/^http:\/\/github.com\//, "https://github.com/")
return "<a href='" + href + "'>" + wholeMatch + "</a>";
return "<a href='" + wholeMatch + "'>" + wholeMatch + "</a>";
});
text = text.replace(/[a-z0-9_\-+=.]+@[a-z0-9\-]+(\.[a-z0-9-]+)+/ig, function(wholeMatch){return "<a href='mailto:" + wholeMatch + "'>" + wholeMatch + "</a>";});
@ -437,6 +460,7 @@ var _RunBlockGamut = function(text) {
text = text.replace(/^[ ]{0,2}([ ]?\_[ ]?){3,}[ \t]*$/gm,key);
text = _DoLists(text);
text = _DoCodeFencing(text);
text = _DoCodeBlocks(text);
text = _DoBlockQuotes(text);
@ -968,6 +992,28 @@ var _DoCodeBlocks = function(text) {
return text;
}
//
// Code Fencing is a GitHub flavored MD concept. Basically you can wrap
// your code like this:
//
// ```{language}
// {code}
// ```
//
// Where {language} is the language of the code (useful for coloring code)
// and {code} is your code
//
var _DoCodeFencing = function(text) {
text = text.replace(/`{3}(?:(.*$)\n)?([\s\S]*?)`{3}/gm,
function(wholeMatch,m1,m2){
//HTML for this is copied from GitHub directly for compatibility, except the lang="" attribute
var codeblock = '<div class="highlight"><pre lang="'+m1+'">'+m2+'</pre></div>';
return codeblock;
}
)
return text;
}
var hashBlock = function(text) {
text = text.replace(/(^\n+|\n+$)/g,"");
return "\n\n~K" + (g_html_blocks.push(text)-1) + "K\n\n";
@ -1145,7 +1191,7 @@ var _FormParagraphs = function(text) {
}
else if (str.search(/\S/) >= 0) {
str = _RunSpanGamut(str);
// == CJS == Allow hardwrapping to be disabled.
// benblank - Allow hardwrapping to be disabled.
if (g_hardwrap) str = str.replace(/\n/g,"<br />"); // ** GFM **
str = str.replace(/^([ \t]*)/g,"<p>");
str += "</p>"
@ -1379,6 +1425,3 @@ var escapeCharacters_callback = function(wholeMatch,m1) {
}
} // end of Showdown.converter
// == CJS == Export the converter
if (typeof exports !== "undefined") exports.Converter = Showdown.converter;

15
package.json
View File

@ -1,7 +1,7 @@
{
"name": "JSDoc",
"version": "3.0.0",
"revision": "1350399199104",
"revision": "1350403484637",
"description": "An automatic documentation generator for javascript.",
"keywords": [ "documentation", "javascript" ],
"licenses": [
@ -17,6 +17,7 @@
}
],
"dependencies": {
"github-flavored-markdown": "git://github.com/hegemonic/github-flavored-markdown.git",
"js2xmlparser": "0.1.0",
"jsMD5": "git://github.com/hegemonic/jsMD5.git",
"markdown": "0.4.0",
@ -28,11 +29,11 @@
"jshint": "0.9.1"
},
"bugs": "https://github.com/jsdoc3/jsdoc/issues",
"author": {
"name": "Michael Mathews",
"email": "micmath@gmail.com"
},
"contributors" : [
{
"name": "Michael Mathews",
"email": "micmath@gmail.com"
},
{
"name": "Rafa\u0105 Wrzeszcz",
"email": "rafal.wrzeszcz@wrzasq.pl"
@ -43,10 +44,6 @@
}
],
"maintainers": [
{
"name": "Michael Mathews",
"email": "micmath@gmail.com"
},
{
"name": "Jannon Frank",
"email": "jannon@jannon.net"

28
plugins/markdown.js
View File

@ -11,6 +11,12 @@ var defaultTags = [ "classdesc", "description", "params", "properties", "returns
var parse;
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.
@ -25,17 +31,19 @@ var tags;
function getParser(parser, conf) {
conf = conf || {};
if (parser === "gfm") {
parser = new (require("gfm/showdown").Converter)();
parser.githubRepoOwner = conf.githubRepoOwner;
parser.githubRepoName = conf.githubRepoName;
if (parser === parsers.gfm) {
parser = require(parser);
var githubConf = {
nameWithOwner: conf.githubRepoOwner + "/" + conf.githubRepoName,
repoName: conf.githubRepoName
};
parser.hardwrap = !!conf.hardwrap;
return function(source) {
return parser.makeHtml(source);
return parser.parse(source, githubConf);
};
} else if (parser === "evilstreak") {
parser = require("markdown").markdown;
} else if (parser === parsers.evilstreak) {
parser = require(parser).markdown;
return function(source) {
return parser.toHTML(source, conf.dialect);
@ -69,13 +77,13 @@ function process(doclet) {
// determine which parser should be used based on configuration options, if any
if (conf && conf.parser) {
parse = getParser(conf.parser, conf);
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("gfm", conf);
parse = getParser(parsers.gfm, conf);
} else {
// evilstreak is the default parser
parse = getParser("evilstreak", conf);
parse = getParser(parsers.evilstreak, conf);
}
// set up the list of "tags" (properties) to process

18
plugins/markdown.md
View File

@ -1,6 +1,6 @@
# How to use the Markdown plugin
For most users, all you need to do is add the plugin to your JSDoc configuration (`conf.json`) as you would any other, by adding a reference to it in the "plugins" entry of the configuration JSON:
For most users, all you need to do is add the plugin to your JSDoc configuration (`conf.json`) as you would any other, by adding a reference to the plugin in the `"plugins"` entry:
...
"plugins": [ "plugins/markdown" ]
@ -12,7 +12,7 @@ Also, be sure to use leading asterisks in your doc comments! If you omit the lea
# Configuring the Markdown plugin
The plugin also offers several configuration options for advanced users who want GitHub integration, extended tag support, etc. All configuration for the Markdown plugin should be added to a `"markdown"` property in your JSDoc configuration:
The plugin also offers several configuration options for advanced users who want GitHub integration, extended tag support, etc. All configuration for the Markdown plugin should be added to a `"markdown"` property in your JSDoc configuration:
...
"plugins": [ "plugins/markdown" ],
@ -37,7 +37,7 @@ The plugin currently supports two Markdown parsers. You can select which parser
### Dominic "evilstreak" Baggott's markdown-js
The default parser is Dominic Baggott's excellent [markdown-js](https://github.com/evilstreak/markdown-js). It can be explicitly selected by setting the `parser` to `evilstreak` and has one additional (and optional) configuration option, `dialect`, which can be used to select which of markdown-js' built-in dialects to use. If omitted, markdown-js' default dialect will be used.
The default parser is Dominic Baggott's excellent [markdown-js](https://github.com/evilstreak/markdown-js). It can be explicitly selected by setting the `parser` to `evilstreak` and has one additional (and optional) configuration option, `dialect`, which can be used to select which of markdown-js' built-in dialects to use. If omitted, markdown-js' default dialect will be used.
...
"plugins": [ "plugins/markdown" ],
@ -50,11 +50,11 @@ The default parser is Dominic Baggott's excellent [markdown-js](https://github.c
### GitHib Flavored Markdown
The alternative parser is the modified Showdown parser supplied by GitHub for their [GitHub Flavored Markdown](http://github.github.com/github-flavored-markdown/). GFM several enhancements to standard Markdown syntax (see its documentation) intended to be useful to developers. It *also* has the ability to quickly link to GitHub repositories, files, and issues. It can be selected by setting the `parser` to `gfm` and supports three additional (and optional) configuration options.
The alternative parser is the modified Showdown parser supplied by GitHub for their [GitHub Flavored Markdown](http://github.github.com/github-flavored-markdown/). GFM provides several enhancements to standard Markdown syntax (see its documentation) intended to be useful to developers. It *also* has the ability to quickly link to GitHub repositories, files, and issues. It can be selected by setting the `parser` to `gfm` and supports three additional (and optional) configuration options.
The `hardwrap` option controls the hard wrapping of line ends. Unlike standard Markdown, GFM considers a single newline to indicate a "hard break" in the paragraph, but this doesn't work well with the line length limitations commonly used with comment documentation, so is disabled by default. If you want to turn hard wrapping back on, set `hardwrap` to `true` (or any non-falsy value).
The `hardwrap` option controls the hard wrapping of line ends. Unlike standard Markdown, GFM considers a single newline to indicate a "hard break" in the paragraph, but this doesn't work well with the line length limitations commonly used with comment documentation, so is disabled by default. If you want to turn hard wrapping back on, set `hardwrap` to `true` (or any non-falsy value).
The `githubRepoName` and `githubRepoOwner` indicate which GitHub repo should be used for GitHub links which do not fully specify a repo. These options have no effect unless used together and if they are omitted, several of GFM's default link types will be unavailable. Conversely, if you supply both `github*` options but do not explicitly select `gfm` as your parser, it will be automatically selected for you.
The `githubRepoName` and `githubRepoOwner` indicate which GitHub repo should be used for GitHub links that do not fully specify a repo. These options have no effect unless used together, and if they are omitted, several of GFM's default link types will be unavailable. Conversely, if you supply both `github*` options but do not explicitly select `gfm` as your parser, it will be automatically selected for you.
...
"plugins": [ "plugins/markdown" ],
@ -67,13 +67,13 @@ The `githubRepoName` and `githubRepoOwner` indicate which GitHub repo should be
### Why two parsers?
The "evilstreak" parser is flexible, extensible, currently-maintained, and was the only parser available in earlier versions of the Markdown plugin, but doesn't support the useful GFM extensions. The "gfm" parser is based on the no-longer-maintained Showdown parser, but is the actual library used for GitHub's [client-side previews](http://github.github.com/github-flavored-markdown/preview.html).
The "evilstreak" parser is flexible, extensible, currently maintained, and was the only parser available in earlier versions of the Markdown plugin, but doesn't support the useful GFM extensions. The "gfm" parser is based on the no-longer-maintained Showdown parser, but it provides GFM extensions.
In the future, if GFM support is made available for the "evilstreak" parser, this plugin will drop the "gfm" parser in favor of that support.
## Extended tag support
While the Markdown plugin already supports JSDoc's default tags, if you're using other plugins, you may well have extra tags available. You can tell the Markdown plugin to handle those extra tags as well using the `tags` property, which is an array of the tags* it should check in addition to the default set.
While the Markdown plugin already supports JSDoc's default tags, if you're using other plugins, you may well have extra tags available. You can tell the Markdown plugin to handle those extra tags as well using the `tags` property, which is an array of the tags* it should check in addition to the default set.
...
"plugins": [ "plugins/markdown" ],
@ -83,4 +83,4 @@ While the Markdown plugin already supports JSDoc's default tags, if you're using
}
...
\* Because the Markdown plugin works with JSDoc's internal representation rather than with the source comments, the names you need to enter in the `tags` property aren't necessarily the same as the actual tag names. For example, in the default set of tags, `@param` is stored under `params`. If you are having trouble getting the Markdown plugin to work with your extra tags, either take a peek at the output of JSDoc's `--explain` command-line parameter (which displays the internal state which plugins work with) or ask the plugin author which "doclet properties" their plugin uses. The Markdown plugin supports strings, arrays, and objects/subdoclets.
\* Because the Markdown plugin works with JSDoc's internal representation rather than with the source comments, the names you need to enter in the `tags` property aren't necessarily the same as the actual tag names. For example, in the default set of tags, `@param` is stored under `params`. If you are having trouble getting the Markdown plugin to work with your extra tags, either take a peek at the output of JSDoc's `--explain` command-line parameter (which displays the internal state that plugins work with) or ask the plugin author which "doclet properties" their plugin uses. The Markdown plugin supports strings, arrays, and objects/subdoclets.