Expanding the PHPDoc comments to clarify concepts

Let's not use @package and @uses, it's duplication, hard to maintain, and bound to turn into comment rot.