.rejects doesn't match documentation

[Morgan Roderick]

The documentation for stub.rejects specifies

stub.rejects("TypeError");
Causes the stub to return a Promise which rejects with an exception of the provided type.

However, that is incorrect.

The returned value from that example, will give you an Error object, with the name property set to the value of the first argument.

However, the desired behaviour (according to the documentation) should be more like this:

// create a stub that rejects with an `Error` with a blank message
const stub1 = sinon.stub().rejects();
// create a stub that rejects with a user supplied reason
const reason = "The pie is a lie";
const stub2 = sinon.stub().rejects(reason);
// create a stub that rejects with exactly the error instance provided
const myError = new Error(reason);
const stub3 = sinon.stub().rejects(myError);

// example
const applePieError = new RangeError("The apple pie is a lie");
const stub4 = sinon.stub().rejects(applePieError);

try {
    await stub4();
} catch (error) {
    console.log(error === applePieError);
    // => true
}

[Carl-Erik Kopseng]

I actually do not know what is meant here. Is the implementation wrong or the documentation? What behavior should we aim for? What is chosen should at least be consistent, ref confusions in #1679 and alike.

[Morgan Roderick]

Closing this issue in favour of continuing discussion in #1679