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

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

* Author: Rodrigo Rosenfeld Rosas
* Status: Feedback
* 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/