Add rudimentary support for async tests

This is very hacky, but closes #8. Version 1.3 is getting published
ASAP, because I like breaking things.

Author: yamadapc

examples/async-failing.js

@@ -0,0 +1,9 @@
+/**
+ * @example
+ *    takesCallback('something', cb)
+ *    // async => 'something - here'
+ */
+
+function takesCallback(something, cb) {
+  cb(new Error('bad things happen'));
+}

examples/async.js

@@ -0,0 +1,9 @@
+/**
+ * @example
+ *    takesCallback('something', cb)
+ *    // async => 'something - here'
+ */
+
+function takesCallback(something, cb) {
+  cb(null, something + ' - here');
+}

lib/comment-parser.js

@@ -92,9 +92,13 @@ exports.parseExamples = function commentParser$parseExamples(parsedComments) {
     if(parsedComments[i].type === 'code') {
       if(currentExample.testCase) flush();
       currentExample.testCase = parsedComments[i].string;
-    } else if(parsedComments[i].type === 'comment' && currentExample.testCase &&
-              parsedComments[i].string.indexOf('=>') === 0) {
-      currentExample.expectedResult += parsedComments[i].string.slice(3);
+    } else if(parsedComments[i].type === 'comment' && currentExample.testCase) {
+      if(parsedComments[i].string.indexOf('=>') === 0) {
+        currentExample.expectedResult += parsedComments[i].string.slice(3);
+      } else if(parsedComments[i].string.indexOf('async =>') === 0) {
+        currentExample.expectedResult += parsedComments[i].string.slice(9);
+        currentExample.isAsync = true;
+      }
     }
   }
 
@@ -106,6 +110,7 @@ exports.parseExamples = function commentParser$parseExamples(parsedComments) {
     if(currentExample.expectedResult) {
       examples.push(currentExample);
     }
+
     currentExample = { expectedResult: '', };
   }
 };

lib/get-example-code.js

@@ -0,0 +1,41 @@
+'use strict';
+
+module.exports = exports = getExampleCode;
+
+/**
+ * Compiles down an `example`. Async examples call an imaginary `done` function
+ * once they're done.
+ *
+ * @param {Object} comment
+ * @param {String} comment.testCase
+ * @param {String} comment.expectedResult
+ * @param {Boolean} comment.isAsync
+ * @return {String}
+ */
+
+function getExampleCode(comment) {
+  var expectedResult = comment.expectedResult;
+  var isAsync = comment.isAsync;
+  var testCase = comment.testCase.replace();
+
+  if(isAsync) {
+    return '\nfunction cb(err, result) {' +
+      'if(err) return done(err);' +
+      'result.should.eql(' + expectedResult + ');' +
+      'done();' +
+    '}\n' +
+    testCase;
+  } else {
+    return '(' + testCase + ').should.eql(' + expectedResult + ');';
+  }
+}
+
+/**
+ * Escapes a string for meta-quoting
+ */
+
+function escapeString(str) {
+  return str.replace(/\'/g, '\\\'');
+}
+
+exports.escapeString = escapeString;

lib/index.js

@@ -4,8 +4,11 @@ var path = require('path');
 var dox = require('dox');
 var _ = require('lodash');
 var commentParser = require('./comment-parser');
+var getExampleCode = require('./get-example-code');
 var util = require('./util');
 
+var escapeString = getExampleCode.escapeString;
+
 var JSDOCTEST_DISABLE = process.env.JSDOCTEST_DISABLE || false;
 
 /**
@@ -91,10 +94,10 @@ exports.runRegistered = function() {
 exports.toJsdocRegister = function jsdoctest$toJsdocRegister(comment) {
   var baseId = comment.ctx.name + ' - ';
   var compiled = _.map(comment.examples, function(example) {
-    var id = baseId + example.testCase + ' => ' + example.expectedResult;
-    var fn = 'function() {' +
-      '(' + example.testCase + ').should.equal(' + example.expectedResult + ');' +
-    '}';
+    var id = escapeString(baseId) +
+             escapeString(example.testCase) + ' => ' +
+             escapeString(example.expectedResult);
+    var fn = 'function() {' + example.testCode + '}';
     return '__registerTest(\'' + id + '\', ' + fn + ');';
   }).join('');
 

lib/mocha.js

@@ -3,8 +3,11 @@ var fs = require('fs');
 var path = require('path');
 var _ = require('lodash');
 var jsdoctest = require('./index');
+var getExampleCode = require('./get-example-code');
 var util = require('./util');
 
+var escapeString = getExampleCode.escapeString;
+
 /**
  * Mocks `mocha`'s register environment for doctest mocha integration. This
  * works in the same manner `coffee-script/register` or `mocha --require
@@ -31,7 +34,7 @@ function contentsToMochaSpec(rootDir, filename, content) {
   var comments = jsdoctest.getJsdoctests(content);
   var moduleName = exports._getModuleName(rootDir, filename);
 
-  return '\ndescribe(\'' + moduleName + '\', function() {' +
+  return '\ndescribe(\'' + escapeString(moduleName) + '\', function() {' +
              _.map(_.compact(comments), function(comment) {
                return exports.commentToMochaSpec(comment);
              }).join('') +
@@ -45,14 +48,14 @@ function contentsToMochaSpec(rootDir, filename, content) {
 
 exports.commentToMochaSpec = function commentToMochaSpec(comment) {
   var ctx = comment.ctx || {};
-  return '\ndescribe(\'' + ctx.string + '\', function() {' +
-         _.map(comment.examples, function(example) {
-           return 'it(\'' + example.testCase + '\', function() {' +
-                     '(' + example.testCase + ')' +
-                       '.should.eql(' + example.expectedResult + ');' +
-                  '});';
-         }).join('\n') +
-         '});';
+  return '\ndescribe(\'' + escapeString(ctx.string) + '\', function() {' +
+     _.map(comment.examples, function(example) {
+       return 'it(\'' + escapeString(example.testCase) +
+              '\', function(' + (example.isAsync ? 'done' : '') + ') {' +
+              getExampleCode(example) +
+              '});';
+     }).join('\n') +
+     '});';
 };
 
 var originalLoad;