Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
docs(addAssertion): document alternations, flags and optional values #668
alexjeffburke left a comment
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.
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?