docs: rewrite .throw jsdoc
#866
Conversation
| * instance. | ||
| * | ||
| * var err = new TypeError("Illegal salmon!"); | ||
| * var badFn = function () { throw err }; |
There was a problem hiding this comment.
Nitpick note: throw err <-- semicolon here
|
Fantastic job, @meeber. Very well written 👍 |
|
Thank you @meeber. This is really awesome work! Just for the sake of discussion, this made me realize that this assertion actually checks if anything is thrown not only errors. function stringThrower() {
throw 'this is a string';
}
expect(stringThrower).to.throw();IMHO this is an ok behavior and the docs can remain as it is. What do you think? |
| * asserting that the thrown error is an instance of the given error | ||
| * constructor, or that the thrown error is referentially equal to the given | ||
| * error instance, and/or that the thrown error's message contains a given | ||
| * string or matches a given regular expression. |
There was a problem hiding this comment.
This is quite a chunky sentence, I'd like to simplify this into a series of shorter statements, maybe even bullets? Maybe something like...
Invokes the target function, expecting it to throw an error. Passing in an Error constructor as the first argument will assert that the thrown error should match. Passing in an Error instance (
new Error('...')) will assert that both errors should be referentially equal (===). Passing a string will assert that the thrown error's message matches the given string. Passing a regular expression will assert that the thrown error's message matches the given regular expression.
Then again, maybe we could simplify this whole paragraph much more given the examples below:
Invokes the target function, expecting it to throw an error. Providing arguments can be used to add extra assertions about the thrown error. See below for examples:
| * expect(badFn).to.not.throw(ReferenceError); | ||
| * | ||
| * If the first argument is an error instance, `throw` invokes the function | ||
| * and asserts that an error is thrown that's referentially equal to that |
There was a problem hiding this comment.
We should say here:
referentially equal (
===)
| * | ||
| * expect(function () { cat.meow(); }).to.throw(); // Function expression | ||
| * expect(() => cat.meow()).to.throw(); // ES6 arrow function | ||
| * expect(cat.meow.bind(cat)).to.throw(); // Bind |
There was a problem hiding this comment.
This is all great. Very clear. Kudos.
|
Couple of requested changes @meeber - mostly around simplifying the wording, or making sure when we use terms like |
|
Awesome job! I totally agree with the changes @keithamus suggested, specially the first one. Shorter sentences could satisfy people's need to use this without having to read many details. Thanks @meeber! 😄 |
|
@keithamus @lucasfcosta Agreed on the first paragraph and the @vieiralucas Great point. Actually, I think it's worth mentioning how |
|
Awesome! LGTM |
|
LGTM, very much agreed on specifying handling non-errors. |
|
LGTM too! |
|
Let's merge this! |
Closes #864