Bug #2829

Missing documentation for Exception subclasses.

Added by Marc-Andre Lafortune almost 2 years ago. Updated 10 months ago.

[ruby-core:28394]
Status:Closed Start date:03/02/2010
Priority:Normal Due date:
Assignee:Marc-Andre Lafortune % Done:

100%
Category:DOC
Target version:1.9.2
ruby -v:ruby 1.9.2dev (2010-03-02 trunk 26792) [x86_64-darwin10.2.0]

Description

I noticed that the documentation for Exception subclasses are either that of Exception itself, or just plain non-sensical because they are actually missing (see ZeroDivisionError, FiberError, ...)

It would be preferable if the Exception classes were at least briefly described.

I've made a first draft of a description for all Exception subclasses, and would encourage anyone interested in improving it by editing the wiki:

http://redmine.ruby-lang.org/wiki/ruby/ExceptionClassesDoc

Thanks.

Associated revisions

Revision 27670
Added by Marc-Andre Lafortune almost 2 years ago

* array.c (rb_ary_fetch, rb_ary_splice, rb_ary_store): Improve IndexError messages [ruby-core:28394] * hash.c (rb_hash_fetch_m): Improve KeyError message

Revision 27671
Added by Marc-Andre Lafortune almost 2 years ago

* error.c: RDoc for subclasses of Exception. [ruby-core:28394] * cont.c: ditto * enumerator.c: ditto * io.c: ditto * math.c: ditto * numeric.c: ditto * proc.c: ditto * re.c: ditto * thread.c: ditto * transcode.c: ditto. Thanks to Run Paint for some of the documentation.

History

#1
Updated by Yusuke Endoh almost 2 years ago

  • Assignee set to Marc-Andre Lafortune
Hi,

> I've made a first draft of a description for all Exception subclasses, and would encourage anyone interested in improving it by editing the wiki:
>
> http://redmine.ruby-lang.org/wiki/ruby/ExceptionClassesDoc

Outstanding work!

My comments:

> NotImplementedError
>   Raised when a method is not implemented on the current platform.

I prefer "feature" to "method", because some method is actually
defined but NotImplementedError may be raised depending on the
argument (e.g., Process.uid=).


> SyntaxError
>   Raised when attempting to parse Ruby code with an invalid syntax.

I could be paranoid, but SyntaxError may be raised in compile
phase.  So "execute" would be better than "parse".


> LocalJumpError
>   Raised when attempting to return out of a context that no longer exists.

There is simpler situation: no block given (yield).
Attempting to return across Threads will also raise LocalJumpError.

  def foo
    Thread.new { return }.join
  end
  foo

But I don't have better concrete explanation.  Sorry.


> NameError
>   Raised when a given name is invalid (e.g. a constant's name can not be "my_constant" since it must start with a capital letter)

It will also be raised when referring undefined (uninitialized)
local variable.

   undefined local variable or method `foo' for main:Object (NameError)


Anyway, I agree with importing them.

-- 
Yusuke Endoh <mame@tsg.ne.jp>

#2
Updated by Marc-Andre Lafortune almost 2 years ago

Hi Yusuke.

Thanks for these comments. I've updated the wiki accordingly. I've also added examples to most exception classes.

Unless there is objection, I plan on changing the following error messages:

[1, 2].fetch(-3)
From: index -1 out of array
To:   index -3 outside of array bounds: -2...2

{}.fetch("foo")
From: key not found
To:   key not found: "foo"

I will also commit the changes documentation unless there are further comments.

--
Marc-André

#3
Updated by Marc-Andre Lafortune almost 2 years ago

  • Status changed from Open to Closed
  • % Done changed from 0 to 100
This issue was solved with changeset r27670.
Marc-Andre, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.

Also available in: Atom PDF