Expanding the PHPDoc comments to clarify concepts

Good point, well made :)