Improve JavaDoc and unit test coverage

Standardise some failure messages, add unit tests for additional cases
and to verify failure descriptions are correct, improve unit test
coverage, add JavaDoc