Improve PHPDoc - missing @params, variable types, inconsistencies, typos etc.

There were a lot inconsistencies, missing param types, typos etc. in the PHPDoc, causing the IDE code completion and typehinting to be confused.