a few suggestions for readability

These are somethings I like to do to make things more readable, in my opinion.

A few things here:
- using doc blocks to indicate deprecated variables, and illuminate API hooks.
- using string interpolation rather than concatenation for hook handles
- comment closing brackets of long methods & constructs for readability

I wouldn't mind continuing throughout the file but I thought I'd run a little by you guys first to start.