Fixed bad composer merges from 4.1 to 4.2
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.
Fix comments.
Merge branch '4.1'
Merge pull request #4195 from GrahamCampbell/4.2-composer

Fixed bad composer merges from 4.1 to 4.2