Use better yardoc tags

While this doesn't completely fix the documentation, it can really help
to understand what methods do.

Author: ekohl