Clarify the function call in "to throw" documentation.

[alexjeffburke]

This PR hopes to address the concerns in issue #411.

The changes make the wrapping function clear and also include examples using arrow function syntax.

[papandreou]

Yeah, that's another downside of supporting node 0.10 -- we can't use arrow functions in the documentation code snippets :)

[papandreou]

equivalent

[alexjeffburke]

@papandreou check. And re the arrow functions, honestly that's another vote to do as mocha do and go node 4+ in my book :)

[papandreou]

Or node 6+ while we're at it :)

[alexjeffburke]

Hmm yeah - I only assumed we’d stick with 4 to be in line with mocha.

[sunesimonsen]

@papandreou isn't the Node versions which we test and generate the documentation deciding if we can use arrow functions? I actually agree. Maybe we should just jump directly to Node v6+

[papandreou]

@sunesimonsen, not sure I fully understood that? The code snippets in the documentation are executed via mocha as part of make test It doesn't look like we attempt to limit the node versions where the
md files are also included in the test run. We could do that, of course.

[dasilvacontin]

I can see people thinking "why wrap the function pointlessly when I can just pass the function and boom will be called for me".

[dasilvacontin]

But yeah, that's for people who understand that you have to let the library call the function for you.

How passing functions work is something that is easy mislearned, from what I have seen helping people with JavaScript. Trying to pass callbacks while you are actually executing them in the spot and passing whatever they return, etc.

[alexjeffburke]

@dasilvacontin still very glad you reported it so we get a chance to hopefully improve things :)

[alexjeffburke]

Quick note, I've rebased this on top of v11 which has addressed the test failures due to the use of arrow functions :)

[papandreou]

🚀

[papandreou]

@alexjeffburke, is there anything holding this back, or should we get it into v11?

[alexjeffburke]

@papandreou nothing from my side so yeah let's fold this in :)

[papandreou]

I keep stumbling upon this one, let's just get it in :)

[alexjeffburke]

Yay!