Update inline docs to work with YARD

[jacius]

The existing inline documentation comments were written for RDoc. They should be updated to be compatible with YARD, and to use YARD's special features like meta-tags (@param, @return, @raise, etc.).

This is a huge job, so I don't recommend any single person try to do it all. Instead, pick a class or file, leave a comment here saying you're working on it, then make a pull request when you're done.