rewrite Ruby API docs in YARD syntax

I've updated the docs to YARD syntax and clarified some of the parameters. Hopefully clarified.

Uh, let me know if I missed anything big or small or just messed anything up in general. :+1: