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

hook up node visitors; gratuitous refactor of 'runtime' module (formerly 'vm'); move runtime-specific code

Browse Source 
includes updated Rhino jar:
https://github.com/hegemonic/rhino/commit/b63c00d5
This commit is contained in:
Jeff Williams 2013-07-05 09:11:27 -07:00
parent 1f627daee2
commit c058a60ed1
27 changed files with 718 additions and 198 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -28,7 +28,7 @@
"underscore": "1.4.2",
"wrench": "1.3.9"
},
"bin": "./nodejs/bin/jsdoc",
"bin": "./node/bin/jsdoc",
"bugs": "https://github.com/jsdoc3/jsdoc/issues",
"author": {
"name": "Michael Mathews",

10
jsdoc.js
View File

@ -72,9 +72,9 @@ require('lib/jsdoc/util/global').env = {
// initialize the environment for the current JavaScript VM
(function(args) {
var vm = require('jsdoc/util/vm').vm;
var runtime = require('jsdoc/util/runtime').getRuntime();
// TODO: may need to move this file to support Node.js
require('initialize')[vm](args);
require('initialize')[runtime](args);
})( Array.prototype.slice.call(arguments, 0) );
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~//
@ -87,7 +87,11 @@ require('lib/jsdoc/util/global').env = {
require('lib/jsdoc/util/global').app = {
jsdoc: {
scanner: new (require('jsdoc/src/scanner').Scanner)(),
parser: new (require('jsdoc/src/parser').Parser)(),
// TODO: allow the config file to specify the parser module
parser: (function() {
var modulePath = require('jsdoc/util/runtime').getModulePath('jsdoc/src/parser');
return new ( require(modulePath) ).Parser();
})(),
name: require('jsdoc/name')
}
};

4
lib/jsdoc/fs.js
View File

@ -4,11 +4,11 @@
*/
var fs = exports.fs = require('fs');
var vm = require('jsdoc/util/vm');
var runtime = require('jsdoc/util/runtime');
// export the VM-specific implementations of the extra methods
// TODO: document extra methods here
var extras = vm.getModule('fs');
var extras = require( runtime.getModulePath('fs') );
Object.keys(extras).forEach(function(extra) {
exports[extra] = extras[extra];
});

6
lib/jsdoc/path.js
View File

@ -5,7 +5,7 @@
var fs = require('fs');
var path = require('path');
var vm = require('jsdoc/util/vm');
var runtime = require('jsdoc/util/runtime');
function prefixReducer(previousPath, current) {
@ -71,7 +71,7 @@ exports.commonPrefix = function(paths) {
* @param {string} path The path to convert.
* @return {string} A URI that meets the operating system's requirements, or the original path.
*/
var pathToUri = vm.getModule('jsdoc').pathToUri;
var pathToUri = require( runtime.getModulePath('jsdoc') ).pathToUri;
// TODO: do we need this? if so, any way to stop exporting it?
/**
@ -82,7 +82,7 @@ var pathToUri = vm.getModule('jsdoc').pathToUri;
* @param {string} uri The URI to convert.
* @return {string} A path that meets the operating system's requirements.
*/
exports._uriToPath = vm.getModule('jsdoc').uriToPath;
exports._uriToPath = require( runtime.getModulePath('jsdoc') ).uriToPath;
/**
* Retrieve the fully qualified path to the requested resource.

7
lib/jsdoc/plugins.js
View File

@ -36,10 +36,15 @@ exports.installPlugins = function(plugins, p) {
plugin.defineTags(dictionary);
}
//...add a node visitor
//...add a Rhino node visitor (deprecated in JSDoc 3.3)
if (plugin.nodeVisitor) {
parser.addNodeVisitor(plugin.nodeVisitor);
}
//...add a Mozilla Parser API node visitor
if (plugin.astNodeVisitor) {
parser.addAstNodeVisitor(plugin.astNodeVisitor);
}
}
}
};

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

@ -24,13 +24,33 @@ var SCHEMA = 'javascript:';
* @example <caption>Create a new parser.</caption>
* var jsdocParser = new (require('jsdoc/src/parser').Parser)();
*/
var Parser = exports.Parser = function() {
var Parser = exports.Parser = function(builderInstance, visitorInstance, walkerInstance) {
this.clear();
// TODO: require the appropriate AstBuilder based on a config setting
this._astBuilder = new (require('jsdoc/src/rhino/astbuilder'))();
this._visitor = new (require('jsdoc/src/visitor'))(this);
this._walker = new (require('jsdoc/src/walker')).Walker();
// TODO: replace with a runtime-agnostic default builder
var runtime = require('jsdoc/util/runtime');
this._astBuilder = builderInstance ||
new ( require(runtime.getModulePath('jsdoc/src/astbuilder')) )();
this._visitor = visitorInstance || new (require('jsdoc/src/visitor')).Visitor(this);
this._walker = walkerInstance || new (require('jsdoc/src/walker')).Walker();
Object.defineProperties(this, {
astBuilder: {
get: function() {
return this._astBuilder;
}
},
visitor: {
get: function() {
return this._visitor;
}
},
walker: {
get: function() {
return this._walker;
}
}
});
};
util.inherits(Parser, require('events').EventEmitter);
@ -42,12 +62,6 @@ Parser.prototype.clear = function() {
meta: {}
}
};
this._visitor = null;
};
// TODO: docs
Parser.prototype.getVisitor = function() {
return this._visitor;
};
// TODO: docs
@ -134,9 +148,6 @@ Parser.prototype.fireProcessingComplete = function(doclets) {
};
// TODO: docs
/**
* @returns {Array<Doclet>} The accumulated results of any calls to parse.
*/
Parser.prototype.results = function() {
return this._resultBuffer;
};
@ -149,20 +160,14 @@ Parser.prototype.addResult = function(o) {
this._resultBuffer.push(o);
};
// TODO: update docs
/**
* Adds a node visitor to use in parsing
*/
Parser.prototype.addNodeVisitor = function(visitor) {
this._visitor._addRhinoNodeVisitor(visitor);
// TODO: docs
Parser.prototype.addAstNodeVisitor = function(visitor) {
this._visitor.addAstNodeVisitor(visitor);
};
// TODO: docs
/**
* Get the node visitors used in parsing
*/
Parser.prototype.getVisitors = function() {
return this._visitor._getRhinoNodeVisitors();
Parser.prototype.getAstNodeVisitors = function() {
return this._visitor.getAstNodeVisitors();
};
// TODO: docs
@ -424,7 +429,6 @@ Parser.prototype.getBasename = function(name) {
if (name !== undefined) {
return name.replace(/^([$a-z_][$a-z_0-9]*).*?$/i, '$1');
}
return name;
};
// TODO: docs
@ -433,7 +437,6 @@ function definedInScope(doclet, basename) {
hasOwnProp.call(doclet.meta.vars, basename);
}
// TODO: docs
/**
* Given a node, determine what the node is a member of.

46
lib/jsdoc/src/visitor.js
View File

@ -68,13 +68,11 @@ function JsdocCommentFound(comment, filename) {
// TODO: docs
var Visitor = module.exports = function(parser) {
var Visitor = exports.Visitor = function(parser) {
this._parser = parser;
// Mozilla Parser API node visitors added by plugins
this._nodeVisitors = [];
// Rhino node visitors added by plugins (deprecated in JSDoc 3.3)
this._rhinoNodeVisitors = [];
// built-in visitors
this._visitors = [
this.visitNodeComments,
@ -83,12 +81,12 @@ var Visitor = module.exports = function(parser) {
};
// TODO: docs
Visitor.prototype.addNodeVisitor = function(visitor) {
Visitor.prototype.addAstNodeVisitor = function(visitor) {
this._nodeVisitors.push(visitor);
};
// TODO: docs
Visitor.prototype.removeNodeVisitor = function(visitor) {
Visitor.prototype.removeAstNodeVisitor = function(visitor) {
var idx = this._nodeVisitors.indexOf(visitor);
if (idx !== -1) {
this._nodeVisitors.splice(idx, 1);
@ -96,20 +94,10 @@ Visitor.prototype.removeNodeVisitor = function(visitor) {
};
// TODO: docs
Visitor.prototype.getNodeVisitors = function() {
Visitor.prototype.getAstNodeVisitors = function() {
return this._nodeVisitors;
};
// TODO: docs (deprecated)
Visitor.prototype._addRhinoNodeVisitor = function(visitor) {
this._rhinoNodeVisitors.push(visitor);
};
// TODO: docs (deprecated)
Visitor.prototype._getRhinoNodeVisitors = function() {
return this._rhinoNodeVisitors;
};
// TODO: docs; visitor signature is (node, parser, filename)
Visitor.prototype.visit = function(node, filename) {
var i;
@ -203,18 +191,10 @@ Visitor.prototype.visitNodeComments = function(node, parser, filename) {
// TODO: docs
Visitor.prototype.visitNode = function(node, parser, filename) {
var e = this.makeSymbolFoundEvent(node, parser, filename);
var i;
var l;
function callNodeVisitors(visitors, nodeToVisit) {
if (visitors) {
for (var i = 0, l = visitors.length; i < l; i++) {
visitors[i].visitNode(nodeToVisit, e, parser, filename);
if (e.stopPropagation) {
break;
}
}
}
}
var e = this.makeSymbolFoundEvent(node, parser, filename);
if (!node.nodeId) {
Object.defineProperty(node, 'nodeId', {
@ -222,9 +202,13 @@ Visitor.prototype.visitNode = function(node, parser, filename) {
});
}
callNodeVisitors(this._nodeVisitors, node);
if (e.code && e.code.node) {
callNodeVisitors(this._rhinoNodeVisitors, e.code.node); // TODO: check this!!
if (this._nodeVisitors && this._nodeVisitors.length) {
for (i = 0, l = this._nodeVisitors.length; i < l; i++) {
this._nodeVisitors[i].visitNode(node, e, parser, filename);
if (e.stopPropagation) {
break;
}
}
}
if (!e.preventDefault && e.comment && isValidJsdoc(e.comment)) {
@ -234,7 +218,7 @@ Visitor.prototype.visitNode = function(node, parser, filename) {
// add the node to the parser's lookup table
parser.addDocletRef(e);
for (var i = 0, l = e.finishers.length; i < l; i++) {
for (i = 0, l = e.finishers.length; i < l; i++) {
e.finishers[i].call(parser, e);
}

4
lib/jsdoc/util/include.js
View File

@ -1,5 +1,5 @@
var path = require('path');
var vm = require('jsdoc/util/vm');
var runtime = require('jsdoc/util/runtime');
/**
* Read and execute a JavaScript file in global scope.
@ -11,7 +11,7 @@ module.exports = function(filepath) {
filepath = path.resolve(__dirname, filepath);
try {
vm.getModule('jsdoc/util/include')(filepath);
require( runtime.getModulePath('jsdoc/util/include') )(filepath);
}
catch (e) {
console.log('Cannot include ' + filepath + ': ' + e);

58
lib/jsdoc/util/vm.js → lib/jsdoc/util/runtime.js
View File

@ -1,16 +1,18 @@
/*global Packages: true */
/**
* Helper functions to enable JSDoc to run on multiple JavaScript virtual machines.
* @module jsdoc/util/vm
* Helper functions to enable JSDoc to run on multiple JavaScript runtimes.
*
* @module jsdoc/util/runtime
* @private
*/
var os = require('os');
// These strings represent directory names; do not modify them!
/** @private */
const RHINO = exports.RHINO = 'rhino';
var RHINO = exports.RHINO = 'rhino';
/** @private */
const NODEJS = exports.NODEJS = 'nodejs';
var NODE = exports.NODE = 'node';
// hacky conversion from Windows path to URI
function pathToUri(filepath) {
@ -33,51 +35,63 @@ function pathToUri(filepath) {
}
/**
* The JavaScript VM that is executing JSDoc:
* The JavaScript runtime that is executing JSDoc:
*
* + `module:jsdoc/util/vm.RHINO`: Mozilla Rhino.
* + `module:jsdoc/util/vm.NODEJS`: Node.js (not currently supported).
* + `module:jsdoc/util/runtime~RHINO`: Mozilla Rhino.
* + `module:jsdoc/util/runtime~NODE`: Node.js (not currently supported).
*
* @private
*/
var vm = exports.vm = (function() {
var runtime = (function() {
if (Packages && typeof Packages === 'object' &&
Object.prototype.toString.call(Packages) === '[object JavaPackage]') {
return RHINO;
} else if ( require && require.main && module && (require.main === module) ) {
return NODEJS;
return NODE;
} else {
// unknown VM
throw new Error('Unable to identify the current JavaScript VM.');
// unknown runtime
throw new Error('Unable to identify the current JavaScript runtime.');
}
})();
/**
* Load the VM-specific implementation of a module.
* Get the require path for the runtime-specific implementation of a module.
*
* @param {string} modulePath - The relative path to the module. Use the same format as when calling
* @param {string} partialPath - The partial path to the module. Use the same format as when calling
* `require()`.
* @return {object} An object containing VM-specific functions for the requested module.
* @return {object} The require path for the runtime-specific implementation of the module.
*/
exports.getModule = function(modulePath) {
modulePath = [__dirname, vm, modulePath].join('/').replace(/ /g, '%20');
exports.getModulePath = function(partialPath) {
var modulePath = [__dirname, runtime, partialPath].join('/').replace(/ /g, '%20');
if (os.platform() === 'win32') {
modulePath = pathToUri(modulePath);
}
return require(modulePath);
return modulePath;
};
/**
* Retrieve the identifier for the current JavaScript runtime.
*
* @private
* @return {string} The runtime identifier.
*/
exports.getRuntime = function() {
return runtime;
};
/**
* Check whether Mozilla Rhino is running JSDoc.
* @return {boolean} Set to `true` if the current VM is Mozilla Rhino.
* @return {boolean} Set to `true` if the current runtime is Mozilla Rhino.
*/
exports.isRhino = function() {
return vm === RHINO;
return runtime === RHINO;
};
/**
* Check whether Node.js is running JSDoc. (Node.js is not currently supported.)
* @return {boolean} Set to `true` if the current VM is Node.js.
* @return {boolean} Set to `true` if the current runtime is Node.js.
*/
exports.isNodejs = function() {
return vm === NODEJS;
exports.isNode = function() {
return runtime === NODE;
};

11
nodejs/bin/jsdoc → node/bin/jsdoc
View File

@ -7,19 +7,12 @@
var fs = require('fs');
var os = require('os');
var path = require('path');
var spawnProc = require('child_process').spawn;
var args = process.argv.slice(2);
var script = path.normalize( path.join( path.dirname(fs.realpathSync(process.argv[1])), '..', '..',
'jsdoc' ) );
var jsdoc;
if (process.platform === 'win32') {
jsdoc = spawnProc(script + '.cmd', args, {stdio: 'inherit'});
}
else {
jsdoc = spawnProc(script, args, {stdio: 'inherit'});
}
var command = process.platform === 'win32' ? script + '.cmd' : script;
var jsdoc = require('child_process').spawn(command, args, {stdio: 'inherit'});
jsdoc.on('close', function(code) {
process.exit(code);

0
nodejs/jsdoc/fs.js → node/jsdoc/fs.js
View File

1
node/jsdoc/src/parser.js Normal file
View File

@ -0,0 +1 @@
module.exports = require('jsdoc/src/parser');

0
nodejs/jsdoc/util/include.js → node/jsdoc/util/include.js
View File

4
package.json
View File

@ -1,7 +1,7 @@
{
"name": "jsdoc",
"version": "3.2.0-dev",
"revision": "1366409063892",
"revision": "1373039791834",
"description": "An API documentation generator for JavaScript.",
"keywords": [ "documentation", "javascript" ],
"licenses": [
@ -28,7 +28,7 @@
"underscore": "1.4.2",
"wrench": "1.3.9"
},
"bin": "./nodejs/bin/jsdoc",
"bin": "./node/bin/jsdoc",
"bugs": "https://github.com/jsdoc3/jsdoc/issues",
"author": {
"name": "Michael Mathews",

BIN
rhino/js.jar
View File

Binary file not shown.

6
lib/jsdoc/src/rhino/astbuilder.js → rhino/jsdoc/src/astbuilder.js
View File

@ -1,7 +1,7 @@
/*global Packages: true */
/**
* Creates an Esprima-compatible AST using Rhino's JavaScript parser.
* @module jsdoc/src/rhino/astbuilder
* @module rhino/jsdoc/src/astbuilder
*/
var AstBuilder = module.exports = function() {
@ -11,3 +11,7 @@ var AstBuilder = module.exports = function() {
AstBuilder.prototype.build = function(sourceCode, sourceName) {
return this._builder.build(sourceCode, sourceName);
};
AstBuilder.prototype.getRhinoNodes = function() {
return this._builder.getRhinoNodes();
};

34
rhino/jsdoc/src/parser.js Normal file
View File

@ -0,0 +1,34 @@
// TODO: module docs
// TODO: docs
var Parser = exports.Parser = function() {
var astBuilder;
var visitor;
var runtime = require('jsdoc/util/runtime');
if ( !runtime.isRhino() ) {
throw new Error('You must run JSDoc on Mozilla Rhino to use the Rhino parser.');
}
astBuilder = new ( require(runtime.getModulePath('jsdoc/src/astbuilder')) )();
visitor = new ( require(runtime.getModulePath('jsdoc/src/visitor')) ).Visitor(this);
Parser.super_.call(this, astBuilder, visitor);
};
require('util').inherits(Parser, require('jsdoc/src/parser').Parser);
// TODO: update docs
/**
* Adds a node visitor to use in parsing
*/
Parser.prototype.addNodeVisitor = function(visitor) {
this._visitor.addRhinoNodeVisitor(visitor);
};
// TODO: docs
/**
* Get the node visitors used in parsing
*/
Parser.prototype.getNodeVisitors = function() {
return this._visitor.getRhinoNodeVisitors();
};

56
rhino/jsdoc/src/visitor.js Normal file
View File

@ -0,0 +1,56 @@
// TODO: module docs
// TODO: docs
var Visitor = exports.Visitor = function(parser) {
var runtime = require('jsdoc/util/runtime');
if ( !runtime.isRhino() ) {
throw new Error('You must run JSDoc on Mozilla Rhino to use the Rhino node visitor.');
}
Visitor.super_.call(this, parser);
// Rhino node visitors added by plugins (deprecated in JSDoc 3.3)
this._rhinoNodeVisitors = [];
// Rhino nodes retrieved from the org.jsdoc.AstBuilder instance
this._rhinoNodes = null;
this.addAstNodeVisitor({
visitNode: this._visitRhinoNode.bind(this)
});
};
require('util').inherits(Visitor, require('jsdoc/src/visitor').Visitor);
// TODO: docs (deprecated)
Visitor.prototype.addRhinoNodeVisitor = function(visitor) {
this._rhinoNodeVisitors.push(visitor);
};
// TODO: docs (deprecated)
Visitor.prototype.getRhinoNodeVisitors = function() {
return this._rhinoNodeVisitors;
};
// TODO: docs (deprecated)
Visitor.prototype._visitRhinoNode = function(astNode, e, parser, filename) {
var rhinoNode;
var visitors = this._rhinoNodeVisitors;
// if there are no visitors, bail out before we retrieve all the nodes
if (!visitors.length) {
return;
}
if (!this._rhinoNodes) {
this._rhinoNodes = parser.astBuilder.getRhinoNodes();
}
rhinoNode = this._rhinoNodes ? this._rhinoNodes.get(astNode.nodeId) : null;
if (rhinoNode) {
for (var i = 0, l = visitors.length; i < l; i++) {
visitors[i].visitNode(rhinoNode, e, parser, filename);
if (e.stopPropagation) {
break;
}
}
}
};

10
test/jasmine-jsdoc.js
View File

@ -110,10 +110,12 @@ jasmine.asyncSpecDone = function() {
};
jasmine.getDocSetFromFile = function(filename, parser) {
var sourceCode = fs.readFileSync(__dirname + '/' + filename, 'utf8'),
testParser = parser || new (require('jsdoc/src/parser')).Parser(),
indexAll = require('jsdoc/borrow').indexAll,
doclets;
var sourceCode = fs.readFileSync(__dirname + '/' + filename, 'utf8');
var runtime = require('jsdoc/util/runtime');
var testParser = parser ||
new ( require(runtime.getModulePath('jsdoc/src/parser')) ).Parser();
var indexAll = require('jsdoc/borrow').indexAll;
var doclets;
require('jsdoc/src/handlers').attachTo(testParser);

6
test/specs/documentation/modules.js
View File

@ -1,7 +1,9 @@
/*global beforeEach: true, describe: true, env: true, expect: true, it: true */
describe("module names", function() {
var parser = require('jsdoc/src/parser'),
srcParser = null, doclets;
var runtime = require('jsdoc/util/runtime');
var parser = require( runtime.getModulePath('jsdoc/src/parser') );
var srcParser = null;
var doclets;
beforeEach(function() {
env.opts._ = [__dirname + '/test/fixtures/modules/'];

9
test/specs/jsdoc/src/handlers.js
View File

@ -1,8 +1,9 @@
/*global describe: true, expect: true, it: true */
describe("jsdoc/src/handlers", function() {
var jsdoc = {src: { parser: require('jsdoc/src/parser')}},
testParser = new jsdoc.src.parser.Parser(),
handlers = require('jsdoc/src/handlers');
var runtime = require('jsdoc/util/runtime');
var parser = require( runtime.getModulePath('jsdoc/src/parser') );
var testParser = new parser.Parser();
var handlers = require('jsdoc/src/handlers');
handlers.attachTo(testParser);
@ -52,4 +53,4 @@ describe("jsdoc/src/handlers", function() {
describe("symbolFound handler", function() {
//TODO
});
});
});

208
test/specs/jsdoc/src/parser.js
View File

@ -1,15 +1,16 @@
/*global beforeEach: true, describe: true, expect: true, it: true, jasmine: true, xdescribe: true, xit: true */
/*global beforeEach: true, describe: true, expect: true, it: true, jasmine: true, spyOn: true,
xit: true */
describe("jsdoc/src/parser", function() {
var jsdoc = {src: { parser: require('jsdoc/src/parser')}};
var jsdoc = { src: { parser: require('jsdoc/src/parser') } };
it("should exist", function() {
expect(jsdoc.src.parser).toBeDefined();
expect(typeof jsdoc.src.parser).toEqual("object");
expect(typeof jsdoc.src.parser).toBe('object');
});
it("should export a 'Parser' constructor", function() {
expect(jsdoc.src.parser.Parser).toBeDefined();
expect(typeof jsdoc.src.parser.Parser).toEqual("function");
expect(typeof jsdoc.src.parser.Parser).toBe('function');
});
describe("Parser", function() {
@ -19,14 +20,69 @@ describe("jsdoc/src/parser", function() {
parser = new jsdoc.src.parser.Parser();
}
it("should have a 'parse' function", function() {
expect(jsdoc.src.parser.Parser.prototype.parse).toBeDefined();
expect(typeof jsdoc.src.parser.Parser.prototype.parse).toEqual("function");
newParser();
it('should have an "astBuilder" property', function() {
expect(parser.astBuilder).toBeDefined();
});
it("should have a 'results' function", function() {
expect(jsdoc.src.parser.Parser.prototype.results).toBeDefined();
expect(typeof jsdoc.src.parser.Parser.prototype.results).toEqual("function");
it('should have a "visitor" property', function() {
expect(parser.visitor).toBeDefined();
});
it('should have a "walker" property', function() {
expect(parser.walker).toBeDefined();
});
it('should accept an astBuilder, visitor, and walker as arguments', function() {
var astBuilder = {};
var visitor = {};
var walker = {};
var myParser = new jsdoc.src.parser.Parser(astBuilder, visitor, walker);
expect(myParser.astBuilder).toBe(astBuilder);
expect(myParser.visitor).toBe(visitor);
expect(myParser.walker).toBe(walker);
});
it('should have a "parse" method', function() {
expect(parser.parse).toBeDefined();
expect(typeof parser.parse).toBe('function');
});
it('should have a "results" method', function() {
expect(parser.results).toBeDefined();
expect(typeof parser.results).toBe('function');
});
it('should have an "addAstNodeVisitor" method', function() {
expect(parser.addAstNodeVisitor).toBeDefined();
expect(typeof parser.addAstNodeVisitor).toBe('function');
});
it('should have a "getAstNodeVisitors" method', function() {
expect(parser.getAstNodeVisitors).toBeDefined();
expect(typeof parser.getAstNodeVisitors).toBe('function');
});
describe('astBuilder', function() {
// TODO: enable
xit('should contain an appropriate astBuilder by default', function() {
expect( parser.astBuilder instanceof (require('jsdoc/src/astbuilder')) ).toBe(true);
});
});
describe('visitor', function() {
it('should contain an appropriate visitor by default', function() {
expect( parser.visitor instanceof (require('jsdoc/src/visitor')).Visitor ).toBe(true);
});
});
describe('walker', function() {
it('should contain an appropriate walker by default', function() {
expect( parser.walker instanceof (require('jsdoc/src/walker')).Walker ).toBe(true);
});
});
describe("parse", function() {
@ -70,6 +126,70 @@ describe("jsdoc/src/parser", function() {
expect(spy).toHaveBeenCalled();
});
it('should call AST node visitors', function() {
var Syntax = require('jsdoc/src/syntax').Syntax;
var args;
var sourceCode = ['javascript:/** foo */var foo;'];
var visitor = {
visitNode: function(node, e, parser, sourceName) {
if (e && e.code && !args) {
args = Array.prototype.slice.call(arguments);
}
}
};
require('jsdoc/src/handlers').attachTo(parser);
parser.addAstNodeVisitor(visitor);
parser.parse(sourceCode);
expect(args).toBeDefined();
expect( Array.isArray(args) ).toBe(true);
expect(args.length).toBe(4);
// args[0]: AST node
expect(args[0].type).toBeDefined();
expect(args[0].type).toBe(Syntax.VariableDeclarator);
// args[1]: JSDoc event
expect(typeof args[1]).toBe('object');
expect(args[1].code).toBeDefined();
expect(args[1].code.name).toBeDefined();
expect(args[1].code.name).toBe('foo');
// args[2]: parser
expect(typeof args[2]).toBe('object');
expect(args[2] instanceof jsdoc.src.parser.Parser).toBe(true);
// args[3]: current source name
expect( String(args[3]) ).toBe('[[string0]]');
});
it('should reflect changes made by AST node visitors', function() {
var doclet;
var sourceCode = ['javascript:/** foo */var foo;'];
var visitor = {
visitNode: function(node, e, parser, sourceName) {
if (e && e.code && e.code.name === 'foo') {
e.code.name = 'bar';
}
}
};
require('jsdoc/src/handlers').attachTo(parser);
parser.addAstNodeVisitor(visitor);
parser.parse(sourceCode);
doclet = parser.results()[0];
expect(doclet).toBeDefined();
expect(typeof doclet).toBe('object');
expect(doclet.name).toBeDefined();
expect(doclet.name).toBe('bar');
});
it("should fire 'parseComplete' events after it finishes parsing files", function() {
var spy = jasmine.createSpy(),
sourceCode = ['javascript:var bar = false;'];
@ -101,15 +221,31 @@ describe("jsdoc/src/parser", function() {
});
});
describe("results", function() {
describe('results', function() {
beforeEach(newParser);
xit("contains an empty array before files are parsed", function() {
// TODO
it('returns an empty array before files are parsed', function() {
var results = parser.results();
expect(results).toBeDefined();
expect( Array.isArray(results) ).toBe(true);
expect(results.length).toBe(0);
});
xit("contains an array of doclets after files are parsed", function() {
it('returns an array of doclets after files are parsed', function() {
var source = 'javascript:var foo;';
var results;
require('jsdoc/src/handlers').attachTo(parser);
parser.parse(source);
results = parser.results();
expect(results).toBeDefined();
expect(results[0]).toBeDefined();
expect(typeof results[0]).toBe('object');
expect(results[0].name).toBeDefined();
expect(results[0].name).toBe('foo');
});
it("should reflect comment changes made by 'jsdocCommentFound' handlers", function() {
@ -129,5 +265,47 @@ describe("jsdoc/src/parser", function() {
});
});
});
describe('addAstNodeVisitor', function() {
function visitorA() {}
function visitorB() {}
var visitors;
beforeEach(newParser);
it('should work with a single node visitor', function() {
parser.addAstNodeVisitor(visitorA);
visitors = parser.getAstNodeVisitors();
expect(visitors.length).toBe(1);
expect(visitors[0]).toBe(visitorA);
});
it('should work with multiple node visitors', function() {
parser.addAstNodeVisitor(visitorA);
parser.addAstNodeVisitor(visitorB);
visitors = parser.getAstNodeVisitors();
expect(visitors.length).toBe(2);
expect(visitors[0]).toBe(visitorA);
expect(visitors[1]).toBe(visitorB);
});
});
describe('getAstNodeVisitors', function() {
beforeEach(newParser);
it('should return an empty array by default', function() {
var visitors = parser.getAstNodeVisitors();
expect( Array.isArray(visitors) ).toBe(true);
expect(visitors.length).toBe(0);
});
// other functionality is covered by the addNodeVisitors tests
});
});
});
});

62
test/specs/jsdoc/util/runtime.js Normal file
View File

@ -0,0 +1,62 @@
/*global describe: true, expect: true, it: true, xit: true */
describe("jsdoc/util/runtime", function() {
var runtime = require('jsdoc/util/runtime');
var isRhino;
var isNode;
it("should exist", function() {
expect(runtime).toBeDefined();
expect(typeof runtime).toEqual('object');
});
it("should export a 'RHINO' constant", function() {
expect(runtime.RHINO).toBeDefined();
expect(typeof runtime.RHINO).toEqual('string');
});
it("should export a 'NODE' constant", function() {
expect(runtime.NODE).toBeDefined();
expect(typeof runtime.NODE).toEqual('string');
});
it("should export an 'isRhino' function", function() {
expect(runtime.isRhino).toBeDefined();
expect(typeof runtime.isRhino).toEqual('function');
});
it("should export an 'isNode' function", function() {
expect(runtime.isNode).toBeDefined();
expect(typeof runtime.isNode).toEqual('function');
});
describe("isRhino", function() {
isRhino = runtime.isRhino();
it("should return a boolean", function() {
expect(typeof isRhino).toEqual('boolean');
});
it("should return the opposite value from isNode()", function() {
if (isNode === undefined) {
isNode = runtime.isNode();
}
expect(!isRhino).toBe(isNode);
});
});
describe("isNode", function() {
isNode = runtime.isNode();
it("should return a boolean", function() {
expect(typeof isNode).toEqual('boolean');
});
it("should return the opposite value from isRhino()", function() {
if (isRhino === undefined) {
isRhino = runtime.isRhino();
}
expect(!isNode).toBe(isRhino);
});
});
});

66
test/specs/jsdoc/util/vm.js
View File

@ -1,66 +0,0 @@
/*global describe: true, expect: true, it: true, xit: true */
describe("jsdoc/util/vm", function() {
var vm = require('jsdoc/util/vm');
it("should exist", function() {
expect(vm).toBeDefined();
expect(typeof vm).toEqual('object');
});
it("should export a 'RHINO' constant", function() {
expect(vm.RHINO).toBeDefined();
expect(typeof vm.RHINO).toEqual('string');
});
it("should export a 'NODEJS' constant", function() {
expect(vm.NODEJS).toBeDefined();
expect(typeof vm.NODEJS).toEqual('string');
});
it("should export a 'vm' property", function() {
expect(vm.vm).toBeDefined();
expect(typeof vm.vm).toEqual('string');
});
it("should export an 'isRhino' function", function() {
expect(vm.isRhino).toBeDefined();
expect(typeof vm.isRhino).toEqual('function');
});
it("should export an 'isNodejs' function", function() {
expect(vm.isNodejs).toBeDefined();
expect(typeof vm.isNodejs).toEqual('function');
});
describe("vm", function() {
it("should match either 'vm.RHINO' or 'vm.NODEJS'", function() {
expect(vm.vm).toEqual(vm.RHINO || vm.NODEJS);
});
xit("should return the correct value for the current VM", function() {
// TODO: is there a reasonable test that doesn't just replicate getVm()?
});
});
describe("isRhino", function() {
it("should return a boolean", function() {
expect( typeof vm.isRhino() ).toEqual('boolean');
});
it("should reflect the value of 'vm.vm'", function() {
expect( vm.isRhino() ).toEqual(vm.vm === vm.RHINO ? true : false);
});
});
describe("isNodejs", function() {
it("should return a boolean", function() {
expect( typeof vm.isNodejs() ).toEqual('boolean');
});
it("should reflect the value of 'vm.vm'", function() {
expect( vm.isNodejs() ).toEqual(vm.vm === vm.NODEJS ? true : false);
});
});
});

154
test/specs/rhino/src/parser.js Normal file
View File

@ -0,0 +1,154 @@
/*global beforeEach: true, describe: true, expect: true, it: true, jasmine: true, spyOn: true */
describe('rhino/jsdoc/src/parser', function() {
var jsdoc = {
src: {
parser: (function() {
var runtime = require('jsdoc/util/runtime');
return require( runtime.getModulePath('jsdoc/src/parser') );
})()
}
};
it('should exist', function() {
expect(jsdoc.src.parser).toBeDefined();
expect(typeof jsdoc.src.parser).toBe('object');
});
it('should export a "Parser" constructor', function() {
expect(jsdoc.src.parser.Parser).toBeDefined();
expect(typeof jsdoc.src.parser.Parser).toBe('function');
});
describe('Parser', function() {
var parser;
function newParser() {
parser = new jsdoc.src.parser.Parser();
}
newParser();
it('should inherit from jsdoc/src/parser', function() {
var parent = require('jsdoc/src/parser').Parser;
expect(parser instanceof parent).toBe(true);
});
it('should have an "addNodeVisitor" method', function() {
expect(parser.addNodeVisitor).toBeDefined();
expect(typeof parser.addNodeVisitor).toBe('function');
});
it('should have a "getNodeVisitors" method', function() {
expect(parser.getNodeVisitors).toBeDefined();
expect(typeof parser.getNodeVisitors).toBe('function');
});
describe('addNodeVisitor', function() {
function visitorA() {}
function visitorB() {}
var visitors;
beforeEach(newParser);
it('should work with a single Rhino node visitor', function() {
parser.addNodeVisitor(visitorA);
visitors = parser.getNodeVisitors();
expect(visitors.length).toBe(1);
expect(visitors[0]).toBe(visitorA);
});
it('should work with multiple Rhino node visitors', function() {
parser.addNodeVisitor(visitorA);
parser.addNodeVisitor(visitorB);
visitors = parser.getNodeVisitors();
expect(visitors.length).toBe(2);
expect(visitors[0]).toBe(visitorA);
expect(visitors[1]).toBe(visitorB);
});
});
describe('getNodeVisitors', function() {
beforeEach(newParser);
it('should return an empty array by default', function() {
var visitors = parser.getNodeVisitors();
expect( Array.isArray(visitors) ).toBe(true);
expect(visitors.length).toBe(0);
});
// other functionality is covered by the addNodeVisitors tests
});
describe('parse', function() {
beforeEach(newParser);
var sourceCode = ['javascript:/** foo */var foo;'];
it('should call Rhino node visitors', function() {
var args;
var visitor = {
visitNode: function(rhinoNode, e, parser, sourceName) {
if (e && e.code && !args) {
args = Array.prototype.slice.call(arguments);
}
}
};
require('jsdoc/src/handlers').attachTo(parser);
parser.addNodeVisitor(visitor);
parser.parse(sourceCode);
expect(args).toBeDefined();
expect( Array.isArray(args) ).toBe(true);
expect(args.length).toBe(4);
// args[0]: Rhino node
expect(args[0].toSource).toBeDefined();
expect( String(args[0].toSource()) ).toBe('foo');
// args[1]: JSDoc event
expect(typeof args[1]).toBe('object');
expect(args[1].code).toBeDefined();
expect(args[1].code.name).toBeDefined();
expect( String(args[1].code.name) ).toBe('foo');
// args[2]: parser
expect(typeof args[2]).toBe('object');
expect(args[2] instanceof jsdoc.src.parser.Parser).toBe(true);
// args[3]: current source name
expect( String(args[3]) ).toBe('[[string0]]');
});
it('should reflect changes made by Rhino node visitors', function() {
var doclet;
var visitor = {
visitNode: function(rhinoNode, e, parser, sourceName) {
if (e && e.code && e.code.name === 'foo') {
e.code.name = 'bar';
}
}
};
require('jsdoc/src/handlers').attachTo(parser);
parser.addNodeVisitor(visitor);
parser.parse(sourceCode);
doclet = parser.results()[0];
expect(doclet).toBeDefined();
expect(typeof doclet).toBe('object');
expect(doclet.name).toBeDefined();
expect(doclet.name).toBe('bar');
});
});
});
});

88
test/specs/rhino/src/visitor.js Normal file
View File

@ -0,0 +1,88 @@
/*global beforeEach: true, describe: true, expect: true, it: true */
describe('rhino/jsdoc/src/visitor', function() {
var runtime = require('jsdoc/util/runtime');
var jsdoc = {
src: {
visitor: require( runtime.getModulePath('jsdoc/src/visitor') )
}
};
it('should exist', function() {
expect(jsdoc.src.visitor).toBeDefined();
expect(typeof jsdoc.src.visitor).toBe('object');
});
it('should export a "Visitor" constructor', function() {
expect(jsdoc.src.visitor.Visitor).toBeDefined();
expect(typeof jsdoc.src.visitor.Visitor).toBe('function');
});
describe('Visitor', function() {
var parser;
var visitor;
function newVisitor() {
parser = new ( require(runtime.getModulePath('jsdoc/src/parser')) ).Parser();
visitor = new jsdoc.src.visitor.Visitor(parser);
}
newVisitor();
it('should inherit from jsdoc/src/visitor', function() {
var parent = require('jsdoc/src/visitor').Visitor;
expect(visitor instanceof parent).toBe(true);
});
it('should have an "addRhinoNodeVisitor" method', function() {
expect(visitor.addRhinoNodeVisitor).toBeDefined();
expect(typeof visitor.addRhinoNodeVisitor).toBe('function');
});
it('should have a "getRhinoNodeVisitors" method', function() {
expect(visitor.getRhinoNodeVisitors).toBeDefined();
expect(typeof visitor.getRhinoNodeVisitors).toBe('function');
});
describe('addRhinoNodeVisitor', function() {
function visitorA() {}
function visitorB() {}
var visitors;
beforeEach(newVisitor);
it('should work with a single Rhino node visitor', function() {
visitor.addRhinoNodeVisitor(visitorA);
visitors = visitor.getRhinoNodeVisitors();
expect(visitors.length).toBe(1);
expect(visitors[0]).toBe(visitorA);
});
it('should work with multiple Rhino node visitors', function() {
visitor.addRhinoNodeVisitor(visitorA);
visitor.addRhinoNodeVisitor(visitorB);
visitors = visitor.getRhinoNodeVisitors();
expect(visitors.length).toBe(2);
expect(visitors[0]).toBe(visitorA);
expect(visitors[1]).toBe(visitorB);
});
});
describe('getRhinoNodeVisitors', function() {
beforeEach(newVisitor);
it('should return an empty array by default', function() {
var visitors = visitor.getRhinoNodeVisitors();
expect( Array.isArray(visitors) ).toBe(true);
expect(visitors.length).toBe(0);
});
// other functionality is covered by the addNodeVisitors tests
});
});
});

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

@ -1,9 +1,10 @@
/*global describe: true, env: true, expect: true, it: true */
describe("@overview tag", function() {
var parser = require('jsdoc/src/parser'),
srcParser = new parser.Parser(),
doclets;
var runtime = require('jsdoc/util/runtime');
var parser = require( runtime.getModulePath('jsdoc/src/parser') );
var srcParser = new parser.Parser();
var doclets;
require('jsdoc/src/handlers').attachTo(srcParser);
doclets = srcParser.parse(__dirname + '/test/fixtures/file.js');