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 meeber commented Nov 15, 2016

Closes #864

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

@shvaikalesh shvaikalesh Nov 15, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpick note: throw err <-- semicolon here

@shvaikalesh
Copy link
Contributor

shvaikalesh commented Nov 15, 2016

Fantastic job, @meeber. Very well written 👍

@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.
Copy link
Member

@keithamus keithamus Nov 15, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Copy link
Member

@lucasfcosta lucasfcosta Nov 15, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

* 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
Copy link
Member

@keithamus keithamus Nov 15, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member

@keithamus keithamus Nov 15, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
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
@meeber meeber deleted the throw-doc branch Aug 6, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants