新增调试信息

libcore/node_modules/jsdoc/plugins/test/fixtures/markdown.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * @see [Nowhere](http://nowhere.com)
+ */
+function foo() {}
+
+/**
+ * @see AnObject#myProperty
+ */
+function bar() {}
+
+/**
+ * @author [Mr. Macintosh](http://www.folklore.org/StoryView.py?story=Mister_Macintosh.txt)
+ * @classdesc My class.
+ * @description My class.
+ * @exception {Error} Some error.
+ * @param {string} myParam - My parameter.
+ * @property {string} value - Value of myParam.
+ * @return {MyClass} Class instance.
+ * @see [Example Inc.](http://example.com)
+ * @summary My class.
+ */
+function MyClass(myParam) {
+    this.value = myParam;
+}
+
+/**
+ * "See" {@link chat."#channel"."say-\"hello\""}.
+ */
+function MyOtherClass() {}

libcore/node_modules/jsdoc/plugins/test/fixtures/overloadHelper.js

@@ -0,0 +1,50 @@
+/**
+ * A bowl of non-spicy soup.
+ * @class
+ *//**
+ * A bowl of spicy soup.
+ * @class
+ * @param {number} spiciness - The spiciness of the soup, in Scoville heat units (SHU).
+ */
+function Soup(spiciness) {}
+
+/**
+ * Slurp the soup.
+ *//**
+ * Slurp the soup loudly.
+ * @param {number} dBA - The slurping volume, in A-weighted decibels.
+ */
+Soup.prototype.slurp = function(dBA) {};
+
+/**
+ * Salt the soup as needed, using a highly optimized soup-salting heuristic.
+ *//**
+ * Salt the soup, specifying the amount of salt to add.
+ * @variation mg
+ * @param {number} amount - The amount of salt to add, in milligrams.
+ */
+Soup.prototype.salt = function(amount) {};
+
+/**
+ * Heat the soup by the specified number of degrees.
+ * @param {number} degrees - The number of degrees, in Fahrenheit, by which to heat the soup.
+ *//**
+ * Heat the soup by the specified number of degrees.
+ * @variation 1
+ * @param {string} degrees - The number of degrees, in Fahrenheit, by which to heat the soup, but
+ * as a string for some reason.
+ *//**
+ * Heat the soup by the specified number of degrees.
+ * @param {boolean} degrees - The number of degrees, as a boolean. Wait, what?
+ */
+Soup.prototype.heat = function(degrees) {};
+
+/**
+ * Discard the soup.
+ * @variation discardSoup
+ *//**
+ * Discard the soup by pouring it into the specified container.
+ * @variation discardSoup
+ * @param {Object} container - The container in which to discard the soup.
+ */
+Soup.prototype.discard = function(container) {};

libcore/node_modules/jsdoc/plugins/test/fixtures/railsTemplate.js.erb

@@ -0,0 +1,19 @@
+/**
+ * Strips the rails template tags from a js.erb file
+ *
+ * @module plugins/railsTemplate
+ */
+
+exports.handlers = {
+    /**
+     * Remove rails tags from the source input (e.g. <% foo bar %>)
+     * @param e
+     * @param e.filename
+     * @param e.source
+     */
+    beforeParse: function(e) {
+        if (e.filename.match(/\.erb$/)) {
+            e.source = e.source.replace(/<%.*%> /g, "");
+        }
+    }
+};

libcore/node_modules/jsdoc/plugins/test/fixtures/underscore.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/** This doclet will be shown by default, just like normal. */
+function normal() {}
+
+/** This doclet will be hidden by default because it begins with an underscore. */
+function _hidden() {}
+
+/**
+ * Klass class
+ * @class
+ */
+function Klass() {
+    /** This is a private property of the class, and should not. */
+    this._privateProp = null;
+
+    /**
+     * This is a property explicitly marked as private.
+     * @private
+     */
+    this.privateProp = null;
+}

libcore/node_modules/jsdoc/plugins/test/specs/commentConvert.js

@@ -0,0 +1,20 @@
+'use strict';
+
+describe('commentConvert plugin', function() {
+    var env = require('jsdoc/env');
+    var path = require('jsdoc/path');
+
+    var docSet;
+    var parser = jasmine.createParser();
+    var pluginPath = 'plugins/commentConvert';
+    var pluginPathResolved = path.join(env.dirname, pluginPath);
+    var plugin = require(pluginPathResolved);
+
+    require('jsdoc/plugins').installPlugins([pluginPathResolved], parser);
+    docSet = jasmine.getDocSetFromFile(pluginPath + '.js', parser);
+
+    it('should convert ///-style comments into jsdoc comments', function() {
+        var doclet = docSet.getByLongname('module:plugins/commentConvert.handlers.beforeParse');
+        expect(doclet.length).toEqual(1);
+    });
+});

libcore/node_modules/jsdoc/plugins/test/specs/escapeHtml.js

@@ -0,0 +1,20 @@
+'use strict';
+
+describe('escapeHtml plugin', function() {
+    var env = require('jsdoc/env');
+    var path = require('jsdoc/path');
+
+    var docSet;
+    var parser = jasmine.createParser();
+    var pluginPath = 'plugins/escapeHtml';
+    var pluginPathResolved = path.join(env.dirname, pluginPath);
+
+    require('jsdoc/plugins').installPlugins([pluginPathResolved], parser);
+    docSet = jasmine.getDocSetFromFile(pluginPath + '.js', parser);
+
+    it("should escape '&', '<' and newlines in doclet descriptions", function() {
+        var doclet = docSet.getByLongname('module:plugins/escapeHtml.handlers.newDoclet');
+
+        expect(doclet[0].description).toEqual('Translate HTML tags in descriptions into safe entities. Replaces &lt;, &amp; and newlines');
+    });
+});

libcore/node_modules/jsdoc/plugins/test/specs/markdown.js

@@ -0,0 +1,60 @@
+'use strict';
+
+var env = require('jsdoc/env');
+var path = require('jsdoc/path');
+
+describe('markdown plugin', function() {
+    var pluginPath = 'plugins/markdown';
+    var pluginPathResolved = path.join(env.dirname, pluginPath);
+    var plugin = require(pluginPathResolved);
+
+    var docSet = jasmine.getDocSetFromFile('plugins/test/fixtures/markdown.js');
+
+    // TODO: more tests; refactor the plugin so multiple settings can be tested
+
+    it('should process the correct tags by default', function() {
+        var myClass = docSet.getByLongname('MyClass')[0];
+
+        plugin.handlers.newDoclet({ doclet: myClass });
+        [
+            myClass.author[0],
+            myClass.classdesc,
+            myClass.description,
+            myClass.exceptions[0].description,
+            myClass.params[0].description,
+            myClass.properties[0].description,
+            myClass.returns[0].description,
+            myClass.see,
+            myClass.summary
+        ].forEach(function(value) {
+            // if we processed the value, it should be wrapped in a <p> tag
+            expect( /^<p>(?:.+)<\/p>$/.test(value) ).toBe(true);
+        });
+    });
+
+    it('should unescape &quot; entities in inline tags, but not elsewhere', function() {
+        var myOtherClass = docSet.getByLongname('MyOtherClass')[0];
+
+        plugin.handlers.newDoclet({ doclet: myOtherClass });
+
+        expect(myOtherClass.description).toContain('chat."#channel"."say-\\"hello\\""');
+        expect(myOtherClass.description).toContain('&quot;See&quot;');
+    });
+
+    describe('@see tag support', function() {
+        var foo = docSet.getByLongname('foo')[0];
+        var bar = docSet.getByLongname('bar')[0];
+
+        it('should parse @see tags containing links', function() {
+            plugin.handlers.newDoclet({ doclet: foo });
+            expect(typeof foo).toEqual('object');
+            expect(foo.see[0]).toEqual('<p><a href="http://nowhere.com">Nowhere</a></p>');
+        });
+
+        it('should not parse @see tags that do not contain links', function() {
+            plugin.handlers.newDoclet({ doclet: bar });
+            expect(typeof bar).toEqual('object');
+            expect(bar.see[0]).toEqual('AnObject#myProperty');
+        });
+    });
+});

libcore/node_modules/jsdoc/plugins/test/specs/overloadHelper.js

@@ -0,0 +1,102 @@
+'use strict';
+
+describe('plugins/overloadHelper', function() {
+    var env = require('jsdoc/env');
+    var path = require('jsdoc/path');
+
+    var docSet;
+    var parser = jasmine.createParser();
+    var pluginPath = 'plugins/overloadHelper';
+    var pluginPathResolved = path.resolve(env.dirname, pluginPath);
+    var plugin = require(pluginPathResolved);
+
+    require('jsdoc/plugins').installPlugins([pluginPathResolved], parser);
+    docSet = jasmine.getDocSetFromFile('plugins/test/fixtures/overloadHelper.js', parser);
+
+    it('should exist', function() {
+        expect(plugin).toBeDefined();
+        expect(typeof plugin).toBe('object');
+    });
+
+    it('should export handlers', function() {
+        expect(plugin.handlers).toBeDefined();
+        expect(typeof plugin.handlers).toBe('object');
+    });
+
+    it('should export a "newDoclet" handler', function() {
+        expect(plugin.handlers.newDoclet).toBeDefined();
+        expect(typeof plugin.handlers.newDoclet).toBe('function');
+    });
+
+    it('should export a "parseComplete" handler', function() {
+        expect(plugin.handlers.parseComplete).toBeDefined();
+        expect(typeof plugin.handlers.parseComplete).toBe('function');
+    });
+
+    describe('newDoclet handler', function() {
+        it('should not add unique longnames to constructors', function() {
+            var soup = docSet.getByLongname('Soup');
+            var soup1 = docSet.getByLongname('Soup()');
+            var soup2 = docSet.getByLongname('Soup(spiciness)');
+
+            expect(soup.length).toBe(2);
+            expect(soup1.length).toBe(0);
+            expect(soup2.length).toBe(0);
+        });
+
+        it('should add unique longnames to methods', function() {
+            var slurp = docSet.getByLongname('Soup#slurp');
+            var slurp1 = docSet.getByLongname('Soup#slurp()');
+            var slurp2 = docSet.getByLongname('Soup#slurp(dBA)');
+
+            expect(slurp.length).toBe(0);
+            expect(slurp1.length).toBe(1);
+            expect(slurp2.length).toBe(1);
+        });
+
+        it('should update the "variation" property of the method', function() {
+            var slurp1 = docSet.getByLongname('Soup#slurp()')[0];
+            var slurp2 = docSet.getByLongname('Soup#slurp(dBA)')[0];
+
+            expect(slurp1.variation).toBe('');
+            expect(slurp2.variation).toBe('dBA');
+        });
+
+        it('should not add to or change existing variations that are unique', function() {
+            var salt1 = docSet.getByLongname('Soup#salt');
+            var salt2 = docSet.getByLongname('Soup#salt(mg)');
+
+            expect(salt1.length).toBe(1);
+            expect(salt2.length).toBe(1);
+        });
+
+        it('should not duplicate the names of existing numeric variations', function() {
+            var heat1 = docSet.getByLongname('Soup#heat(1)');
+            var heat2 = docSet.getByLongname('Soup#heat(2)');
+            var heat3 = docSet.getByLongname('Soup#heat(3)');
+
+            expect(heat1.length).toBe(1);
+            expect(heat2.length).toBe(1);
+            expect(heat3.length).toBe(1);
+        });
+
+        it('should replace identical variations with new, unique variations', function() {
+            var discard1 = docSet.getByLongname('Soup#discard()');
+            var discard2 = docSet.getByLongname('Soup#discard(container)');
+
+            expect(discard1.length).toBe(1);
+            expect(discard2.length).toBe(1);
+        });
+    });
+
+    describe('parseComplete handler', function() {
+        // disabled because on the second run, each comment is being parsed twice; who knows why...
+        xit('should not retain parse results between parser runs', function() {
+            parser.clear();
+            docSet = jasmine.getDocSetFromFile('plugins/test/fixtures/overloadHelper.js', parser);
+            var heat = docSet.getByLongname('Soup#heat(4)');
+
+            expect(heat.length).toBe(0);
+        });
+    });
+});

libcore/node_modules/jsdoc/plugins/test/specs/railsTemplate.js

@@ -0,0 +1,19 @@
+'use strict';
+
+describe('railsTemplate plugin', function() {
+    var env = require('jsdoc/env');
+    var path = require('jsdoc/path');
+
+    var parser = jasmine.createParser();
+    var pluginPath = path.join(env.dirname, 'plugins/railsTemplate');
+    var plugin = require(pluginPath);
+
+    require('jsdoc/plugins').installPlugins([pluginPath], parser);
+    require('jsdoc/src/handlers').attachTo(parser);
+
+    it('should remove <% %> rails template tags from the source of *.erb files', function() {
+        var docSet = parser.parse([path.join(env.dirname, 'plugins/test/fixtures/railsTemplate.js.erb')]);
+
+        expect(docSet[2].description).toEqual('Remove rails tags from the source input (e.g. )');
+    });
+});

libcore/node_modules/jsdoc/plugins/test/specs/shout.js

@@ -0,0 +1,20 @@
+'use strict';
+
+describe('shout plugin', function() {
+    var env = require('jsdoc/env');
+    var path = require('jsdoc/path');
+
+    var docSet;
+    var parser = jasmine.createParser();
+    var pluginPath = 'plugins/shout';
+    var pluginPathResolved = path.join(env.dirname, pluginPath);
+    var plugin = require(pluginPathResolved);
+
+    require('jsdoc/plugins').installPlugins([pluginPathResolved], parser);
+    docSet = jasmine.getDocSetFromFile(pluginPath + '.js', parser);
+
+    it('should make the description uppercase', function() {
+        var doclet = docSet.getByLongname('module:plugins/shout.handlers.newDoclet');
+        expect(doclet[0].description).toEqual('MAKE YOUR DESCRIPTIONS MORE SHOUTIER.');
+    });
+});

libcore/node_modules/jsdoc/plugins/test/specs/sourcetag.js

@@ -0,0 +1,22 @@
+'use strict';
+
+describe('sourcetag plugin', function() {
+    var env = require('jsdoc/env');
+    var path = require('jsdoc/path');
+
+    var docSet;
+    var parser = jasmine.createParser();
+    var pluginPath = 'plugins/sourcetag';
+    var pluginPathResolved = path.join(env.dirname, pluginPath);
+
+    require('jsdoc/plugins').installPlugins([pluginPathResolved], parser);
+    docSet = jasmine.getDocSetFromFile(pluginPath + '.js', parser);
+
+    it("should set the lineno and filename of the doclet's meta property", function() {
+        var doclet = docSet.getByLongname('module:plugins/sourcetag.handlers.newDoclet');
+
+        expect(doclet[0].meta).toBeDefined();
+        expect(doclet[0].meta.filename).toEqual('sourcetag.js');
+        expect(doclet[0].meta.lineno).toEqual(9);
+    });
+});

libcore/node_modules/jsdoc/plugins/test/specs/summarize.js

@@ -0,0 +1,112 @@
+/*global describe, expect, it */
+'use strict';
+
+var summarize = require('../../summarize');
+
+describe('summarize', function() {
+    it('should export handlers', function() {
+        expect(summarize.handlers).toBeDefined();
+        expect(typeof summarize.handlers).toBe('object');
+    });
+
+    it('should export a newDoclet handler', function() {
+        expect(summarize.handlers.newDoclet).toBeDefined();
+        expect(typeof summarize.handlers.newDoclet).toBe('function');
+    });
+
+    describe('newDoclet handler', function() {
+        var handler = summarize.handlers.newDoclet;
+
+        it('should not blow up if the doclet is missing', function() {
+            function noDoclet() {
+                return handler({});
+            }
+
+            expect(noDoclet).not.toThrow();
+        });
+
+        it('should not change the summary if it is already defined', function() {
+            var doclet = {
+                summary: 'This is a summary.',
+                description: 'Descriptions are good.'
+            };
+            handler({ doclet: doclet });
+
+            expect(doclet.summary).not.toBe(doclet.description);
+        });
+
+        it('should not do anything if the description is missing', function() {
+            var doclet = {};
+            handler({ doclet: doclet });
+
+            expect(doclet.summary).not.toBeDefined();
+        });
+
+        it('should use the first sentence as the summary', function() {
+            var doclet = {
+                description: 'This sentence is the summary. This sentence is not.'
+            };
+            handler({ doclet: doclet });
+
+            expect(doclet.summary).toBe('This sentence is the summary.');
+        });
+
+        it('should not add an extra period if there is only one sentence in the description',
+            function() {
+            var doclet = {
+                description: 'This description has only one sentence.'
+            };
+            handler({ doclet: doclet });
+
+            expect(doclet.summary).toBe('This description has only one sentence.');
+        });
+
+        it('should use the entire description, plus a period, as the summary if the description ' +
+            'does not contain a period', function() {
+            var doclet = {
+                description: 'This is a description'
+            };
+            handler({ doclet: doclet });
+
+            expect(doclet.summary).toBe('This is a description.');
+        });
+
+        it('should use the entire description as the summary if the description contains only ' +
+            'one sentence', function() {
+            var doclet = {
+                description: 'This is a description.'
+            };
+            handler({ doclet: doclet });
+
+            expect(doclet.description).toBe('This is a description.');
+        });
+
+        it('should work when an HTML tag immediately follows the first sentence', function() {
+            var doclet = {
+                description: 'This sentence is the summary.<small>This sentence is small.</small>'
+            };
+            handler({ doclet: doclet });
+
+            expect(doclet.summary).toBe('This sentence is the summary.');
+        });
+
+        it('should generate valid HTML if a tag is opened, but not closed, in the summary',
+            function() {
+            var doclet = {
+                description: 'This description has <em>a tag. The tag straddles</em> sentences.'
+            };
+            handler({ doclet: doclet });
+
+            expect(doclet.summary).toBe('This description has <em>a tag.</em>');
+        });
+
+        it('should not include a <p> tag in the summary', function() {
+            var doclet = {
+                description: '<p>This description contains HTML.</p><p>And plenty of it!</p>'
+            };
+            handler({ doclet: doclet });
+
+            expect(doclet.summary).toBe('This description contains HTML.');
+        });
+    });
+});

libcore/node_modules/jsdoc/plugins/test/specs/underscore.js

@@ -0,0 +1,35 @@
+'use strict';
+
+describe('underscore plugin', function () {
+    var env = require('jsdoc/env');
+    var path = require('jsdoc/path');
+
+    var docSet;
+    var parser = jasmine.createParser();
+    var pluginPath = 'plugins/underscore';
+    var fixturePath = 'plugins/test/fixtures/underscore';
+    var pluginPathResolved = path.join(env.dirname, pluginPath);
+    var plugin = require(pluginPathResolved);
+
+    require('jsdoc/plugins').installPlugins([pluginPathResolved], parser);
+    docSet = jasmine.getDocSetFromFile(fixturePath + '.js', parser);
+
+    it('should not mark normal, public properties as private', function() {
+        // Base line tests
+        var normal = docSet.getByLongname('normal');
+        expect(normal[0].access).toBeUndefined();
+
+        var realPrivate = docSet.getByLongname('Klass#privateProp');
+        expect(realPrivate[0].access).toEqual('private');
+    });
+
+    it('should hide doclet for symbols beginning with an underscore under normal circumstances', function () {
+        var hidden = docSet.getByLongname('_hidden');
+        expect(hidden[0].access).toEqual('private');
+    });
+
+    it('picks up "this"', function() {
+        var privateUnderscore = docSet.getByLongname('Klass#_privateProp');
+        expect(privateUnderscore[0].access).toEqual('private');
+    });
+});