Documentation tidy up

It seems yardoc doesn't follow its own documented behaviour. `@param` tags only work when ordered type _then_ name.

A bunch of formatting pedantry also.