Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Overhaul bdd documentation #920
Note to self: Rebase once #947 is merged and update docs for
There are two commits in this PR.
The first commit is a small change that renames the
The second commit is a huge overhaul of the bdd documentation intended to bring clarity, consistency, and guidance to every assertion. All of the examples that are intended to pass do so with the exception of two due to #919.
Quite a lot to get through here. I got up to
I'll hold off on commenting or making any changes until everyone (who wants to) has had a chance to perform a complete review.
One question though: Is it possible to add titled subsections to a particular assertion's docs? If so, how? My guess would be adding four pound signs like
Awesome job! I just left a few new minor comments.
I think this will be awesome for our contributors to read since it gives them so much information about how to use Chai effectively instead of just telling them how things work.
Great job! Also, @keithamus comments were great too, I agree with them all.
This was referenced
Jan 30, 2017
This was referenced
Feb 7, 2017
referenced this pull request
Feb 20, 2017
Okay @meeber I've reviewed all of this. Pretty much all great, I've got a few notes on some areas for concern though.
Largely I'm also sensing a theme - which is that these docs seem to suggest a lot of the assertions we provide have very limited use cases. Is this something we should be worried about? Taking a long look at the horizon, should we be slowly pushing these assertions into plugins?
@keithamus @lucasfcosta @vieiralucas @shvaikalesh I just updated this PR. I made several passes through the whole thing to address concerns, improve readability, soften and de-formalize some language, move reference links closer to concepts, etc. If there are any major issues, let's fix them. But if all that's left is minor issues, then I vote we merge and proceed with the next canary release.
I only thought about two possible changes, but nothing that could block this from being merged.