A way to document alternative return values

[agladysh]

Currently two @return tags yield text that can be read as mutltiple return values documentation (i.e. and).

Functions that can return different things depending on the situation are not that rare. Is there a way to document alternative return values (i.e. or)?

There should probably be a special syntax (and, maybe, a template in the output) for a set of nil, error_message alternatives, but non-error alternative returns should be supported as well.

For example I've recently written a function that returns an object if it is found, false if it is not and nil, error_message on error.

[stevedonovan]

This is a good point. I'm open to suggestions on how to indicate 'or' rather than 'and'. (Dynamic languages are such fun to document!)

[agladysh]

Do we need and as default?

Would this be too hard to do?

@return 
  @nil
  @string error message

(OTOH, backwards compatibility...)

[alerque]

This is not fixed yet, I'm open to suggestions or PRs!