In the docs, specify when a method can also return nil (besides its usual types)
Use Yard's @raise tag to document exception raises
Use Yard's @see tag when appropriate