Document the done() contract

[FagnerMartinsBrack]

When I call done() passing a non Error instance (let's say an error Object Literal, for instance) I get the following message:

done() invoked with non-Error: [Object object]

If the contract is that you should pass an Error instance to the async done handler, then that should be documented. I couldn't find that when looking at the site, only looking at the internals (which, as we all know, should not be relied upon).

If you pass a String (done("it should not do this")), according to the source, it is supposed to be casted accordingly, but then the result will be something like:

done() invoked with non-Error: it should not do this

That is interpreted as a mistake, but then the docs should reflect what should be done to prevent that mistake.

Below is the relevant piece of code from source (2.4.5):

function callFnAsync(fn) {
  fn.call(ctx, function(err) {
    if (err instanceof Error || toString.call(err) === '[object Error]') {
      return done(err);
    }
    if (err) {
      if (Object.prototype.toString.call(err) === '[object Object]') {
        return done(new Error('done() invoked with non-Error: '
          + JSON.stringify(err)));
      }
     return done(new Error('done() invoked with non-Error: ' + err));
    }
    done();
  });
}

TL DR;

Document that done accepts either undefined or an Error object to reflect the current undocumented behavior.

[boneskull]

This issue was moved to mochajs/mocha#3134