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 'master' into feature-listens

Browse Source
This commit is contained in:
mathematicalcoffee 2013-02-26 14:19:14 +10:00
commit db3451be72
79 changed files with 1432 additions and 396 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
jsdoc.js
View File

@ -179,6 +179,10 @@ function main() {
if (env.conf.plugins) {
plugins.installPlugins(env.conf.plugins, app.jsdoc.parser);
}
if (env.conf.source && env.conf.source.include) {
env.opts._ = (env.opts._ || []).concat(env.conf.source.include);
}
// any source file named package.json or README.md is treated special
for (i = 0, l = env.opts._.length; i < l; i++ ) {
@ -193,10 +197,6 @@ function main() {
}
}
if (env.conf.source && env.conf.source.include) {
env.opts._ = (env.opts._ || []).concat(env.conf.source.include);
}
if (env.conf.source && env.opts._.length > 0) { // are there any files to scan and parse?
filter = new Filter(env.conf.source);

37
lib/jsdoc/src/parser.js
View File

@ -300,6 +300,20 @@ function getBasename(name) {
return name;
}
/** @private
* @memberof module:src/parser.Parser
* @param {object} node
* @return {Array.<number>} Start and end lines.
*/
function getRange(node) {
var range = [];
range[0] = parseInt(String(node.getAbsolutePosition()), 10);
range[1] = range[0] + parseInt(String(node.getLength()), 10);
return range;
}
/** @private
* @memberof module:src/parser.Parser
*/
@ -312,17 +326,7 @@ exports.Parser.prototype._makeEvent = function(node, extras) {
id: extras.id || 'astnode' + node.hashCode(),
comment: extras.comment || String(node.getJsDoc() || '@undocumented'),
lineno: extras.lineno || node.left.getLineno(),
range: (function() {
var range = [];
if (extras.range) {
range = extras.range;
}
else {
range[0] = parseInt(String(node.getAbsolutePosition()), 10);
range[1] = range[0] + parseInt(String(node.getLength()), 10);
}
return range;
})(),
range: extras.range || getRange(node),
filename: extras.filename || this._currentSourceName,
astnode: extras.astnode || node,
code: extras.code || aboutNode(node),
@ -388,8 +392,7 @@ exports.Parser.prototype._visitNode = function(node) {
comment: commentSrc,
lineno: comment.getLineno(),
filename: this._currentSourceName,
linelength: comment.getLength(),
absposition: comment.getAbsolutePosition()
range: getRange(comment)
};
this.emit('jsdocCommentFound', e, this);
@ -432,9 +435,7 @@ exports.Parser.prototype._visitNode = function(node) {
}
extras = {
lineno: node.getLineno(),
linelength: node.getLength(),
absposition: node.getAbsolutePosition()
lineno: node.getLineno()
};
e = this._makeEvent(node, extras);
@ -442,9 +443,7 @@ exports.Parser.prototype._visitNode = function(node) {
}
else if (node.type == Token.FUNCTION || node.type == tkn.NAMEDFUNCTIONSTATEMENT) {
extras = {
lineno: node.getLineno(),
linelength: node.getLength(),
absposition: node.getAbsolutePosition()
lineno: node.getLineno()
};
e = this._makeEvent(node, extras);

3
lib/jsdoc/tag/dictionary/definitions.js
View File

@ -349,7 +349,8 @@ exports.defineTags = function(dictionary) {
applyNamespace('event', tag);
doclet.fires.push(tag.value);
}
});
})
.synonym('emits');
dictionary.defineTag('function', {
onTagged: function(doclet, tag) {

6
lib/jsdoc/tutorial/resolver.js
View File

@ -97,7 +97,7 @@ exports.root = new tutorial.Tutorial('', '');
@return {tutorial.Tutorial} Tutorial instance.
*/
exports.root.getByName = function(name) {
return tutorials[name];
return hasOwnProp.call(tutorials, name) && tutorials[name];
};
/** Load tutorials from given path.
@ -162,7 +162,7 @@ exports.resolve = function() {
for (var name in conf) {
if ( hasOwnProp.call(conf, name) ) {
// TODO: should we complain about this?
if (!(name in tutorials)) {
if (!hasOwnProp.call(tutorials, name)) {
continue;
}
@ -177,7 +177,7 @@ exports.resolve = function() {
// add children
if (item.children) {
item.children.forEach(function(child) {
if (!(child in tutorials)) {
if (!hasOwnProp.call(tutorials, child)) {
error.handle( new Error("Missing child tutorial: " + child) );
}
else {

31
lib/jsdoc/util/templateHelper.js
View File

@ -3,7 +3,6 @@
* @module jsdoc/util/templateHelper
*/
var crypto = require('crypto');
var dictionary = require('jsdoc/tag/dictionary');
var util = require('util');
@ -14,7 +13,6 @@ var files = {};
// each container gets its own html file
var containers = ['class', 'module', 'external', 'namespace', 'mixin'];
/** @external {jsdoc.tutorial.Tutorial} */
var tutorials;
/** Sets tutorials map.
@ -68,18 +66,25 @@ var nsprefix = /^(event|module|external):/;
* @return {string} The filename to use for the string.
*/
var getUniqueFilename = exports.getUniqueFilename = function(str) {
var result;
// allow for namespace prefix
var basename = str.replace(nsprefix, '$1-');
var basename = str.replace(nsprefix, '$1-')
// and use - instead of ~ to denote 'inner'
.replace(/~/g, '-');
if ( /[^$a-z0-9._\-]/i.test(basename) ) {
result = crypto.createHash('sha1').update(str).digest('hex').substr(0, 10);
} else {
result = makeFilenameUnique(basename, str);
// if the basename includes characters that we can't use in a filepath, remove everything up to
// and including the last bad character
var regexp = /[^$a-z0-9._\-](?=[$a-z0-9._\-]*$)/i;
var result = regexp.exec(basename);
if (result && result.index) {
basename = basename.substr(result.index + 1);
}
return result + exports.fileExtension;
// make sure we don't create hidden files on POSIX systems
basename = basename.replace(/^\./, '');
// and in case we've now stripped the entire basename (uncommon, but possible):
basename = basename.length ? basename : '_';
return makeFilenameUnique(basename, str) + exports.fileExtension;
};
// two-way lookup
@ -98,7 +103,7 @@ var longnameToUrl = exports.longnameToUrl = linkMap.longnameToUrl;
var linkto = exports.linkto = function(longname, linktext, cssClass) {
var classString = cssClass ? util.format(' class="%s"', cssClass) : '';
var text = linktext || longname;
var url = longnameToUrl[longname];
var url = hasOwnProp.call(longnameToUrl, longname) && longnameToUrl[longname];
if (!url) {
return text;
@ -353,7 +358,7 @@ function toLink(longname, content, monospace) {
}
else {
// the actual longname is stored in `url` if there was a delimiter.
url = linkMap.longnameToUrl[longname];
url = hasOwnProp.call(linkMap.longnameToUrl, longname) && linkMap.longnameToUrl[longname];
}
content = content || longname;
@ -390,7 +395,7 @@ var tutorialToUrl = exports.tutorialToUrl = function(tutorial) {
var url;
// define the URL if necessary
if (!tutorialLinkMap.nameToUrl[node.name]) {
if (!hasOwnProp.call(tutorialLinkMap.nameToUrl, node.name)) {
url = 'tutorial-' + getUniqueFilename(node.name);
tutorialLinkMap.nameToUrl[node.name] = url;
tutorialLinkMap.urlToName[url] = node.name;

2
lib/jsdoc/util/vm.js
View File

@ -58,7 +58,7 @@ var vm = exports.vm = (function() {
* @return {object} An object containing VM-specific functions for the requested module.
*/
exports.getModule = function(modulePath) {
modulePath = [__dirname, vm, modulePath].join('/');
modulePath = [__dirname, vm, modulePath].join('/').replace(/ /g, '%20');
if (os.platform() === 'win32') {
modulePath = pathToUri(modulePath);
}

18
test/fixtures/augmentstag3.js vendored Normal file
View File

@ -0,0 +1,18 @@
// test to see that we can @augment multiple things (code allows for it)
/** @class */
function Foo() {
}
/** A method. */
Foo.prototype.method1 = function () {};
/** @class */
function Bar() {
}
/** Another method. */
Bar.prototype.method2 = function () {}
/** @class
* @augments Foo
* @augments Bar */
function FooBar() {
}

8
test/fixtures/authortag.js vendored
View File

@ -2,5 +2,9 @@
@author Michael Mathews <micmath@gmail.com>
*/
function Thingy() {
}
}
/** @author John Doe <john.doe@gmail.com>
* @author Jane Doe <jane.doe@gmail.com> */
function Thingy2() {
}

7
test/fixtures/classdesctag.js vendored Normal file
View File

@ -0,0 +1,7 @@
/**
* Asdf.
* @class
* @classdesc A description of the class.
*/
function Foo () {
}

6
test/fixtures/constanttag.js vendored Normal file
View File

@ -0,0 +1,6 @@
/** @constant */
var FOO = 1;
/** @const BAR */
/** @const {string} BAZ */

7
test/fixtures/descriptiontag.js vendored Normal file
View File

@ -0,0 +1,7 @@
/** Blah Blah Blah
* @desc halb halb halb
*/
var x;
/** @description lkjasdf */
var y;

12
test/fixtures/eventfirestag.js vendored
View File

@ -16,3 +16,15 @@ Hurl.prototype.snowball = function () {
*/
this.emit('snowball', {});
};
/**
* Throw a football match.
*
* @emits Hurl#footballMatch
*/
Hurl.prototype.footballMatch = function () {
/**
* @event Hurl#footballMatch
*/
this.emit('footballMatch', {});
};

14
test/fixtures/exampletag.js vendored Normal file
View File

@ -0,0 +1,14 @@
/** @example
* console.log("foo");
* console.log("bar");
*/
var x;
/** @example
* console.log("foo");
* console.log("bar");
* @example
* <caption>Example 2</caption>
* 1 + 2;
*/
var y;

7
test/fixtures/functiontag.js vendored Normal file
View File

@ -0,0 +1,7 @@
/** @func Foo */
function Foo() {
}
/** @method */
function Bar() {
}

2
test/fixtures/kindtag.js vendored Normal file
View File

@ -0,0 +1,2 @@
/** @kind function */
var x;

2
test/fixtures/licensetag.js vendored Normal file
View File

@ -0,0 +1,2 @@
/** @license GPL v2 */
var x;

5
test/fixtures/membertag.js vendored Normal file
View File

@ -0,0 +1,5 @@
/** @member */
var x;
/** @var foobar */
/** @var {string} baz */

27
test/fixtures/mixintag.js vendored Normal file
View File

@ -0,0 +1,27 @@
/**
* This provides methods used for event handling. It's not meant to
* be used directly, except as a provider of related methods.
*
* @mixin
*/
var Eventful = {
/** fires something. */
fires: function () {},
/** handles a signal. */
on: function () {}
};
/**
* @constructor
* @mixes Eventful
*/
var FormButton = function() {
};
/** @mixin AnotherMixin*/
/** I mix in multiple things
* @constructor MyClass
* @mixes Eventful
* @mixes AnotherMixin */

5
test/fixtures/namespacetag.js vendored Normal file
View File

@ -0,0 +1,5 @@
/** @namespace */
var x = {
};
/** @namespace Foo */
/** @namespace {function} Bar */

10
test/fixtures/scopetags.js vendored Normal file
View File

@ -0,0 +1,10 @@
/** (scope tags for global objects do not override globalness hence need a container class)
* @module scopetags */
/** @inner */
var myInner;
/** @instance */
var myInstance;
/** @static */
var myStatic;

3
test/fixtures/summarytag.js vendored Normal file
View File

@ -0,0 +1,3 @@
/** @summary I do not like green eggs and ham! */
function Sam() {
}

6
test/fixtures/todotag.js vendored Normal file
View File

@ -0,0 +1,6 @@
/** A function.
* @todo something
* @todo something else
*/
function x() {
}

5
test/fixtures/tutorialtag.js vendored Normal file
View File

@ -0,0 +1,5 @@
/** Some documentation.
* @tutorial tute1
* @tutorial tute2
*/
var x;

3
test/fixtures/undocumentedtag.js vendored Normal file
View File

@ -0,0 +1,3 @@
/** Undocumented doclet.
* @undocumented */
var x;

105
test/specs/jsdoc/tutorial/resolver.js
View File

@ -8,32 +8,32 @@ describe("jsdoc/tutorial/resolver", function() {
/*jshint evil: true */
it("should exist", function() {
expect(resolver).toBeDefined();
expect(typeof resolver).toEqual('object');
expect(typeof resolver).toBe('object');
});
it("should export a 'addTutorial' function", function() {
expect(resolver.addTutorial).toBeDefined();
expect(typeof resolver.addTutorial).toEqual("function");
expect(typeof resolver.addTutorial).toBe("function");
});
it("should export a 'load' function", function() {
expect(resolver.load).toBeDefined();
expect(typeof resolver.load).toEqual("function");
expect(typeof resolver.load).toBe("function");
});
it("should export a 'resolve' function", function() {
expect(resolver.resolve).toBeDefined();
expect(typeof resolver.resolve).toEqual("function");
expect(typeof resolver.resolve).toBe("function");
});
it("should export a 'root' tutorial", function() {
expect(resolver.root).toBeDefined();
expect(resolver.root instanceof tutorial.Tutorial).toEqual(true);
expect(resolver.root instanceof tutorial.Tutorial).toBe(true);
});
it("exported 'root' tutorial should export a 'getByName' function", function() {
expect(resolver.root.getByName).toBeDefined();
expect(typeof resolver.root.getByName).toEqual("function");
expect(typeof resolver.root.getByName).toBe("function");
});
// note: every time we addTutorial or run the resolver, we are *adding*
@ -45,18 +45,26 @@ describe("jsdoc/tutorial/resolver", function() {
describe("addTutorial", function() {
it("should add a default parent of the root tutorial", function() {
expect(tute.parent).toEqual(resolver.root);
expect(tute.parent).toBe(resolver.root);
});
it("should be added to the root tutorial as a child", function() {
expect(resolver.root.children[0]).toEqual(tute);
expect(resolver.root.children).toContain(tute);
});
});
// root.getByName
describe("root.getByName", function() {
it("can retrieve tutorials by name", function() {
expect(resolver.root.getByName('myTutorial')).toEqual(tute);
expect(resolver.root.getByName('myTutorial')).toBe(tute);
});
it("returns nothing for non-existent tutorials", function() {
expect(resolver.root.getByName('asdf')).toBeFalsy();
});
it("is careful with tutorials whose names are reserved keywords in JS", function() {
expect(resolver.root.getByName('prototype')).toBeFalsy();
});
});
@ -66,8 +74,9 @@ describe("jsdoc/tutorial/resolver", function() {
test = resolver.root.getByName('test'),
test2 = resolver.root.getByName('test2'),
test3 = resolver.root.getByName('test3'),
test4 = resolver.root.getByName('test4');
test6 = resolver.root.getByName('test6');
test4 = resolver.root.getByName('test4'),
test6 = resolver.root.getByName('test6'),
constr = resolver.root.getByName('constructor');
describe("load", function() {
@ -78,33 +87,39 @@ describe("jsdoc/tutorial/resolver", function() {
expect(test3).toBeDefined();
expect(test4).toBeDefined();
expect(test6).toBeDefined();
expect(constr).toBeDefined();
// check they are top-level in resolver.root
expect(childNames.indexOf('test')).not.toEqual(-1);
expect(childNames.indexOf('test2')).not.toEqual(-1);
expect(childNames.indexOf('test3')).not.toEqual(-1);
expect(childNames.indexOf('test4')).not.toEqual(-1);
expect(childNames.indexOf('test6')).not.toEqual(-1);
expect(childNames).toContain('test');
expect(childNames).toContain('test2');
expect(childNames).toContain('test3');
expect(childNames).toContain('test4');
expect(childNames).toContain('test6');
});
it("tutorials with names equal to reserved keywords in JS still function as expected", function() {
expect(constr instanceof tutorial.Tutorial).toBe(true);
});
it("non-tutorials are skipped", function() {
expect(resolver.root.getByName('multple')).toBeUndefined();
expect(resolver.root.getByName('test5')).toBeUndefined();
expect(resolver.root.getByName('multiple')).toBeFalsy();
expect(resolver.root.getByName('test5')).toBeFalsy();
});
it("tutorial types are determined correctly", function() {
// test.html, test2.markdown, test3.html, test4.md, test6.xml
expect(test.type).toEqual(tutorial.TYPES.HTML);
expect(test2.type).toEqual(tutorial.TYPES.MARKDOWN);
expect(test3.type).toEqual(tutorial.TYPES.HTML);
expect(test4.type).toEqual(tutorial.TYPES.MARKDOWN);
expect(test6.type).toEqual(tutorial.TYPES.HTML);
expect(test.type).toBe(tutorial.TYPES.HTML);
expect(test2.type).toBe(tutorial.TYPES.MARKDOWN);
expect(test3.type).toBe(tutorial.TYPES.HTML);
expect(test4.type).toBe(tutorial.TYPES.MARKDOWN);
expect(test6.type).toBe(tutorial.TYPES.HTML);
expect(constr.type).toBe(tutorial.TYPES.MARKDOWN);
});
});
// resolve
// myTutorial
// constructor
// test
// |- test2
// |- test6
@ -114,42 +129,44 @@ describe("jsdoc/tutorial/resolver", function() {
resolver.resolve();
it("hierarchy is resolved properly no matter how the children property is defined", function() {
// root has child 'test'
expect(resolver.root.children.length).toEqual(2);
expect(resolver.root.children.indexOf(test)).not.toEqual(-1);
expect(test.parent).toEqual(resolver.root);
expect(resolver.root.children.length).toBe(3);
expect(resolver.root.children).toContain(test);
expect(resolver.root.children).toContain(constr);
expect(test.parent).toBe(resolver.root);
expect(constr.parent).toBe(resolver.root);
// test has child 'test2'
expect(test.children.length).toEqual(1);
expect(test.children[0]).toEqual(test2);
expect(test2.parent).toEqual(test);
expect(test.children.length).toBe(1);
expect(test.children).toContain(test2);
expect(test2.parent).toBe(test);
// test2 has children test3, test6
expect(test2.children.length).toEqual(2);
expect(test2.children.indexOf(test3)).not.toEqual(-1);
expect(test2.children.indexOf(test6)).not.toEqual(-1);
expect(test3.parent).toEqual(test2);
expect(test6.parent).toEqual(test2);
expect(test2.children.length).toBe(2);
expect(test2.children).toContain(test3);
expect(test2.children).toContain(test6);
expect(test3.parent).toBe(test2);
expect(test6.parent).toBe(test2);
// test3 has child test4
expect(test3.children.length).toEqual(1);
expect(test3.children[0]).toEqual(test4);
expect(test4.parent).toEqual(test3);
expect(test3.children.length).toBe(1);
expect(test3.children).toContain(test4);
expect(test4.parent).toBe(test3);
});
it("tutorials without configuration files have titles matching filenames", function() {
// test6.xml didn't have a metadata
expect(test6.title).toEqual('test6');
expect(test6.title).toBe('test6');
});
it("tutorials with configuration files have titles matching filenames", function() {
it("tutorials with configuration files have titles as specified in configuration", function() {
// test.json had info for just test.json
expect(test.title).toEqual("Test tutorial");
expect(test.title).toBe("Test tutorial");
});
it("multiple tutorials can appear in a configuration file", function() {
expect(test2.title).toEqual("Test 2");
expect(test3.title).toEqual("Test 3");
expect(test4.title).toEqual("Test 4");
expect(test2.title).toBe("Test 2");
expect(test3.title).toBe("Test 3");
expect(test4.title).toBe("Test 4");
});
});

75
test/specs/jsdoc/util/doop.js
View File

@ -1,4 +1,73 @@
/*global describe: true, it: true */
describe("jsdoc/util/doop", function() {
// TODO
});
describe('jsdoc/util/doop', function() {
var doop = require('jsdoc/util/doop');
it('should exist', function() {
expect(doop).toBeDefined();
expect(typeof doop).toBe('object');
});
it('should export a doop function', function() {
expect(doop.doop).toBeDefined();
expect(typeof doop.doop).toBe('function');
});
// deep-clones a simple object.
describe('doop', function() {
it("should return the input object if it's simple (boolan, string etc) or a function", function() {
// .toBe uses === to test.
// test a number...
expect(doop.doop(3)).toBe(3);
// test a string...
expect(doop.doop('asdf')).toBe('asdf');
// test a boolean...
expect(doop.doop(true)).toBe(true);
// test a function...
var f = function () {};
expect(doop.doop(f)).toBe(f);
});
it("should return a clone of an array", function() {
var inp = [1,2,3],
out = doop.doop(inp);
// toEqual is a comparison on properties; toBe is === comparison.
expect(inp).toEqual(out);
expect(inp).not.toBe(out);
});
it("should return a clone of an object", function() {
var inp = {a:1, b:2, 'asdf-fdsa': 3};
out = doop.doop(inp);
// toEqual is a comparison on properties; toBe is === comparison.
expect(inp).toEqual(out);
expect(inp).not.toBe(out);
});
// checks that a === b if it's not an object or array (or it's af function);
// otherwise recurses down into keys and compares them.
function compareForEquality(a, b) {
if (a instanceof Object && a.constructor != Function) {
// if it's an object and not a function, it should clone.
var keys = Object.keys(a);
expect(Object.keys(a)).toEqual(Object.keys(b));
for (var i = 0; i < keys.length; ++i) {
compareForEquality(a[keys[i]], b[keys[i]]);
}
} else {
// otherwise, it should be exactly equal.
expect(a).toBe(b);
}
}
it("should clone recursively", function() {
var inp = {a:1, b:2, 'asdf-fdsa': {a: 'fdsa', b: [1,2,3]}};
out = doop.doop(inp);
// toEqual is a comparison on properties; toBe is === comparison.
expect(inp).toEqual(out);
expect(inp).not.toBe(out);
// double-check
compareForEquality(inp, out);
});
});
});

6
test/specs/jsdoc/util/error.js
View File

@ -15,8 +15,7 @@ describe("jsdoc/util/error", function() {
describe("handle", function() {
/*jshint evil: true */
var lenient = !!env.opts.lenient,
log = eval(console.log);
var lenient = !!env.opts.lenient;
function handleError() {
handle( new Error("foo") );
@ -28,7 +27,6 @@ describe("jsdoc/util/error", function() {
afterEach(function() {
env.opts.lenient = lenient;
console.log = log;
});
it("should re-throw errors by default", function() {
@ -43,7 +41,7 @@ describe("jsdoc/util/error", function() {
it("should not re-throw errors if lenient mode is enabled", function() {
env.opts.lenient = true;
console.log = function() {};
spyOn(console, 'log');
expect(handleError).not.toThrow();
});

680
test/specs/jsdoc/util/templateHelper.js
View File

File diff suppressed because it is too large Load Diff

4
test/specs/tags/abstracttag.js
View File

@ -8,13 +8,13 @@ describe("@abstract tag", function() {
});
it("should set the doclet's 'virtual' property to true when ' @abstract tag is present", function() {
expect(pez.virtual).toEqual(true);
expect(pez.virtual).toBe(true);
});
// same as...
it("should set the doclet's 'virtual' property to true when ' @abstract tag is present", function() {
pez = docSet.getByLongname('OtherThingy#pez')[0];
expect(pez.virtual).toEqual(true);
expect(pez.virtual).toBe(true);
});
});

8
test/specs/tags/accesstag.js
View File

@ -8,13 +8,13 @@ describe("@access tag", function() {
pez2 = docSet.getByLongname('OtherThingy#pez')[0];
it("should set the doclet's 'access' property to 'private' when there is an @access private tag", function() {
expect(foo.access).toEqual('private');
expect(foo2.access).toEqual('private');
expect(foo.access).toBe('private');
expect(foo2.access).toBe('private');
});
it("should set the doclet's 'access' property to 'protected' when there is an @access protected tag", function() {
expect(_bar.access).toEqual('protected');
expect(_bar2.access).toEqual('protected');
expect(_bar.access).toBe('protected');
expect(_bar2.access).toBe('protected');
});
it("should set no 'access' property on the doclet when there is an @access public tag", function() {

11
test/specs/tags/aliastag.js Normal file
View File

@ -0,0 +1,11 @@
describe("@alias tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/alias.js'),
// there are two doclets with longname myObject, we want the second one
myObject = docSet.getByLongname('myObject')[1];
it("adds an 'alias' property to the doclet with the tag's value", function() {
expect(myObject.alias).toBeDefined();
expect(myObject.alias).toBe('myObject');
});
// further tests (ensuring alias has the proper effect): documentation/alias.js
});

68
test/specs/tags/augmentstag.js
View File

@ -24,11 +24,17 @@
bazMethod3 = docSet.getByLongname('Baz#method3')[0],
docSet2 = jasmine.getDocSetFromFile('test/fixtures/augmentstag2.js'),
qux = docSet2.getByLongname('Qux')[0];
qux = docSet2.getByLongname('Qux')[0],
docSet3 = jasmine.getDocSetFromFile('test/fixtures/augmentstag3.js'),
FooMethod1 = docSet3.getByLongname('Foo#method1')[0],
BarMethod2 = docSet3.getByLongname('Bar#method2')[0],
FooBarMethod1 = docSet3.getByLongname('FooBar#method1')[0],
FooBarMethod2 = docSet3.getByLongname('FooBar#method2')[0];
it('When a symbol has an @augments tag, the doclet has a augments property that includes that value.', function() {
expect(typeof bar.augments).toEqual('object');
expect(bar.augments[0]).toEqual('Foo');
expect(typeof bar.augments).toBe('object');
expect(bar.augments[0]).toBe('Foo');
});
it('When an object is extended, the original is not modified', function() {
@ -36,50 +42,58 @@
});
it('When an object is extended, it inherits properties set in parent constructor', function() {
expect(fooProp1.memberof).toEqual("Foo");
expect(barProp1.memberof).toEqual("Bar");
expect(barProp1.description).toEqual(fooProp1.description);
expect(fooProp1.memberof).toBe("Foo");
expect(barProp1.memberof).toBe("Bar");
expect(barProp1.description).toBe(fooProp1.description);
});
it('When an object is extended, it inherits properties set on parent prototype', function() {
expect(fooProp2.memberof).toEqual("Foo");
expect(barProp2.memberof).toEqual("Bar");
expect(barProp2.description).toEqual(fooProp2.description);
expect(fooProp2.memberof).toBe("Foo");
expect(barProp2.memberof).toBe("Bar");
expect(barProp2.description).toBe(fooProp2.description);
});
it('When an object is extended, it inherits methods set on parent prototype', function() {
expect(fooMethod1.memberof).toEqual("Foo");
expect(barMethod1.memberof).toEqual("Bar");
expect(barMethod1.description).toEqual(fooMethod1.description);
expect(fooMethod1.memberof).toBe("Foo");
expect(barMethod1.memberof).toBe("Bar");
expect(barMethod1.description).toBe(fooMethod1.description);
});
it('When an object is extended, it may override methods set on parent prototype', function() {
expect(fooMethod2.memberof).toEqual("Foo");
expect(fooMethod2.description).toEqual("Second parent method.");
expect(barMethod2.memberof).toEqual("Bar");
expect(barMethod2.description).toEqual("Second child method.");
expect(fooMethod2.memberof).toBe("Foo");
expect(fooMethod2.description).toBe("Second parent method.");
expect(barMethod2.memberof).toBe("Bar");
expect(barMethod2.description).toBe("Second child method.");
});
it('When an object is extended, and it overrides an ancestor method, the child does not include docs for the ancestor method.', function() {
expect(barMethod2All.length).toEqual(1);
expect(barMethod2All.length).toBe(1);
});
it('When an object is extended, it inherits properties set on grandparent prototype', function() {
expect(fooProp1.memberof).toEqual("Foo");
expect(barProp1.memberof).toEqual("Bar");
expect(bazProp1.memberof).toEqual("Baz");
expect(bazProp1.description).toEqual("Override prop1");
expect(bazMethod1.memberof).toEqual("Baz");
expect(bazMethod2.memberof).toEqual("Baz");
expect(bazMethod3.memberof).toEqual("Baz");
expect(fooProp1.memberof).toBe("Foo");
expect(barProp1.memberof).toBe("Bar");
expect(bazProp1.memberof).toBe("Baz");
expect(bazProp1.description).toBe("Override prop1");
expect(bazMethod1.memberof).toBe("Baz");
expect(bazMethod2.memberof).toBe("Baz");
expect(bazMethod3.memberof).toBe("Baz");
});
it('When an object is extended, and it overrides an ancestor property, the child does not include docs for the ancestor property.', function() {
expect(bazProp1All.length).toEqual(1);
expect(bazProp1All.length).toBe(1);
});
it('When a symbol has an @augments tag, and the parent is not documented, the doclet still has an augments property', function() {
expect(typeof qux.augments).toEqual('object');
expect(qux.augments[0]).toEqual('UndocumentedThing');
expect(typeof qux.augments).toBe('object');
expect(qux.augments[0]).toBe('UndocumentedThing');
});
it('When a symbol @augments multiple parents, it inherits methods from all parents', function() {
expect(FooBarMethod1).toBeDefined();
expect(FooBarMethod2).toBeDefined();
expect(FooBarMethod1.description).toBe(FooMethod1.description);
expect(FooBarMethod2.description).toBe(BarMethod2.description);
});
});

16
test/specs/tags/authortag.js
View File

@ -1,8 +1,18 @@
describe("@author tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/authortag.js'),
Thingy = docSet.getByLongname('Thingy')[0];
Thingy = docSet.getByLongname('Thingy')[0],
Thingy2 = docSet.getByLongname('Thingy2')[0];
it('When a symbol has a @author tag, the doclet has a author property with that value.', function() {
expect(Thingy.author[0]).toEqual('Michael Mathews <micmath@gmail.com>');
expect(Thingy.author).toBeDefined();
expect(Array.isArray(Thingy.author)).toBe(true);
expect(Thingy.author[0]).toBe('Michael Mathews <micmath@gmail.com>');
});
});
it('When a symbol has multiple @author tags, the doclet has a author property, an array with those values.', function() {
expect(Thingy2.author).toBeDefined();
expect(Array.isArray(Thingy2.author)).toBe(true);
expect(Thingy2.author).toContain('Jane Doe <jane.doe@gmail.com>');
expect(Thingy2.author).toContain('John Doe <john.doe@gmail.com>');
});
});

8
test/specs/tags/borrowstag.js
View File

@ -4,9 +4,9 @@ describe("@borrows tag", function() {
util = docSet.getByLongname('util').filter(function($) {
return ! $.undocumented;
})[0];
expect(util.borrowed.length).toEqual(1);
expect(util.borrowed[0].from).toEqual('trstr');
expect(util.borrowed[0].as).toEqual('trim');
expect(util.borrowed.length).toBe(1);
expect(util.borrowed[0].from).toBe('trstr');
expect(util.borrowed[0].as).toBe('trim');
});
it('When a symbol has a @borrows tag, the borrowed symbol is added to the symbol.', function() {
@ -19,6 +19,6 @@ describe("@borrows tag", function() {
return ! $.undocumented;
})[0];
expect(typeof str_rtrim).toEqual('object');
expect(typeof str_rtrim).toBe('object');
});
});

8
test/specs/tags/classdesctag.js Normal file
View File

@ -0,0 +1,8 @@
describe("@classdesc tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/classdesctag.js'),
doc = docSet.getByLongname('Foo')[0];
it('adds a classdesc property to the doclet with the description', function() {
expect(doc.classdesc).toBe('A description of the class.');
});
});

6
test/specs/tags/classtag.js
View File

@ -4,11 +4,11 @@ describe("@class tag", function() {
news = docSet.getByLongname('NewsSource')[0];
it('When a symbol has a @class tag, the doclet has a kind property set to "class".', function() {
expect(ticker.kind).toEqual('class');
expect(ticker.kind).toBe('class');
});
it('When a symbol has a @class tag with a value, the doclet has a name property set to that value.', function() {
expect(news.kind).toEqual('class');
expect(news.longname).toEqual('NewsSource');
expect(news.kind).toBe('class');
expect(news.longname).toBe('NewsSource');
});
});

28
test/specs/tags/constanttag.js Normal file
View File

@ -0,0 +1,28 @@
describe("@constant tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/constanttag.js'),
FOO = docSet.getByLongname('FOO')[0],
BAR = docSet.getByLongname('BAR')[0],
BAZ = docSet.getByLongname('BAZ')[0];
it("sets the doclet's 'kind' property to 'constant'", function() {
expect(FOO.kind).toBe('constant');
expect(BAR.kind).toBe('constant');
expect(BAZ.kind).toBe('constant');
});
it("If used as a standalone, takes the name from the code", function() {
expect(FOO.name).toBe('FOO');
});
it("If used with just a name, sets the doclet's name to that", function() {
expect(BAR.name).toBe('BAR');
});
it("If used with a name and a type, sets the doclet's name and type appropriately", function() {
expect(BAZ.name).toBe('BAZ');
expect(typeof BAZ.type).toBe('object');
expect(BAZ.type.names).toBeDefined();
expect(BAZ.type.names.length).toBe(1);
expect(BAZ.type.names[0]).toBe('string');
});
});

6
test/specs/tags/constructortag.js
View File

@ -3,11 +3,11 @@ describe("@constructor tag", function() {
feed = docSet.getByLongname('Feed')[0];
it('When a symbol has an @constructor tag, it is documented as a class.', function() {
expect(feed.kind).toEqual('class');
expect(feed.kind).toBe('class');
});
it('When a symbol has an @constructor tag and a @class tag, the value of the @class tag becomes the classdesc property.', function() {
expect(feed.classdesc).toEqual('Describe your class here.');
expect(feed.description).toEqual('Describe your constructor function here.');
expect(feed.classdesc).toBe('Describe your class here.');
expect(feed.description).toBe('Describe your constructor function here.');
});
});

24
test/specs/tags/constructstag.js
View File

@ -4,24 +4,24 @@ describe("@constructs tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/constructstag.js'),
textblock = docSet.getByLongname('TextBlock')[0];
expect(textblock.kind).toEqual('class');
expect(textblock.longname).toEqual('TextBlock');
expect(textblock.kind).toBe('class');
expect(textblock.longname).toBe('TextBlock');
});
it('When a symbol has an @constructs tag, it is documented as a class.', function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/constructstag2.js'),
menu = docSet.getByLongname('Menu')[0];
expect(menu.name).toEqual('Menu');
expect(menu.kind).toEqual('class');
expect(menu.name).toBe('Menu');
expect(menu.kind).toBe('class');
});
it('When a function symbol has an @constructs tag, any this-variables are ducumented as instance members of the class.', function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/constructstag3.js'),
personName = docSet.getByLongname('Person#name')[0];
expect(personName.memberof).toEqual('Person');
expect(personName.scope).toEqual('instance');
expect(personName.memberof).toBe('Person');
expect(personName.scope).toBe('instance');
});
it('When a function symbol has an @constructs tag with no value, in a @lends block with a "Name#" value, the function is documented as a constructor of "Name".', function() {
@ -30,15 +30,15 @@ describe("@constructs tag", function() {
return ! $.undocumented;
})[0];
expect(person.kind).toEqual('class');
expect(person.kind).toBe('class');
});
it('When a function symbol has an @constructs tag with no value, any this-variables are documented as instance members of the class.', function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/constructstag4.js'),
personName = docSet.getByLongname('Person#name')[0];
expect(personName.memberof).toEqual('Person');
expect(personName.scope).toEqual('instance');
expect(personName.memberof).toBe('Person');
expect(personName.scope).toBe('instance');
});
it('When a object literal property has an @constructs tag with no value, and the object has a @lends, the property is documented as the lent class.', function() {
@ -47,8 +47,8 @@ describe("@constructs tag", function() {
return ! $.undocumented;
})[0];
expect(duck.longname).toEqual('Duck');
expect(duck.kind).toEqual('class');
expect(duck.description).toEqual('Constructs a duck.');
expect(duck.longname).toBe('Duck');
expect(duck.kind).toBe('class');
expect(duck.description).toBe('Constructs a duck.');
});
});

2
test/specs/tags/copyrighttag.js
View File

@ -3,6 +3,6 @@ describe("@copyright tag", function() {
Thingy = docSet.getByLongname('Thingy')[0];
it('When a symbol has a @copyright tag, the doclet has a copyright property with that value.', function() {
expect(Thingy.copyright).toEqual('(c) 2011 Michael Mathews');
expect(Thingy.copyright).toBe('(c) 2011 Michael Mathews');
});
});

10
test/specs/tags/defaulttag.js
View File

@ -9,23 +9,23 @@ describe("@default tag", function() {
header = (docSet.getByLongname('header') || [])[0];
it('When symbol set to null has a @default tag with no text, the doclet\'s defaultValue property should be: null', function() {
expect(request.defaultvalue).toEqual('null');
expect(request.defaultvalue).toBe('null');
});
it('When symbol set to a string has a @default tag with no text, the doclet\'s defaultValue property should be that quoted string', function() {
expect(response.defaultvalue).toEqual('"ok"');
expect(response.defaultvalue).toBe('"ok"');
});
it('When symbol set to a number has a @default tag with no text, the doclet\'s defaultValue property should be that number.', function() {
expect(rcode.defaultvalue).toEqual('200');
expect(rcode.defaultvalue).toBe('200');
});
it('When symbol has a @default tag with text, the doclet\'s defaultValue property should be that text.', function() {
expect(win.defaultvalue).toEqual('the parent window');
expect(win.defaultvalue).toBe('the parent window');
});
it('When symbol has a @default tag with true.', function() {
expect(rvalid.defaultvalue).toEqual('true');
expect(rvalid.defaultvalue).toBe('true');
});
it('When symbol has a @default tag with false.', function() {

4
test/specs/tags/deprecatedtag.js
View File

@ -4,11 +4,11 @@ describe("@deprecated tag", function() {
bar = docSet.getByLongname('bar')[0];
it('When a symbol has a @deprecated tag with no value, the doclet has a deprecated property set to true.', function() {
expect(foo.deprecated).toEqual(true);
expect(foo.deprecated).toBe(true);
});
it('When a symbol has a @deprecated tag with a value, the doclet has a deprecated property set to that value.', function() {
expect(bar.deprecated).toEqual('since version 2.0');
expect(bar.deprecated).toBe('since version 2.0');
});
});

15
test/specs/tags/descriptiontag.js Normal file
View File

@ -0,0 +1,15 @@
describe("@description tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/descriptiontag.js'),
doc = docSet.getByLongname('x')[0],
doc2 = docSet.getByLongname('y')[0];
it("sets the doclet's 'description' property to the description", function() {
expect(doc2.description).toBeDefined();
expect(doc2.description).toBe('lkjasdf');
});
it("overrides the default description", function() {
expect(doc.description).toBeDefined();
expect(doc.description).toBe('halb halb halb');
});
});

10
test/specs/tags/enumtag.js
View File

@ -3,24 +3,24 @@ describe("@enum tag", function() {
tristate = docSet.getByLongname('TriState')[0];
it('When a symbol has a @enum tag, it has a properties array.', function() {
expect(typeof tristate.properties).toEqual('object');
expect(typeof tristate.properties).toBe('object');
});
it('If no @type is given for the property it is inherted from the enum.', function() {
expect(tristate.properties[0].type.names.join(', ')).toEqual('number');
expect(tristate.properties[0].type.names.join(', ')).toBe('number');
});
it('If no no comment is given for the property it is still included in the enum.', function() {
expect(tristate.properties[1].longname).toEqual('TriState.FALSE');
expect(tristate.properties[1].longname).toBe('TriState.FALSE');
expect(tristate.properties[1].undocumented).toBeUndefined();
});
it('A property of an enum gets its defaultvalue set.', function() {
expect(tristate.properties[1].defaultvalue).toEqual('-1');
expect(tristate.properties[1].defaultvalue).toBe('-1');
});
it('If a @type is given for the property it is reflected in the property value.', function() {
expect(tristate.properties[2].type.names.join(', ')).toEqual('boolean');
expect(tristate.properties[2].type.names.join(', ')).toBe('boolean');
});
it('An enum does not contain any circular references.', function() {

27
test/specs/tags/eventfirestag.js
View File

@ -1,23 +1,30 @@
describe("@event and @fires tags", function() {
/*global describe: true, expect: true, it: true, jasmine: true */
describe('@event and @fires/@emits tags', function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/eventfirestag.js'),
snowballMethod = docSet.getByLongname('Hurl#snowball')[0],
snowballEvent = docSet.getByLongname('Hurl#event:snowball')[0];
snowballEvent = docSet.getByLongname('Hurl#event:snowball')[0],
footballMatchMethod = docSet.getByLongname('Hurl#footballMatch')[0];
// @event tag
it('When a symbol has an @event tag, the doclet is of kind "event".', function() {
expect(snowballEvent.kind).toEqual('event');
expect(snowballEvent.kind).toBe('event');
});
// @fires tag
// @fires/@emits tag
it('When a symbol has a @fires tag, the doclet has an array named "fires".', function() {
expect(typeof snowballMethod.fires).toEqual('object');
expect(typeof snowballMethod.fires).toBe('object');
});
it('When a symbol has a fires array, the members have the event namespace.', function() {
expect(snowballMethod.fires[0]).toEqual('Hurl#event:snowball');
it('When a symbol has an @emits tag, the doclet has an array named "fires".', function() {
expect(typeof footballMatchMethod.fires).toBe('object');
});
it('When a symbol has a fires array with a name that already has an event: namespace, it doesn\'t have a secong namespace applied.', function() {
expect(snowballMethod.fires[1]).toEqual('Hurl#event:brick');
it('When a symbol has a "fires" array, the members have the "event:" namespace.', function() {
expect(snowballMethod.fires[0]).toBe('Hurl#event:snowball');
});
});
it('When a symbol has a "fires" array with a name that already has an "event:" namespace, ' +
'it does not have a second namespace applied.', function() {
expect(snowballMethod.fires[1]).toBe('Hurl#event:brick');
});
});

22
test/specs/tags/exampletag.js Normal file
View File

@ -0,0 +1,22 @@
describe("@example tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/exampletag.js'),
doc = docSet.getByLongname('x')[0],
doc2 = docSet.getByLongname('y')[0],
txt = 'console.log("foo");\nconsole.log("bar");',
txt2 = '<caption>Example 2</caption>\n1 + 2;';
it("creates an 'examples' property on the doclet with the example", function() {
expect(doc.examples).toBeDefined();
expect(Array.isArray(doc.examples)).toBe(true);
expect(doc.examples.length).toBe(1);
expect(doc.examples).toContain(txt);
});
it("can be specified multiple times on one doclet", function() {
expect(doc2.examples).toBeDefined();
expect(Array.isArray(doc2.examples)).toBe(true);
expect(doc2.examples.length).toBe(2);
expect(doc2.examples).toContain(txt);
expect(doc2.examples).toContain(txt2);
});
});

12
test/specs/tags/exceptiontag.js
View File

@ -5,13 +5,13 @@ describe("@exception tag", function() {
pez = docSet.getByLongname('pez')[0];
it('When a symbol has an @exception tag, the doclet has a exception property set to that value.', function() {
expect(typeof foo.exceptions).toEqual('object');
expect(foo.exceptions.length).toEqual(1);
expect(typeof foo.exceptions).toBe('object');
expect(foo.exceptions.length).toBe(1);
expect(typeof bar.exceptions).toEqual('object');
expect(bar.exceptions.length).toEqual(1);
expect(typeof bar.exceptions).toBe('object');
expect(bar.exceptions.length).toBe(1);
expect(typeof pez.exceptions).toEqual('object');
expect(pez.exceptions.length).toEqual(1);
expect(typeof pez.exceptions).toBe('object');
expect(pez.exceptions.length).toBe(1);
});
});

18
test/specs/tags/functiontag.js Normal file
View File

@ -0,0 +1,18 @@
describe("@function tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/functiontag.js'),
doc = docSet.getByLongname('Foo')[0],
doc2 = docSet.getByLongname('Bar')[0];
it("sets the doclet's kind to 'function'", function() {
expect(doc.kind).toBe('function');
expect(doc2.kind).toBe('function');
});
it("sets the doclet's name to the tag value, if provided", function() {
expect(doc.name).toBe('Foo');
expect(doc2.name).toBe('Bar');
});
// parameter etc tests take place elsewhere: on its own, all @func does is
// set doclet.kind to function and sets the doclet's name.
});

12
test/specs/tags/globaltag.js
View File

@ -5,10 +5,10 @@ describe("@global tag", function() {
var found = docSet.getByLongname('foo').filter(function($) {
return ! $.undocumented;
});
expect(found[0].name).toEqual('foo');
expect(found[0].longname).toEqual('foo');
expect(found[0].name).toBe('foo');
expect(found[0].longname).toBe('foo');
expect(found[0].memberof).toBeUndefined();
expect(found[0].scope).toEqual('global');
expect(found[0].scope).toBe('global');
});
@ -16,9 +16,9 @@ describe("@global tag", function() {
var found = docSet.getByLongname('Bar').filter(function($) {
return ! $.undocumented;
});
expect(found[0].name).toEqual('Bar');
expect(found[0].longname).toEqual('Bar');
expect(found[0].name).toBe('Bar');
expect(found[0].longname).toBe('Bar');
expect(found[0].memberof).toBeUndefined();
expect(found[0].scope).toEqual('global');
expect(found[0].scope).toBe('global');
});
});

4
test/specs/tags/ignoretag.js
View File

@ -3,7 +3,7 @@ describe("@ignore tag", function() {
foo = docSet.getByLongname('foo')[0];
it('When a symbol has an @ignore tag, the doclet has a ignore property set to true.', function() {
expect(foo.ignore).toEqual(true);
expect(foo.ignore).toBe(true);
});
it('When a symbol has an @ignore tag with a value an error is thrown', function() {
@ -11,7 +11,7 @@ describe("@ignore tag", function() {
docSet = jasmine.getDocSetFromFile('test/fixtures/ignoretag2.js');
foo = docSet.getByLongname('foo')[0];
} catch (e) {
expect(e.name).toEqual('TagValueNotPermittedError');
expect(e.name).toBe('TagValueNotPermittedError');
};
});
});

8
test/specs/tags/kindtag.js Normal file
View File

@ -0,0 +1,8 @@
describe("@kind tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/kindtag.js'),
doc = docSet.getByLongname('x')[0];
it("sets the doclet's 'kind' property to the tag value", function() {
expect(doc.kind).toBeDefined();
expect(doc.kind).toBe('function');
});
});

16
test/specs/tags/lendstag.js Normal file
View File

@ -0,0 +1,16 @@
describe("@lends tag", function() {
// see also specs/documentation/lends.js for tests on @lends behaviour.
var doclet = require('jsdoc/doclet'),
doc = new doclet.Doclet('/** @lends */', {}),
doc2 = new doclet.Doclet('/** @lends MyClass# */', {});
it("sets the doclet's 'alias' property to the tag value or <global>", function() {
expect(doc.alias).toBe('<global>');
expect(doc2.alias).toBe('MyClass#');
});
it("sets the doclet's 'undocumented' property to 'true'", function() {
expect(doc.undocumented).toBeTruthy();
expect(doc2.undocumented).toBeTruthy();
});
});

8
test/specs/tags/licensetag.js Normal file
View File

@ -0,0 +1,8 @@
describe("@license tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/licensetag.js'),
doc = docSet.getByLongname('x')[0];
it("sets the doclet's 'license' property to the tag value", function() {
expect(doc.license).toBe('GPL v2');
});
});

32
test/specs/tags/memberoftag.js
View File

@ -6,11 +6,11 @@ describe("@memberof tag", function() {
Data = docSet.getByLongname('mathlib.Data')[0],
point = docSet.getByLongname('mathlib.Data#point')[0];
expect(typeof Data).toEqual('object');
expect(typeof point).toEqual('object');
expect(typeof Data).toBe('object');
expect(typeof point).toBe('object');
expect(Data.memberof).toEqual('mathlib');
expect(Data.name).toEqual('Data');
expect(Data.memberof).toBe('mathlib');
expect(Data.name).toBe('Data');
});
it('A symbol within a namespace for which no scope is specified.', function() {
@ -18,7 +18,7 @@ describe("@memberof tag", function() {
doOtherStuff = docSet.getByLongname('doStuff.doOtherStuff')[0];
expect(doOtherStuff).toBeDefined();
expect(doOtherStuff.scope).toEqual('static');
expect(doOtherStuff.scope).toBe('static');
});
it('A symbol in which name === memberof.', function() {
@ -26,7 +26,7 @@ describe("@memberof tag", function() {
doStuff = docSet.getByLongname('doStuff.doStuff')[0];
expect(doStuff).toBeDefined();
expect(doStuff.scope).toEqual('static');
expect(doStuff.scope).toBe('static');
});
describe ("static", function() {
@ -36,20 +36,20 @@ describe("@memberof tag", function() {
it('A symbol is documented as a static @memberof a class.', function() {
//it should appear as a static member of that class
expect(typeof cache).toEqual('object');
expect(cache.memberof).toEqual('Observable');
expect(cache.scope).toEqual('static');
expect(cache.name).toEqual('cache');
expect(cache.longname).toEqual('Observable.cache');
expect(typeof cache).toBe('object');
expect(cache.memberof).toBe('Observable');
expect(cache.scope).toBe('static');
expect(cache.name).toBe('cache');
expect(cache.longname).toBe('Observable.cache');
});
it('A symbol is documented as a static @memberof a class prototype.', function() {
//it should appear as an instance member of that class
expect(typeof publish).toEqual('object');
expect(publish.memberof).toEqual('Observable');
expect(publish.scope).toEqual('instance');
expect(publish.name).toEqual('publish');
expect(publish.longname).toEqual('Observable#publish');
expect(typeof publish).toBe('object');
expect(publish.memberof).toBe('Observable');
expect(publish.scope).toBe('instance');
expect(publish.name).toBe('publish');
expect(publish.longname).toBe('Observable#publish');
});
});

25
test/specs/tags/membertag.js Normal file
View File

@ -0,0 +1,25 @@
describe("@member tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/membertag.js'),
doc = docSet.getByLongname('x')[0],
doc2 = docSet.getByLongname('foobar')[0],
doc3 = docSet.getByLongname('baz')[0];
it("sets the doclet's 'kind' property to 'member'", function() {
expect(doc.kind).toBe('member');
expect(doc2.kind).toBe('member');
expect(doc3.kind).toBe('member');
});
it("If specified with a name, sets the doclet's name property", function() {
expect(doc.name).toBe('x');
expect(doc2.name).toBe('foobar');
expect(doc3.name).toBe('baz');
});
it("If specified with a type and name, sets the doclet's type appropriately", function() {
expect(doc3.type).toBeDefined();
expect(Array.isArray(doc3.type.names)).toBeTruthy();
expect(doc3.type.names.length).toBe(1);
expect(doc3.type.names[0]).toBe('string');
});
});

19
test/specs/tags/mixestag.js Normal file
View File

@ -0,0 +1,19 @@
describe("@mixes tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/mixintag.js'),
FormButton = docSet.getByLongname('FormButton')[0],
MyClass = docSet.getByLongname('MyClass')[0];
it("When a symbol has a @mixes tag, it gets an array property 'mixes' with the name of the mixin", function() {
expect(FormButton.mixes).toBeDefined();
expect(Array.isArray(FormButton.mixes)).toBe(true);
expect(FormButton.mixes.length).toBe(1);
expect(FormButton.mixes[0]).toBe('Eventful');
});
it("A symbol can @mixes multiple mixins and they are all added.", function() {
expect(MyClass.mixes).toBeDefined();
expect(MyClass.mixes.length).toBe(2);
expect(MyClass.mixes).toContain('Eventful');
expect(MyClass.mixes).toContain('AnotherMixin');
});
});

13
test/specs/tags/mixintag.js Normal file
View File

@ -0,0 +1,13 @@
describe("@mixin tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/mixintag.js'),
Eventful = docSet.getByLongname('Eventful')[0],
Mixin = docSet.getByLongname('AnotherMixin')[0];
it("When a symbol has a @mixin tag, the doclet's 'kind' property is set to 'mixin'", function() {
expect(Eventful.kind).toBe('mixin');
});
it("When a symbol has a @mixin tag, its name is set to the tag's value (if present)", function() {
expect(Mixin).toBeDefined();
});
});

20
test/specs/tags/moduletag.js
View File

@ -5,13 +5,13 @@ describe("@module tag", function() {
title = docSet.getByLongname('module:bookshelf.Book#title')[0];
it('When a global symbol starts with "this" and is in a file with a @module tag, the symbol is documented as a member of that module.', function() {
expect(typeof book).toEqual('object');
expect(book.memberof).toEqual('module:bookshelf');
expect(typeof book).toBe('object');
expect(book.memberof).toBe('module:bookshelf');
});
it('When an inner symbol starts with "this" and is in a file with a @module tag, the symbol is documented as a member of its enclosing constructor.', function() {
expect(typeof title).toEqual('object');
expect(title.memberof).toEqual('module:bookshelf.Book');
expect(typeof title).toBe('object');
expect(title.memberof).toBe('module:bookshelf.Book');
});
});
@ -24,18 +24,18 @@ describe("@module tag", function() {
darken = docSet.getByLongname('module:color/mixer.darken')[0];
it('When a @module tag defines a module module, a symbol of kind "module" is documented', function() {
expect(typeof mixer).toEqual('object');
expect(mixer.kind).toEqual('module');
expect(typeof mixer).toBe('object');
expect(mixer.kind).toBe('module');
});
it('When an object literal is lent to a module with a @lends tag, A member of that object literal is documented as a member of the module', function() {
expect(typeof blend).toEqual('object');
expect(blend.kind).toEqual('function');
expect(typeof blend).toBe('object');
expect(blend.kind).toBe('function');
});
it('When a documented symbol is a member of a namespace "exports", it is documented as a member of the module', function() {
expect(typeof darken).toEqual('object');
expect(darken.kind).toEqual('function');
expect(typeof darken).toBe('object');
expect(darken.kind).toBe('function');
});
});
});

25
test/specs/tags/namespacetag.js Normal file
View File

@ -0,0 +1,25 @@
describe("@namespace tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/namespacetag.js'),
doc = docSet.getByLongname('x')[0],
doc2 = docSet.getByLongname('Foo')[0],
doc3 = docSet.getByLongname('Bar')[0];
it("sets the doclet's kind to 'namespace'", function () {
expect(doc.kind).toBe('namespace');
expect(doc2.kind).toBe('namespace');
expect(doc3.kind).toBe('namespace');
});
it("sets the doclet's name to the tag value (if provided)", function() {
expect(doc.name).toBe('x');
expect(doc2.name).toBe('Foo');
expect(doc3.name).toBe('Bar');
});
it("sets the doclet's type (if provided in @namespace)", function() {
expect(doc3.type).toBeDefined();
expect(Array.isArray(doc3.type.names)).toBeTruthy();
expect(doc3.type.names.length).toBe(1);
expect(doc3.type.names[0]).toBe('function');
});
});

4
test/specs/tags/overviewtag.js
View File

@ -13,6 +13,6 @@ describe("@overview tag", function() {
});
it("The name and longname should be equal", function() {
expect(doclets[0].name).toEqual(doclets[0].longname);
expect(doclets[0].name).toBe(doclets[0].longname);
});
});
});

56
test/specs/tags/paramtag.js
View File

@ -9,60 +9,60 @@ describe("@param tag", function() {
commit = docSet.getByLongname('commit')[0];
it('When a symbol has an @param tag with a type before the name, the doclet has a params property that includes that param.', function() {
expect(typeof find.params).toEqual('object');
expect(find.params.length).toEqual(1);
expect(find.params[0].type.names.join(', ')).toEqual('String, Array<String>');
expect(find.params[0].name).toEqual('targetName');
expect(find.params[0].description).toEqual('The name (or names) of what to find.');
expect(typeof find.params).toBe('object');
expect(find.params.length).toBe(1);
expect(find.params[0].type.names.join(', ')).toBe('String, Array<String>');
expect(find.params[0].name).toBe('targetName');
expect(find.params[0].description).toBe('The name (or names) of what to find.');
});
it('When a symbol has an @param tag with only a type and name, the doclet has a params property that includes that param.', function() {
expect(typeof bind.params).toEqual('object');
expect(bind.params.length).toEqual(1);
expect(bind.params[0].type.names.join(', ')).toEqual('function');
expect(bind.params[0].name).toEqual('callback');
expect(typeof bind.params).toBe('object');
expect(bind.params.length).toBe(1);
expect(bind.params[0].type.names.join(', ')).toBe('function');
expect(bind.params[0].name).toBe('callback');
expect(bind.params[0].description).toBeUndefined();
});
it('When a symbol has an @param tag with only a type, the doclet has a params property that includes that param.', function() {
expect(typeof unbind.params).toEqual('object');
expect(unbind.params.length).toEqual(1);
expect(unbind.params[0].type.names.join(', ')).toEqual('function');
expect(typeof unbind.params).toBe('object');
expect(unbind.params.length).toBe(1);
expect(unbind.params[0].type.names.join(', ')).toBe('function');
expect(unbind.params[0].description).toBeUndefined();
});
it('When a symbol has an @param tag with no type, the doclet has a params property that includes that param.', function() {
expect(typeof getElement.params).toEqual('object');
expect(getElement.params.length).toEqual(1);
expect(typeof getElement.params).toBe('object');
expect(getElement.params.length).toBe(1);
expect(getElement.params[0].type).toBeUndefined();
expect(getElement.params[0].name).toEqual('id');
expect(getElement.params[0].description).toEqual('The id of the element.');
expect(getElement.params[0].name).toBe('id');
expect(getElement.params[0].description).toBe('The id of the element.');
});
it('When a symbol has an @param tag with a non-alpha name like "...", the doclet has a params property that includes that param.', function() {
expect(typeof combine.params).toEqual('object');
expect(combine.params.length).toEqual(1);
expect(typeof combine.params).toBe('object');
expect(combine.params.length).toBe(1);
expect(combine.params[0].type).toBeUndefined();
expect(combine.params[0].name).toEqual('...');
expect(combine.params[0].description).toEqual('Two or more elements.');
expect(combine.params[0].name).toBe('...');
expect(combine.params[0].description).toBe('Two or more elements.');
});
it('When a symbol has an @param tag with name followed by a dash, the doclet has a params property that includes that param.', function() {
expect(typeof split.params).toEqual('object');
expect(split.params.length).toEqual(1);
expect(typeof split.params).toBe('object');
expect(split.params.length).toBe(1);
expect(split.params[0].type).toBeUndefined();
expect(split.params[0].name).toEqual('delimiter');
expect(split.params[0].description).toEqual('What to split on.');
expect(split.params[0].name).toBe('delimiter');
expect(split.params[0].description).toBe('What to split on.');
});
it('When a symbol has an @param tag with no name or type, the doclet has a params property that includes that param.', function() {
expect(typeof commit.params).toEqual('object');
expect(commit.params.length).toEqual(1);
expect(typeof commit.params).toBe('object');
expect(commit.params.length).toBe(1);
expect(commit.params[0].type).toBeUndefined();
expect(commit.params[0].description).toEqual('If true make the commit atomic.');
expect(commit.params[0].description).toBe('If true make the commit atomic.');
});
it('When a symbol has an @param tag with no name and a name is given in the code, the doclet has a params property that includes that param with the name from the code.', function() {
expect(commit.params[0].name).toEqual('atomic');
expect(commit.params[0].name).toBe('atomic');
});
});

2
test/specs/tags/privatetag.js
View File

@ -4,6 +4,6 @@ describe("@private tag", function() {
bar = docSet.getByLongname('Foo#bar')[0];
it('When a symbol has an @private tag, the doclet has an access property that is "private".', function() {
expect(foo.access).toEqual('private');
expect(foo.access).toBe('private');
});
});

14
test/specs/tags/propertytag.js
View File

@ -3,13 +3,13 @@ describe("@property tag", function() {
myobject = docSet.getByLongname('myobject')[0];
it('When a symbol has an @property tag with a those properties appear in the parsed object.', function() {
expect(typeof myobject.properties).toEqual('object');
expect(myobject.properties.length).toEqual(3);
expect(myobject.properties[0].name).toEqual('defaults');
expect(myobject.properties[1].name).toEqual('defaults.a');
expect(myobject.properties[2].name).toEqual('defaults.b');
expect(myobject.properties[0].description).toEqual('The default values.');
expect(myobject.properties[0].type.names[0]).toEqual('Object');
expect(typeof myobject.properties).toBe('object');
expect(myobject.properties.length).toBe(3);
expect(myobject.properties[0].name).toBe('defaults');
expect(myobject.properties[1].name).toBe('defaults.a');
expect(myobject.properties[2].name).toBe('defaults.b');
expect(myobject.properties[0].description).toBe('The default values.');
expect(myobject.properties[0].type.names[0]).toBe('Object');
});
});

2
test/specs/tags/readonlytag.js
View File

@ -4,6 +4,6 @@ describe("@readonly tag", function() {
length = docSet.getByLongname('Collection#length')[0];
it('When a symbol has an @readonly tag, the doclet has an readonly property that is true.', function() {
expect(length.readonly).toEqual(true);
expect(length.readonly).toBe(true);
});
});

10
test/specs/tags/requirestag.js
View File

@ -4,11 +4,11 @@ describe("@requires tag", function() {
bar = docSet.getByLongname('bar')[0];
it('When a symbol has an @requires tag, the doclet has a requires property that includes that value, with the "module:" namespace added.', function() {
expect(typeof foo.requires).toEqual('object');
expect(foo.requires[0]).toEqual('module:foo/helper');
expect(typeof foo.requires).toBe('object');
expect(foo.requires[0]).toBe('module:foo/helper');
expect(typeof bar.requires).toEqual('object');
expect(bar.requires[0]).toEqual('module:foo');
expect(bar.requires[1]).toEqual('module:Pez#blat');
expect(typeof bar.requires).toBe('object');
expect(bar.requires[0]).toBe('module:foo');
expect(bar.requires[1]).toBe('module:Pez#blat');
});
});

18
test/specs/tags/returnstag.js
View File

@ -4,15 +4,15 @@ describe("@returns tag", function() {
bind = docSet.getByLongname('bind')[0];
it('When a symbol has an @returns tag with a type and description, the doclet has a returns array that includes that return.', function() {
expect(typeof find.returns).toEqual('object');
expect(find.returns.length).toEqual(1);
expect(find.returns[0].type.names.join(', ')).toEqual('String, Array<String>');
expect(find.returns[0].description).toEqual('The names of the found item(s).');
expect(typeof find.returns).toBe('object');
expect(find.returns.length).toBe(1);
expect(find.returns[0].type.names.join(', ')).toBe('String, Array<String>');
expect(find.returns[0].description).toBe('The names of the found item(s).');
});
it('When a symbol has an @param tag with only a type and name, the doclet has a returns array property that includes that param.', function() {
expect(typeof bind.returns).toEqual('object');
expect(bind.returns.length).toEqual(1);
expect(bind.returns[0].description).toEqual('The binding id.');
it('When a symbol has an @returns tag with only a description, the doclet has a returns array property that includes that return.', function() {
expect(typeof bind.returns).toBe('object');
expect(bind.returns.length).toBe(1);
expect(bind.returns[0].description).toBe('The binding id.');
});
});
});

31
test/specs/tags/scopetags.js Normal file
View File

@ -0,0 +1,31 @@
describe('scope tags', function () {
var docSet = jasmine.getDocSetFromFile('test/fixtures/scopetags.js');
// @inner, @instance, @static (@global has its own file)
describe("@inner tag", function() {
var doc = docSet.getByLongname('module:scopetags~myInner')[0];
it("sets the doclet's 'scope' property to 'inner'", function() {
expect(doc.scope).toBeDefined();
expect(doc.scope).toBe('inner');
});
});
describe("@instance tag", function() {
var doc = docSet.getByLongname('module:scopetags#myInstance')[0];
it("sets the doclet's 'scope' property to 'instance'", function() {
expect(doc.scope).toBeDefined();
expect(doc.scope).toBe('instance');
});
});
describe("@static tag", function() {
var doc = docSet.getByLongname('module:scopetags.myStatic')[0];
it("sets the doclet's 'scope' property to 'static'", function() {
expect(doc.scope).toBeDefined();
expect(doc.scope).toBe('static');
});
});
});

8
test/specs/tags/seetag.js
View File

@ -4,10 +4,10 @@ describe("@see tag", function() {
bar = docSet.getByLongname('bar')[0];
it('When a symbol has an @see tag, the doclet has a see property that includes that value.', function() {
expect(typeof foo.see).toEqual('object');
expect(foo.see[0]).toEqual('{@link bar}');
expect(typeof foo.see).toBe('object');
expect(foo.see[0]).toBe('{@link bar}');
expect(typeof bar.see).toEqual('object');
expect(bar.see[0]).toEqual('http://example.com/someref');
expect(typeof bar.see).toBe('object');
expect(bar.see[0]).toBe('http://example.com/someref');
});
});

2
test/specs/tags/sincetag.js
View File

@ -3,6 +3,6 @@ describe("@since tag", function() {
foo = docSet.getByLongname('foo')[0];
it('When a symbol has an @since tag, the doclet has a since property set to true.', function() {
expect(foo.since).toEqual('1.2.3');
expect(foo.since).toBe('1.2.3');
});
});

8
test/specs/tags/summarytag.js Normal file
View File

@ -0,0 +1,8 @@
describe("@summary tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/summarytag.js'),
doc = docSet.getByLongname('Sam')[0];
it("sets the doclet's 'summary' property to the tag value", function() {
expect(doc.summary).toBe('I do not like green eggs and ham!');
});
});

10
test/specs/tags/thistag.js
View File

@ -4,13 +4,13 @@ describe("@this tag", function() {
fooName = docSet.getByLongname('Foo#name')[0];
it('When a symbol has a @this tag, the doclet has a this property that is set to that value.', function() {
expect(setName['this']).toEqual('Foo');
expect(setName['this']).toBe('Foo');
});
it('When a this symbol is documented inside a function with a @this tag, the symbol is documented as a member of that tags value.', function() {
expect(typeof fooName).toEqual('object');
expect(fooName.name).toEqual('name');
expect(fooName.memberof).toEqual('Foo');
expect(fooName.scope).toEqual('instance');
expect(typeof fooName).toBe('object');
expect(fooName.name).toBe('name');
expect(fooName.memberof).toBe('Foo');
expect(fooName.scope).toBe('instance');
});
});

13
test/specs/tags/todotag.js Normal file
View File

@ -0,0 +1,13 @@
describe("@todo tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/todotag.js'),
doc = docSet.getByLongname('x')[0];
it("adds the entries into a 'todo' array on the doclet", function() {
expect(doc.todo).toBeDefined();
expect(Array.isArray(doc.todo)).toBeTruthy();
expect(doc.todo.length).toBe(2);
expect(doc.todo).toContain('something');
expect(doc.todo).toContain('something else');
});
});

13
test/specs/tags/tutorialtag.js Normal file
View File

@ -0,0 +1,13 @@
describe("@tutorial tag", function() {
// these are tests for the block usage, not the inline usage. see util/templateHelper for that.
var docSet = jasmine.getDocSetFromFile('test/fixtures/tutorialtag.js'),
doc = docSet.getByLongname('x')[0];
it("adds the listed tutorials to a 'tutorials' array on the doclet", function () {
expect(Array.isArray(doc.tutorials)).toBeTruthy();
expect(doc.tutorials.length).toBe(2);
expect(doc.tutorials).toContain('tute1');
expect(doc.tutorials).toContain('tute2');
});
});

16
test/specs/tags/typedeftag.js
View File

@ -3,19 +3,19 @@ describe("@typedef tag", function() {
numberlike = docSet.getByLongname('calc.NumberLike')[0];
it('When a symbol has an @typedef tag, the doclet has a kind property set to "typedef".', function() {
expect(numberlike.kind).toEqual('typedef');
expect(numberlike.kind).toBe('typedef');
});
it('When a symbol has an @typedef tag with a type, the doclet has a type property set to that type.', function() {
expect(typeof numberlike.type).toEqual('object');
expect(typeof numberlike.type.names).toEqual('object');
expect(numberlike.type.names.length).toEqual(2);
expect(numberlike.type.names[0]).toEqual('string');
expect(numberlike.type.names[1]).toEqual('number');
expect(typeof numberlike.type).toBe('object');
expect(typeof numberlike.type.names).toBe('object');
expect(numberlike.type.names.length).toBe(2);
expect(numberlike.type.names[0]).toBe('string');
expect(numberlike.type.names[1]).toBe('number');
});
it('When a symbol has an @typedef tag with a name, the doclet has a name property set to that name.', function() {
expect(numberlike.name).toEqual('NumberLike');
expect(numberlike.longname).toEqual('calc.NumberLike');
expect(numberlike.name).toBe('NumberLike');
expect(numberlike.longname).toBe('calc.NumberLike');
});
});

8
test/specs/tags/typekind.js
View File

@ -4,12 +4,12 @@ describe("@kind tag with type", function() {
port = docSet.getByLongname('module:blog/server.port')[0];
it('When a module symbol has an kind tag, that includes a {type} clause, the doclet has a type property set to that {type} clause', function() {
expect(typeof blog.type).toEqual('object');
expect(blog.type.names.join(', ')).toEqual('ConnectServer');
expect(typeof blog.type).toBe('object');
expect(blog.type.names.join(', ')).toBe('ConnectServer');
});
it('When a property symbol has an kind tag, that includes a {type} clause, the doclet has a type property set to that {type} clause', function() {
expect(typeof port.type).toEqual('object');
expect(port.type.names.join(', ')).toEqual('number');
expect(typeof port.type).toBe('object');
expect(port.type.names.join(', ')).toBe('number');
});
});

8
test/specs/tags/typetag.js
View File

@ -4,12 +4,12 @@ describe("@type tag", function() {
bar = docSet.getByLongname('bar')[0];
it('When a symbol has an @type tag, the doclet has a type property set to that value\'s type.', function() {
expect(typeof foo.type).toEqual('object');
expect(typeof foo.type.names).toEqual('object');
expect(foo.type.names.join(', ')).toEqual('string, Array<string>');
expect(typeof foo.type).toBe('object');
expect(typeof foo.type.names).toBe('object');
expect(foo.type.names.join(', ')).toBe('string, Array<string>');
});
it('When a symbol has an @type tag set to a plain string, the doclet has a type property set to that string as if it were a type.', function() {
expect(bar.type.names.join(', ')).toEqual('integer');
expect(bar.type.names.join(', ')).toBe('integer');
});
});

13
test/specs/tags/undocumentedtag.js Normal file
View File

@ -0,0 +1,13 @@
describe("@undocumented tag", function() {
var docSet = jasmine.getDocSetFromFile('test/fixtures/undocumentedtag.js'),
doc = docSet.getByLongname('x')[0];
it("sets the doclet's 'undocumented' property to true", function () {
expect(doc.undocumented).toBeTruthy();
});
it("clears the doclet's 'comment' property", function () {
expect(doc.comment).toBe('');
});
});

2
test/specs/tags/versiontag.js
View File

@ -3,6 +3,6 @@ describe("@version tag", function() {
foo = docSet.getByLongname('foo')[0];
it('When a symbol has an @version tag, the doclet has a version property set to that value.', function() {
expect(foo.version).toEqual('1.2.3');
expect(foo.version).toBe('1.2.3');
});
});

1
test/tutorials/tutorials/constructor.md Normal file
View File

@ -0,0 +1 @@
This tutorial has a tricksy name to make sure we are not loading Array.constructor or Object.constructor.