Updated the return values (comments/docs) of a couple of methods.
Fixed various typos and some additional phpdoc.
Merge pull request #4199 from tomzx/fixes/docs-to-4.1

Updated the return values (comments/docs) of a couple of methods.