Fixes #5032: big cleanup of docs/unused code, small code improvements

I went through most of /engine and looked at almost everything PhpStorm's analyzer flagged as suspicious. This led to lots of doc fixes/typos, removal of unused vars, more simplified logic, and a lot of new @todos. After making all the changes I split them into logical commits for easier digestion. I tried to avoid code that's known to have moved/removed in 1.9 to make this easier to merge.

There are some small functionality improvements, but mainly this improves PhpStorm's ability to help detect bugs, and should make safer autocomplete when working on this code.

Maybe the most controversial changes are the use of `Classname[]` style tokens to document arrays of a particular type. In a capable IDE this makes a huge difference, as you get type comprehension even on dereferenced array items.