https://bugs.ruby-lang.org/https://bugs.ruby-lang.org/favicon.ico?17113305112014-08-06T20:33:35ZRuby Issue Tracking SystemRuby master - Bug #10110: Exception handling is not well documentedhttps://bugs.ruby-lang.org/issues/10110?journal_id=482272014-08-06T20:33:35Zrosenfeld (Rodrigo Rosenfeld Rosas)rr.rosas@gmail.com
<ul></ul><p>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.</p>
<p>Here is the problem:</p>
<pre><code>class CustomError < StandardError
attr_reader :cause
def initialize(cause = nil)
@cause = cause
end
end
</code></pre>
<p>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".</p>
<p>But it's not how it currently works given the class above and this snippet:</p>
<pre><code>raise CustomError, 'custom error message'
</code></pre>
<p>If you rescue this error you'll get e.cause == 'custom error message'.</p>
<p>On the other hand, if you use:</p>
<pre><code>raise CustomError.new, 'custom error message'
</code></pre>
<p>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.</p>
<p>From my point of view something is missing, and some of the actions below should be taken:</p>
<p>1 - if creating exceptions classes like demonstrated above are supported by Ruby then we should either:<br>
1.a - fix Kernel#raise to properly set the error message from the second argument as stated in its docs<br>
1.b - fix the documents to explain how the exception is instantiated depending on the first argument class<br>
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.</p>
<p>Please let me know where is the bug: the exception definition, the raise behavior or the raise documentation?</p> Ruby master - Bug #10110: Exception handling is not well documentedhttps://bugs.ruby-lang.org/issues/10110?journal_id=482432014-08-08T00:42:53Zzzak (zzak _)
<ul><li><strong>Status</strong> changed from <i>Open</i> to <i>Feedback</i></li></ul><p>Is there something more we could add here? <a href="https://github.com/ruby/ruby/blob/trunk/doc/syntax/exceptions.rdoc" class="external">https://github.com/ruby/ruby/blob/trunk/doc/syntax/exceptions.rdoc</a></p> Ruby master - Bug #10110: Exception handling is not well documentedhttps://bugs.ruby-lang.org/issues/10110?journal_id=482542014-08-08T14:40:25Zrosenfeld (Rodrigo Rosenfeld Rosas)rr.rosas@gmail.com
<ul></ul><p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p> Ruby master - Bug #10110: Exception handling is not well documentedhttps://bugs.ruby-lang.org/issues/10110?journal_id=798172019-07-22T21:06:03Zjeremyevans0 (Jeremy Evans)merch-redmine@jeremyevans.net
<ul></ul><p>Exception#cause was documented at <a class="changeset" title="* error.c: [DOC] Document Exception#cause by @jasonrclark [ci skip] [Fixes GH-519] https://gith..." href="https://bugs.ruby-lang.org/projects/ruby-master/repository/git/revisions/16220d9abbb9ef23b0049b63186da8b814f71a37">16220d9abbb9ef23b0049b63186da8b814f71a37</a>. I think the points related to Kernel#raise remain valid and will push a commit shortly to address them.</p> Ruby master - Bug #10110: Exception handling is not well documentedhttps://bugs.ruby-lang.org/issues/10110?journal_id=798182019-07-22T21:11:24Zjeremyevans (Jeremy Evans)code@jeremyevans.net
<ul><li><strong>Status</strong> changed from <i>Feedback</i> to <i>Closed</i></li></ul><p>Applied in changeset <a class="changeset" title="Adjust documentation for Kernel#raise [ci skip] Mention how each of the arguments are retrievabl..." href="https://bugs.ruby-lang.org/projects/ruby-master/repository/git/revisions/c1ad6321b03bcf9f96f975bcba7ff1d205990149">git|c1ad6321b03bcf9f96f975bcba7ff1d205990149</a>.</p>
<hr>
<p>Adjust documentation for Kernel#raise [ci skip]</p>
<p>Mention how each of the arguments are retrievable from the generated<br>
Exception object.</p>
<p>Fixes [Bug <a class="issue tracker-1 status-5 priority-4 priority-default closed" title="Bug: Exception handling is not well documented (Closed)" href="https://bugs.ruby-lang.org/issues/10110">#10110</a>]</p>