docs(addAssertion): document alternations, flags and optional values

[joelmukuthu]

No description provided.

[sunesimonsen]

Thanks for improving this, I'll review this soon.

[sunesimonsen]

I just read through the updated documentation and I think it is a great improvement. So when we get the tests passing and @papandreou blessing then I think we should run with it.

[papandreou]

Great initiative, makes it much easier to understand! 🚀

[joelmukuthu]

Thank you for the review @papandreou and @sunesimonsen. This is ready for a second pass 👼

[alexjeffburke]

Fwiw I also think this is awesome, thanks for taking this on @joelmukuthu 🥇 Have left a small comment inline and will do another top-to-bottom read hopefully this eve.

[alexjeffburke]

I’ve now had the chance to read the text top to bottom - again, really cool taking on docs :) I’ve left a few specific comments inline, but I still think we need to address the “handler” thing.

My suggestion now is to avoid the use of the term handler. I think this could be achieved by saying early on that:

“The function we supply as the second argument to addAssertion is a handler that defines the body of the assertion..” and then later in the document refer to “assertion body”. That make use of terms we’ve generally used for this, but also avoids what to me is a very overloaded word in node.

Finally, I think somewhere we do need to mention that if a promise is returned inside the assertion body that unexpected will wait for it allowing support for asynchronous assertions.

[joelmukuthu]

Thanks for the review @alexjeffburke. I've replied to some of your comments seeking clarification.

Regarding async assertions, there's a section further down on the same page talking about it. My idea with this rewrite was to build up from a simple example and avoid swamping the reader with too much information in one go.

Regarding the word "handler", just to be sure, you'd like for me to use "assertion body" in its place instead?

[joelmukuthu]

FYI, the "fun with flags" reference https://www.youtube.com/watch?v=LeyofQK6tRw :)

EDIT: Actually this, where it all began https://www.youtube.com/watch?v=Xl12Sp1KiEk

[alexjeffburke]

I really like this version 👍 @sunesimonsen @papandreou all my small notes have been addressed and I'd be happy to proceed.

[papandreou]

Great! 🚀

The node.js 6 build is failing because of the use of Object.values in one of the examples.

[joelmukuthu]

Great, thanks for the reviews! I slinkied my way around the Node 6 build and will squash and merge after a successful build.

[joelmukuthu]

Someone remind me, how do I update the docs site? Or anyone mind doing it?

[papandreou]

make deploy-site 🤗

[joelmukuthu]

Thank you @papandreou. All published.