rewrite Ruby API docs in YARD syntax

close jlnr/gosu#185
remove "in pixels" where it may not be true
switch to markdown for docstring syntax
a handful of fixes, clarifications and cleanup
RDoc -> YARD + Markdown in the Rakefile
Merge pull request #186 from erisdiscord/yard

rewrite Ruby API docs in YARD syntax