add 'parseBegin' and 'parseComplete' events (#299)

lib/jsdoc/src/parser.js

@@ -50,10 +50,18 @@ exports.Parser.prototype.parse = function(sourceFiles, encoding) {
 
     var filename = '';
     var sourceCode = '';
+    var parsedFiles = [];
+    var e = {};
 
     if (typeof sourceFiles === 'string') { sourceFiles = [sourceFiles]; }
 
+    e.sourcefiles = sourceFiles;
+
+    this.emit('parseBegin', e);
+
     for (var i = 0, leni = sourceFiles.length; i < leni; i++) {
+        sourceCode = '';
+
         if (sourceFiles[i].indexOf(SCHEMA) === 0) {
             sourceCode = sourceFiles[i].substr(SCHEMA.length);
             filename = '[[string' + i + ']]';
@@ -69,9 +77,14 @@ exports.Parser.prototype.parse = function(sourceFiles, encoding) {
             }
         }
 
-        this._parseSourceCode(sourceCode, filename);
+        if (sourceCode.length) {
+            this._parseSourceCode(sourceCode, filename);
+            parsedFiles.push(filename);
+        }
     }
 
+    this.emit('parseComplete', {sourcefiles: parsedFiles});
+
     return this._resultBuffer;
 };
 

plugins/eventDumper.js

@@ -12,12 +12,14 @@ var conf = env.conf.eventDumper || {};
 
 // Dump the included parser events (defaults to all events)
 var events = conf.include || [
+    'parseBegin',
     'fileBegin',
     'beforeParse',
     'jsdocCommentFound',
     'symbolFound',
     'newDoclet',
-    'fileComplete'
+    'fileComplete',
+    'parseComplete'
 ];
 // Don't dump the excluded parser events
 if (conf.exclude) {

test/specs/jsdoc/src/parser.js

@@ -1,4 +1,4 @@
-/*global beforeEach: true, describe: true, expect: true, it: true, jasmine: true, xdescribe: true */
+/*global beforeEach: true, describe: true, expect: true, it: true, jasmine: true, xdescribe: true, xit: true */
 describe("jsdoc/src/parser", function() {
     var jsdoc = {src: { parser: require('jsdoc/src/parser')}};
 
@@ -32,9 +32,32 @@ describe("jsdoc/src/parser", function() {
         describe("parse", function() {
             beforeEach(newParser);
 
+            it("should fire 'parseBegin' events before it parses any files", function() {
+                var spy = jasmine.createSpy(),
+                    sourceFiles = ["javascript:/** @name foo */"];
+
+                parser.on("parseBegin", spy).parse(sourceFiles);
+                expect(spy).toHaveBeenCalled();
+                expect(spy.mostRecentCall.args[0].sourcefiles).toBe(sourceFiles);
+            });
+
+            it("should allow 'parseBegin' handlers to modify the list of source files", function() {
+                var sourceCode = "javascript:/** @name foo */",
+                    newFiles = ["[[replaced]]"],
+                    evt;
+
+                function handler(e) {
+                    e.sourcefiles = newFiles;
+                    evt = e;
+                }
+
+                parser.on('parseBegin', handler).parse(sourceCode);
+                expect(evt.sourcefiles).toBe(newFiles);
+            });
+
             it("should fire 'jsdocCommentFound' events when parsing source containing jsdoc comments", function() {
                 var spy = jasmine.createSpy(),
-                    sourceCode = 'javascript:/** @name bar */';
+                    sourceCode = ['javascript:/** @name bar */'];
                 parser.on('jsdocCommentFound', spy).parse(sourceCode);
                 expect(spy).toHaveBeenCalled();
                 expect(spy.mostRecentCall.args[0].comment).toEqual("/** @name bar */");
@@ -46,6 +69,14 @@ describe("jsdoc/src/parser", function() {
                 parser.on('symbolFound', spy).parse(sourceCode);
                 expect(spy).toHaveBeenCalled();
             });
+
+            it("should fire 'parseComplete' events after it finishes parsing files", function() {
+                var spy = jasmine.createSpy(),
+                    sourceCode = ['javascript:var bar = false;'];
+                parser.on('parseComplete', spy).parse(sourceCode);
+                expect(spy).toHaveBeenCalled();
+                expect(spy.mostRecentCall.args[0].sourcefiles).toEqual(["[[string0]]"]);
+            });
             
             it("should be able to parse its own source file", function() {
                 var fs = require('jsdoc/fs'),
@@ -63,7 +94,13 @@ describe("jsdoc/src/parser", function() {
         describe("results", function() {
             beforeEach(newParser);
 
-            // TODO: more tests?
+            xit("contains an empty array before files are parsed", function() {
+                // TODO
+            });
+
+            xit("contains an array of doclets after files are parsed", function() {
+
+            });
 
             it("should reflect comment changes made by 'jsdocCommentFound' handlers", function() {
                 // we test both POSIX and Windows line endings