Merge pull request #1487 from hflynn/docs-tidy

Tidying stuff from nitpicks
Use Javadocs rather than source code links when possible