Bug #10110: Exception handling is not well documented

• Status: Closed
• Assignee: zzak (zzak _)
• Target version: -
• ruby -v: 2.1.2
• Backport: 2.0.0: UNKNOWN, 2.1: UNKNOWN

[rosenfeld (Rodrigo Rosenfeld Rosas)]

Exception#cause has no documentation at all:

http://www.ruby-doc.org/core-2.1.2/Exception.html#method-i-cause

This is the documentation for Kernel.raise:

With no arguments, raises the exception in $! or raises a RuntimeError if $! is nil. With a single String argument, raises a RuntimeError with the string as a message. Otherwise, the first parameter should be the name of an Exception class (or an object that returns an Exception object when sent an exception message). The optional second parameter sets the message associated with the exception, and the third parameter is an array of callback information. Exceptions are caught by the rescue clause of begin...end blocks.

It's not clear how to get this last argument, i.e., the "callback information". What is a callback information? Does this relate to Exception#cause or Exception#backtrace?

This is all very confusing to me and it would help if someone could please make it clear...

[rosenfeld (Rodrigo Rosenfeld Rosas)]

Ok, I could get a better understanding of how this works from another message in the mailing list but there's something missing in the documentation.

Here is the problem:

class CustomError < StandardError
  attr_reader :cause

  def initialize(cause = nil)
    @cause = cause
  end
end

So, this is the first question. My coworker insists this is a valid way of describing an exception. If that's true, then it means the documentation of Kernel#raise is incomplete. The documentation states that the "second parameter sets the message associated with the exception".

But it's not how it currently works given the class above and this snippet:

raise CustomError, 'custom error message'

If you rescue this error you'll get e.cause == 'custom error message'.

On the other hand, if you use:

raise CustomError.new, 'custom error message'

Then it works fine. The cause would be nil in that case while the error message would indeed be set to 'custom error message' as stated in the documentation.

From my point of view something is missing, and some of the actions below should be taken:

1 - if creating exceptions classes like demonstrated above are supported by Ruby then we should either:
1.a - fix Kernel#raise to properly set the error message from the second argument as stated in its docs
1.b - fix the documents to explain how the exception is instantiated depending on the first argument class
2 - Otherwise (writing such classes is not supported) it should be explained in the Exception class whether the constructor is allowed to be overriden and if so how their arguments are expected to be like.

Please let me know where is the bug: the exception definition, the raise behavior or the raise documentation?

[zzak (zzak _)]

• Status changed from Open to Feedback

Is there something more we could add here? https://github.com/ruby/ruby/blob/trunk/doc/syntax/exceptions.rdoc

[rosenfeld (Rodrigo Rosenfeld Rosas)]

Good documentation but it didn't touch the points mentioned in the issue. Exception#cause is neither mentioned nor documented in the API docs. For instance, in the Kernel#raise doc, there's this snippet: "... and the third parameter is an array of callback information". It's not clear that the third argument will actually be the result of calling the resulting exception.backtrace. This should be made clear.

Also from another discussion when Exception#cause was introduced I think it was mentioned that it was possible to call raise ..., cause: xxx. If this is indeed possible this should be also documented in that Exception#raise documentation.

Finally, take a look at my previous comment. It's not clear how the exceptions are created for each possible way to call Kernel#raise.

I'll try to add some pull request for the things I already know about (most probably next month since I'm taking vacations and traveling soon and have only one week of work left with tons of things to do) but I don't know the answer for my previous comment so I can't document that behavior.

[jeremyevans0 (Jeremy Evans)]

Exception#cause was documented at 16220d9abbb9ef23b0049b63186da8b814f71a37. I think the points related to Kernel#raise remain valid and will push a commit shortly to address them.

• Status changed from Feedback to Closed

Applied in changeset git|c1ad6321b03bcf9f96f975bcba7ff1d205990149.

---

Adjust documentation for Kernel#raise [ci skip]

Mention how each of the arguments are retrievable from the generated
Exception object.

Fixes [Bug #10110]