Stop PHPStorm hating me

Mostly docs changes and type hinting. Also some more
substantive changes, but only really of the "tweak"
variety.

Change-Id: I3335526fc00bb8a5e0c1faaa7f1692486f93d98d
Merge "Stop PHPStorm hating me"