Merge branch 'master' into docs-plugin-error-reporting

jsdoc.js

@@ -113,6 +113,7 @@ function main() {
     var exampleConf;
     var filter;
     var i;
+    var info;
     var l;
     var packageDocs;
     var packageJson;
@@ -215,6 +216,11 @@ function main() {
     } else if (env.opts.test) {
         include('test/runner.js');
         process.exit(0);
+    } else if (env.opts.version) {
+        info = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf8'));
+        info.revision = new Date(parseInt(info.revision, 10)).toUTCString();
+        console.log('JSDoc ' + info.version + ' (' + info.revision + ')');
+        process.exit(0);
     }
 
     if (env.conf.plugins) {

lib/jsdoc/opts/args.js

@@ -79,6 +79,7 @@ argParser.addOption('h', 'help',        false, 'Print this message and quit.');
 argParser.addOption('X', 'explain',     false, 'Dump all found doclet internals to console and quit.');
 argParser.addOption('q', 'query',       true,  'A query string to parse and store in env.opts.query. Example: foo=bar&baz=true', false, parseQuery);
 argParser.addOption('u', 'tutorials',   true,  'Directory in which JSDoc should search for tutorials.');
+argParser.addOption('v', 'version',     false, 'Display the version number and quit.');
 
 //TODO [-R, recurseonly] = a number representing the depth to recurse
 //TODO [-f, filter] = a regex to filter on <-- this can be better defined in the configs?

lib/jsdoc/util/markdown.js

@@ -48,6 +48,7 @@ function escapeUnderscores(source) {
  */
 function getParseFunction(parser, conf) {
     conf = conf || {};
+    var parse;
 
     if (parser === parsers.gfm) {
         parser = require(parser);
@@ -61,19 +62,23 @@ function getParseFunction(parser, conf) {
 
         parser.hardwrap = !!conf.hardwrap;
 
-        return function(source) {
+        parse = function(source) {
             source = escapeUnderscores(source);
             return parser.parse(source, githubConf);
         };
+        parse._parser = parsers.gfm;
+        return parse;
     } else if (parser === parsers.evilstreak) {
         parser = require(parser).markdown;
 
-        return function(source) {
+        parse = function(source) {
             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);
         };
+        parse._parser = parsers.evilstreak;
+        return parse;
     } else {
         throw new Error("unknown Markdown parser: '" + parser + "'");
     }

node_modules/github-flavored-markdown/scripts/showdown.js

@@ -151,7 +151,7 @@ this.makeHtml = function(text, gh) {
 	g_html_blocks = new Array();
 
 	// benblank - Allow hardwrapping to be disabled.
-	g_hardwrap = typeof this.hardwrap === "undefined" || this.hardwrap;
+	g_hardwrap = (typeof exports.hardwrap === "undefined" || exports.hardwrap);
 
 	// attacklab: Replace ~ with ~T
 	// This lets us use tilde as an escape char to avoid md5 hashes

test/specs/jsdoc/opts/args.js

@@ -233,6 +233,20 @@ describe("jsdoc/opts/args", function() {
             expect(r.nocolor).toEqual(true);
         });
 
+        it("should accept a '-v' option and return an object with a 'version' property", function() {
+            args.parse(['-v']);
+            var r = args.get();
+
+            expect(r.version).toEqual(true);
+        });
+
+        it("should accept a '--version' option and return an object with a 'version' property", function() {
+            args.parse(['--version']);
+            var r = args.get();
+
+            expect(r.version).toEqual(true);
+        });
+
         it("should accept a naked option (i.e. no '-') and return an object with a '_' property", function() {
             args.parse(['myfile1', 'myfile2']);
             var r = args.get();
@@ -242,4 +256,4 @@ describe("jsdoc/opts/args", function() {
 
         //TODO: tests for args that must have values
     });
-});
+});

test/specs/jsdoc/util/markdown.js

@@ -13,56 +13,148 @@ describe('jsdoc/util/markdown', function() {
 	});
 
 	describe('getParser', function() {
-		xit('should retrieve a function when called with default settings', function() {
-			// TODO
+        // couple of convenience functions letting me set conf variables and restore
+        // them back to the originals later.
+        function setMarkdownConf(hash) {
+            if (!env.conf.markdown) {
+                env.conf.markdown = {};
+            }
+            var keys = Object.keys(hash);
+            var storage = {};
+            for (var i = 0; i < keys.length; ++i) {
+                storage[keys[i]] = env.conf.markdown[keys[i]];
+                // works because hash[key] is a scalar not an array/object
+                env.conf.markdown[keys[i]] = hash[keys[i]];
+            }
+            return storage;
+        }
+
+        function restoreMarkdownConf(storage) {
+            var keys = Object.keys(storage);
+            for (var i = 0; i < keys.length; ++i) {
+                env.conf.markdown[keys[i]] = storage[keys[i]];
+            }
+            if (keys.length === 0) {
+                delete env.conf.markdown;
+            }
+        }
+
+		it('should retrieve a function when called with default settings', function() {
+            var storage = setMarkdownConf({parser: 'evilstreak'});
+
+            var parser = markdown.getParser();
+            expect(typeof parser).toEqual('function');
+
+            setMarkdownConf({parser: 'gfm'});
+            parser = markdown.getParser();
+            expect(typeof parser).toEqual('function');
+
+            restoreMarkdownConf(storage);
 		});
 
-		xit('should use the evilstreak parser when requested', function() {
-			// TODO
+		it('should use the evilstreak parser when requested', function() {
+            var storage = setMarkdownConf({parser: 'evilstreak'});
+            var parser = markdown.getParser();
+            expect(parser._parser).toEqual('markdown');
+            restoreMarkdownConf(storage);
 		});
 
-		xit('should use the GFM parser when requested', function() {
-			// TODO
+		it('should use the GFM parser when requested', function() {
+            var storage = setMarkdownConf({parser: 'gfm'});
+            var parser = markdown.getParser();
+            expect(parser._parser).toEqual('github-flavored-markdown');
+            restoreMarkdownConf(storage);
 		});
 
-		xit('should convert GitHub repo references to links when the correct options are defined', function() {
-			// TODO
+        it('should use GFM parser when parser is not specified but github owner and repo are', function() {
+            var storage = setMarkdownConf({githubRepoOwner: 'jsdoc', githubRepoName: 'jsdoc3'});
+            var parser = markdown.getParser();
+            expect(parser._parser).toEqual('github-flavored-markdown');
+            restoreMarkdownConf(storage);
+        });
+
+		it('should convert GitHub repo references to links when the correct options are defined', function() {
+            var storage = setMarkdownConf({parser: 'gfm', githubRepoOwner: 'jsdoc', githubRepoName: 'jsdoc3'});
+            var parser = markdown.getParser();
+            expect(parser._parser).toEqual('github-flavored-markdown');
+
+            var sha = '228c940816b5f799a12f83f071a1c67cbb478f39';
+            var sha7 = sha.substr(0, 7);
+
+            // Auto-link sha1 if GitHub.nameWithOwner is defined
+            expect(parser(sha)).toEqual(
+                "<p><a href='http://github.com/jsdoc/jsdoc3/commit/" + sha + "'>" + sha7 + "</a></p>");
+
+            // ** GFM ** Auto-link user@sha1 if GitHub.nameWithOwner is defined
+            expect(parser('mathematicalcoffee@' + sha)).toEqual(
+                "<p><a href='http://github.com/mathematicalcoffee/jsdoc3/commit/" + sha + "'>mathematicalcoffee@" + sha7 + "</a></p>");
+
+            // ** GFM ** Auto-link user/repo@sha1
+            expect(parser('jsdoc/jsdoc3@' + sha)).toEqual(
+                "<p><a href='http://github.com/jsdoc/jsdoc3/commit/" + sha + "'>jsdoc/jsdoc3@" + sha7 + "</a></p>");
+
+            // ** GFM ** Auto-link #issue if GitHub.nameWithOwner is defined
+            expect(parser('Fixes #1')).toEqual(
+                "<p>Fixes <a href='http://github.com/jsdoc/jsdoc3/issues/#issue/1'>#1</a></p>");
+
+            // ** GFM ** Auto-link user#issue if GitHub.nameWithOwner is defined
+            expect(parser('mathematicalcoffee#12')).toEqual(
+                "<p><a href='http://github.com/mathematicalcoffee/jsdoc3/issues/#issue/12'>mathematicalcoffee#12</a></p>");
+
+            // ** GFM ** Auto-link user/repo#issue
+            expect(parser('jsdoc/jsdoc3#1')).toEqual(
+                "<p><a href='http://github.com/jsdoc/jsdoc3/issues/#issue/1'>jsdoc/jsdoc3#1</a></p>");
+            
+            restoreMarkdownConf(storage);
 		});
 
 		it('should not apply formatting to inline tags when the evilstreak parser is enabled', function() {
-            // store the old configuration
-            var old = (env.conf.markdown ? env.conf.markdown.parser : undefined);
-            env.conf.markdown = {parser: 'evilstreak'};
+            var storage = setMarkdownConf({parser: 'evilstreak'});
 
             // get the evilstreak parser and do the test
             var parser = markdown.getParser();
             expect(parser('{@link MyClass#_x} and {@link MyClass#_y}')).toEqual(
                 '<p>{@link MyClass#_x} and {@link MyClass#_y}</p>');
 
-            // restore the old value
-            if (old === undefined) {
-                env.conf.markdown.parser = old;
-            } else {
-                delete env.conf.markdown;
-            }
+            restoreMarkdownConf(storage);
 		});
 
 		it('should not apply formatting to inline tags when the GFM parser is enabled', function() {
-            // store the old configuration
-            var old = (env.conf.markdown ? env.conf.markdown.parser : undefined);
-            env.conf.markdown = {parser: 'gfm'};
+            var storage = setMarkdownConf({parser: 'gfm'});
 
             // get the gfm parser and do the test
             var parser = markdown.getParser();
             expect(parser('{@link MyClass#_x} and {@link MyClass#_y}')).toEqual(
                 '<p>{@link MyClass#_x} and {@link MyClass#_y}</p>');
 
-            // restore the old value
-            if (old === undefined) {
-                env.conf.markdown.parser = old;
-            } else {
-                delete env.conf.markdown;
-            }
+            restoreMarkdownConf(storage);
 		});
+
+        it('GFM parser with no conf.markdown.hardwrap has it to false', function() {
+            var storage = setMarkdownConf({parser: 'gfm'});
+
+            var parser = markdown.getParser();
+            expect(parser('Testing\nhardwrap')).toEqual('<p>Testing\nhardwrap</p>');
+
+            restoreMarkdownConf(storage);
+        });
+
+        it('GFM parser respects conf.markdown.hardwrap=false', function() {
+            var storage = setMarkdownConf({parser: 'gfm', hardwrap: false});
+
+            var parser = markdown.getParser();
+            expect(parser('Testing\nhardwrap')).toEqual('<p>Testing\nhardwrap</p>');
+
+            restoreMarkdownConf(storage);
+        });
+
+        it('GFM parser respects conf.markdown.hardwrap=true', function() {
+            var storage = setMarkdownConf({parser: 'gfm', hardwrap: true});
+
+            var parser = markdown.getParser();
+            expect(parser('Testing\nhardwrap')).toEqual('<p>Testing<br />hardwrap</p>');
+
+            restoreMarkdownConf(storage);
+        });
 	});
 });