Fix: PHPDoc comments / signatures

This PR

* updates PHPDoc comments to match actual method signatures
* adds missing `throws` annotations