Docblock and minor cs fixes

* I've removed any descriptions from the `@return` annotations. They can go in the short description.
* I've added a few missing fullstops on the descriptions.
* I've fixed a few return types
* I've made a few minor cs fixes