Docblocks do not match

In a few classes I came across some issues with method doc-blocks not matching the actual method declarations. Also, some constructors have got `@return` annotations.

This PR fixes some of these mis-matches.