GEEKING

RobloxHybrid/docs/jsdoc/plugins/test/specs/commentConvert.js

@@ -0,0 +1,19 @@
+/*global describe: true, env: true, expect: true, it: true, jasmine: true */
+describe("commentConvert plugin", function() {
+    var parser = jasmine.createParser();
+    var path = require('jsdoc/path');
+
+    var docSet;
+
+    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);
+    });
+});

RobloxHybrid/docs/jsdoc/plugins/test/specs/escapeHtml.js

@@ -0,0 +1,19 @@
+/*global describe: true, env: true, expect: true, it: true, jasmine: true */
+describe("escapeHtml plugin", function() {
+    var parser = jasmine.createParser();
+    var path = require('jsdoc/path');
+
+    var docSet;
+
+    var pluginPath = 'plugins/escapeHtml';
+    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 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.<br>        Replaces &lt;, &amp; and newlines");
+    });
+});

RobloxHybrid/docs/jsdoc/plugins/test/specs/markdown.js

@@ -0,0 +1,48 @@
+'use strict';
+
+var path = require('jsdoc/path');
+
+describe('markdown plugin', function() {
+    var pluginPath = 'plugins/markdown';
+    var pluginPathResolved = path.join(global.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.classdesc,
+            myClass.description,
+            myClass.exceptions[0].description,
+            myClass.params[0].description,
+            myClass.properties[0].description,
+            myClass.returns[0].description,
+            myClass.see
+        ].forEach(function(value) {
+            // if we processed the value, it should be wrapped in a <p> tag
+            expect( /^<p>(?:.+)<\/p>$/.test(value) ).toBe(true);
+        });
+    });
+
+    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');
+        });
+    });
+});

RobloxHybrid/docs/jsdoc/plugins/test/specs/overloadHelper.js

@@ -0,0 +1,101 @@
+/*global describe: true, env: true, expect: true, it: true, jasmine: true, xit: true */
+describe('plugins/overloadHelper', function() {
+    var parser = jasmine.createParser();
+    var path = require('jsdoc/path');
+
+    var docSet;
+
+    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);
+        });
+    });
+});

RobloxHybrid/docs/jsdoc/plugins/test/specs/railsTemplate.js

@@ -0,0 +1,17 @@
+/*global describe: true, env: true, expect: true, it: true, jasmine: true */
+describe("railsTemplate plugin", function() {
+    var parser = jasmine.createParser();
+    var path = require('jsdoc/path');
+
+    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. )");
+    });
+});

RobloxHybrid/docs/jsdoc/plugins/test/specs/shout.js

@@ -0,0 +1,19 @@
+/*global describe: true, env: true, expect: true, it: true, jasmine: true */
+describe("shout plugin", function() {
+    var parser = jasmine.createParser();
+    var path = require('jsdoc/path');
+
+    var docSet;
+
+    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.");
+    });
+});

RobloxHybrid/docs/jsdoc/plugins/test/specs/sourcetag.js

@@ -0,0 +1,23 @@
+/*global describe, expect, it, jasmine */
+'use strict';
+
+describe('sourcetag plugin', function() {
+    var parser = jasmine.createParser();
+    var path = require('jsdoc/path');
+
+    var docSet;
+
+    var pluginPath = 'plugins/sourcetag';
+    var pluginPathResolved = path.join(global.env.dirname, pluginPath);
+    var plugin = require(pluginPathResolved);
+
+    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(13);
+    });
+});

RobloxHybrid/docs/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.');
+        });
+    });
+});