Split public from private interface of MessageExpectation.

These things were combined all together, which made
it more difficult to tell which was which. Also,
`MessageExpectation` was labeled `@private`, which
prevented these methods from showing up on rubydoc.info.
Improve MessageExpectation docs.

- Group the methods.
- Specify return values.
- Remove blank lines that were rendering in
  example output.
Merge pull request #805 from rspec/doc-improvements

Doc improvements