Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: rewrite `.throw` jsdoc #866

Merged
merged 1 commit into from Nov 15, 2016
Merged

docs: rewrite `.throw` jsdoc #866

merged 1 commit into from Nov 15, 2016

Conversation

@meeber
Copy link
Contributor

meeber commented Nov 15, 2016

Closes #864

* instance.
*
* var err = new TypeError("Illegal salmon!");
* var badFn = function () { throw err };

This comment has been minimized.

Copy link
@shvaikalesh

shvaikalesh Nov 15, 2016

Contributor

Nitpick note: throw err <-- semicolon here

@shvaikalesh
Copy link
Contributor

shvaikalesh commented Nov 15, 2016

Fantastic job, @meeber. Very well written 👍

@meeber meeber force-pushed the meeber:throw-doc branch from 15499f3 to ef18420 Nov 15, 2016
@vieiralucas
Copy link
Member

vieiralucas commented Nov 15, 2016

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.

This comment has been minimized.

Copy link
@keithamus

keithamus Nov 15, 2016

Member

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:

This comment has been minimized.

Copy link
@lucasfcosta
* 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

This comment has been minimized.

Copy link
@keithamus

keithamus Nov 15, 2016

Member

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

This comment has been minimized.

Copy link
@keithamus

keithamus Nov 15, 2016

Member

This is all great. Very clear. Kudos.

@keithamus
Copy link
Member

keithamus commented Nov 15, 2016

Couple of requested changes @meeber - mostly around simplifying the wording, or making sure when we use terms like referentially equal we explain what that is. I want to be very very careful about our documentation - that it remains very approachable and we don't need users to learn new concepts or stumble over unknown words without reasonable redundancy in the explanation. Phrases like "referentially equal", while of course are common parlance for experienced devs, can quickly fall apart when explained to less experienced devs (even though they're aware of ===). Hopefully y'all agree 😄

@lucasfcosta
Copy link
Member

lucasfcosta commented Nov 15, 2016

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! 😄

@meeber meeber force-pushed the meeber:throw-doc branch from ef18420 to 1971561 Nov 15, 2016
@meeber
Copy link
Contributor Author

meeber commented Nov 15, 2016

@keithamus @lucasfcosta Agreed on the first paragraph and the ===. Fixed both.

@vieiralucas Great point. Actually, I think it's worth mentioning how throw handles non-Errors, while also noting that it's a bad practice. Therefore, I've added a new paragraph to the end. Thoughts?

@vieiralucas
Copy link
Member

vieiralucas commented Nov 15, 2016

Awesome! LGTM

@shvaikalesh
Copy link
Contributor

shvaikalesh commented Nov 15, 2016

LGTM, very much agreed on specifying handling non-errors.

@lucasfcosta
Copy link
Member

lucasfcosta commented Nov 15, 2016

LGTM too!
Awesome job.

@keithamus
Copy link
Member

keithamus commented Nov 15, 2016

Let's merge this!

@keithamus keithamus merged commit 0836c45 into chaijs:master Nov 15, 2016
2 checks passed
2 checks passed
approvals/lgtm this commit looks good
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@meeber meeber deleted the meeber:throw-doc branch Aug 6, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

5 participants
You can’t perform that action at this time.