expect.fail() and assert.fail() could be better documented

[ashleyci]

The documentation for expect.fail() and assert.fail() doesn't have an example of usage, took me a minute or two to work out that you can't do expect().to.fail() - also the BDD version (http://chaijs.com/api/bdd/#method_fail) is duplicated in the docs. :)

[keithamus]

Thanks for this @ashleyci.

The docs for the .fail method live in the code here for expect and here for should. I think that is where the duplicate entry is coming from, so we could always set one of those docstrings to ignore (by changing /** to /*!). As for adding examples, you're right we should totally do that! How do you feel about making a PR into chai, to that effect @ashleyci?

[Peter-Lavigne]

What do each of the arguments do? When using Mocha, the message argument comes up (i.e. AssertionError: Test fails) but none of the others do.