thoughtbot/shoulda-matchers — pull request #376 by mcmire (2013-10-27 02:15:28+00:00)
Title: Add comprehensive examples to the README

Currently we only have a very simple rundown of the API that
shoulda-matchers provides. The problem is that we do not provide
examples for every option of every method, so it is up to users to look
at the source code if they want to do something and are wondering if
shoulda-matchers provides the functionality. We also do not mention
caveats about allow_value and validates_uniqueness_of which could (and
regularly) snag users.

One could argue that method documentation is the place to exhibit the
functionality of each method, but this isn't very friendly in my
opinion. Of course, documentation isn't meant to be friendly, it's meant
to be succinct. People like and relate to examples, so I say that we
should have them somewhere.

---

I am certainly open to opinions about this. For instance, do we want to keep the README small and push examples to a separate place? I'm not sure.