Correct way to document multiple couses of an error

Question

I am using yardto generate documentation for some Ruby classes.

We can document some errors which can be raised by a method like this:

# @raise [ArgumentError] Cause 1
# @raise [ArgumentError] Cause 2
# @raise [ArgumentError] Cause 3
# @raise [ArgumentError] ...
# @raise [ArgumentError] Cause n

Is this a good way? Is there another better?

Answer 1

I would suggest to use markdown markup to designate different cases when the same exception occurs, rather than yard internals:

# @raise [ArgumentError] may be thrown in different circumstances:
# * Cause 1
# * Cause 2
# * Cause N

Yard seems to be confused whether it meets the same “keys” in one document block, which differ by explanation only.