Update some Yardoc documentation

Update the description, examples and return values specified in the Yardoc comments.