Document the message parameter

[gajus]

Unless I am overlooking something in http://chaijs.com/api/bdd/, there is no mention in the docs that certain methods (e.g. equal) accept an additional parameter used to describe an error in case of an error, which is implemented in expect interface, e.g.

expect(foo).to.equal(true, 'Expecting `foo` to equal true.');

[keithamus]

Hey @gajus thanks for the issue. #130 just fixed this - the documentation now states which params a method will take. I'll close this issue for now but if you think we can do better we'll re-open it and discuss a better solution.

[gajus]

I would certainly argue that there should be at least one code example using message parameter. Few people will read the API docs; most just scan the code examples.

[keithamus]

@gajus the examples are generated from the code comments within Chai itself. Would you be happy to make a PR adding code examples for each method that takes a message parameter?

[gajus]

I can. How would you like to document it?

Naming assertions make sense when there are multiple variables in an assertion, e.g.

expect(column.index).to.equal(index, 'column.index to equal index');
expect(column.name).to.equal(name, 'column.name to equal name');

[keithamus]

Looks good and makes sense to me. Looking forward to seeing your PR 😄