[ruby-core:64237] [ruby-trunk - Bug #10110] Exception handling is not well documented

Issue #10110 has been updated by 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?

----------------------------------------
Bug #10110: Exception handling is not well documented
https://bugs.ruby-lang.org/issues/10110#change-48227

* Author: Rodrigo Rosenfeld Rosas
* Status: Open
* Priority: Normal
* Assignee: Zachary Scott
* Category: doc
* Target version: 
* ruby -v: 2.1.2
* Backport: 2.0.0: UNKNOWN, 2.1: UNKNOWN
----------------------------------------
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...



-- 
https://bugs.ruby-lang.org/