* 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.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@27671 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

cont.c

@@ -1422,6 +1422,21 @@ rb_fiber_s_current(VALUE klass)
     return rb_fiber_current();
 }
 
+
+
+/*
+ *  Document-class: FiberError
+ *
+ *  Raised when an invalid operation is attempted on a Fiber, in
+ *  particular when attempting to call/resume a dead fiber,
+ *  attempting to yield from the root fiber, or calling a fiber across
+ *  threads.
+ *
+ *     fiber = Fiber.new{}
+ *     fiber.resume #=> nil
+ *     fiber.resume #=> FiberError: dead fiber called
+ */
+
 void
 Init_Cont(void)
 {

enumerator.c

@@ -1021,7 +1021,22 @@ generator_each(VALUE obj)
 }
 
 /*
- * StopIteration
+ *  Document-class: StopIteration
+ *
+ *  Raised to stop the iteration, in particular by Enumerator#next. It is
+ *  rescued by Kernel#loop.
+ *
+ *     loop do
+ *       puts "Hello"
+ *       raise StopIteration
+ *       puts "World"
+ *     end
+ *     puts "Done!"
+ *
+ *  <em>produces:</em>
+ *
+ *     Hello
+ *     Done!
  */
 
 /*

error.c

@@ -1084,6 +1084,295 @@ syserr_eqq(VALUE self, VALUE exc)
     return Qfalse;
 }
 
+
+/*
+ *  Document-class: StandardError
+ *
+ *  The most standard error types are subclasses of StandardError. A
+ *  rescue clause without an explicit Exception class will rescue all
+ *  StandardErrors (and only those).
+ *
+ *     def foo
+ *       raise "Oups"
+ *     end
+ *     foo rescue "Hello"   # => "Hello"
+ *
+ *  On the other hand:
+ *
+ *     require 'does/not/exist' rescue "Hi"
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     LoadError: no such file to load -- does/not/exist
+ *
+ */
+
+/*
+ *  Document-class: SystemExit
+ *
+ *  Raised by +exit+ to initiate the termination of the script.
+ */
+
+/*
+ *  Document-class: SignalException
+ *
+ *  Raised when a signal is received.
+ *
+ *     begin
+ *       Process.kill('HUP',Process.pid)
+ *     rescue SignalException => e
+ *       puts "received Exception #{e}"
+ *     end
+ *
+ *  <em>produces:</em>
+ *
+ *     received Exception SIGHUP
+ */
+
+/*
+ *  Document-class: Interrupt
+ *
+ *  Raised with the interrupt signal is received, typically because the
+ *  user pressed on Control-C (on most posix platforms). As such, it is a
+ *  subclass of +SignalException+.
+ *
+ *     begin
+ *       puts "Press ctrl-C when you get bored"
+ *       loop {}
+ *     rescue Interrupt => e
+ *       puts "Note: You will typically use Signal.trap instead."
+ *     end
+ *
+ *  <em>produces:</em>
+ *
+ *     Press ctrl-C when you get bored
+ *
+ *  <em>then waits until it is interrupted with Control-C and then prints:</em>
+ *
+ *     Note: You will typically use Signal.trap instead.
+ */
+
+/*
+ *  Document-class: TypeError
+ *
+ *  Raised when encountering an object that is not of the expected type.
+ *
+ *     [1, 2, 3].first("two")
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     TypeError: can't convert String into Integer
+ *
+ */
+
+/*
+ *  Document-class: ArgumentError
+ *
+ *  Raised when the arguments are wrong and there isn't a more specific
+ *  Exception class.
+ *
+ *  Ex: passing the wrong number of arguments
+ *
+ *     [1, 2, 3].first(4, 5)
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     ArgumentError: wrong number of arguments (2 for 1)
+ *
+ *  Ex: passing an argument that is not acceptable:
+ *
+ *     [1, 2, 3].first(-4)
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     ArgumentError: negative array size
+ */
+
+/*
+ *  Document-class: IndexError
+ *
+ *  Raised when the given index is invalid.
+ *
+ *     a = [:foo, :bar]
+ *     a.fetch(0)   #=> :foo
+ *     a[4]         #=> nil
+ *     a.fetch(4)   #=> IndexError: index 4 outside of array bounds: -2...2
+ *
+ */
+
+/*
+ *  Document-class: KeyError
+ *
+ *  Raised when the specified key is not found. It is a subclass of
+ *  IndexError.
+ *
+ *     h = {"foo" => :bar}
+ *     h.fetch("foo") # => :bar
+ *     h.fetch("baz") # => KeyError: key not found: "baz"
+ *
+ */
+
+/*
+ *  Document-class: RangeError
+ *
+ *  Raised when a given numerical value is out of range.
+ *
+ *     [1, 2, 3].drop(1 << 100)
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     RangeError: bignum too big to convert into `long'
+ */
+
+/*
+ *  Document-class: ScriptError
+ *
+ *  ScriptError is the superclass for errors raised when a script
+ *  can not be executed because of a +LoadError+,
+ *  +NotImplementedError+ or a +SyntaxError+. Note these type of
+ *  +ScriptErrors+ are not +StandardExceptions+ and will not be
+ *  rescued unless it is specified explicitly (or its ancestor
+ *  +Exception+).
+ */
+
+/*
+ *  Document-class: SyntaxError
+ *
+ *  Raised when encountering Ruby code with an invalid syntax.
+ *
+ *     eval("1+1=2")
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     SyntaxError: (eval):1: syntax error, unexpected '=', expecting $end
+ */
+
+/*
+ *  Document-class: LoadError
+ *
+ *  Raised when a file required (a Ruby script, extension library, ...)
+ *  fails to load.
+ *
+ *     require 'this/file/does/not/exist'
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     LoadError: no such file to load -- this/file/does/not/exist
+ */
+
+/*
+ *  Document-class: NotImplementedError
+ *
+ *  Raised when a feature is not implemented on the current platform. For
+ *  example, methods depending on the +fsync+ or +fork+ system calls may
+ *  raise this exception if the underlying operating system or Ruby
+ *  runtime does not support them.
+ *
+ *  Note that if +fork+ raises a +NotImplementedError+, then
+ *  <code>respond_to?(:fork)</code> returns +false+.
+ */
+
+/*
+ *  Document-class: NameError
+ *
+ *  Raised when a given name is invalid or undefined.
+ *
+ *     puts foo
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     NameError: undefined local variable or method `foo' for main:Object
+ *
+ *  Since constant names must start with a capital:
+ *
+ *     Fixnum.const_set :answer, 42
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     NameError: wrong constant name answer
+ */
+
+/*
+ *  Document-class: NoMethodError
+ *
+ *  Raised when a method is called on a receiver which doesn't have it
+ *  defined and also fails to respond with +method_missing+.
+ *
+ *     "hello".to_ary
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     NoMethodError: undefined method `to_ary' for "hello":String
+ */
+
+/*
+ *  Document-class: RuntimeError
+ *
+ *  A generic error class raised when an invalid operation is attempted.
+ *
+ *     [1, 2, 3].freeze << 4
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     RuntimeError: can't modify frozen array
+ *
+ *  Kernel.raise will raise a RuntimeError if no Exception class is
+ *  specified.
+ *
+ *     raise "ouch"
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     RuntimeError: ouch
+ */
+
+/*
+ *  Document-class: SecurityError
+ *
+ *  Raised when attempting a potential unsafe operation, typically when
+ *  the $SAFE level is raised above 0.
+ *
+ *     foo = "bar"
+ *     proc = Proc.new do
+ *       $SAFE = 4
+ *       foo.gsub! "a", "*"
+ *     end
+ *     proc.call
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     SecurityError: Insecure: can't modify string
+ */
+
+/*
+ *  Document-class: NoMemoryError
+ *
+ *  Raised when memory allocation fails.
+ */
+
+/*
+ *  Document-class: SystemCallError
+ *
+ *  SystemCallError is the base class for all low-level
+ *  platform-dependent errors.
+ *
+ *  The errors available on the current platform are subclasses of
+ *  SystemCallError and are defined in the Errno module.
+ *
+ *     File.open("does/not/exist")
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     Errno::ENOENT: No such file or directory - does/not/exist
+ */
+
+/*
+ *  Document-class: Encoding::CompatibilityError
+ *
+ *  Raised by Encoding and String methods when the source encoding is
+ *  incompatible with the target encoding.
+ */
+
 /*
  *  Descendants of class <code>Exception</code> are used to communicate
  *  between <code>raise</code> methods and <code>rescue</code>
@@ -1091,7 +1380,8 @@ syserr_eqq(VALUE self, VALUE exc)
  *  objects carry information about the exception---its type (the
  *  exception's class name), an optional descriptive string, and
  *  optional traceback information. Programs may subclass
- *  <code>Exception</code> to add additional information.
+ *  <code>Exception</code>, or more typically <code>StandardException</code>
+ *  to provide custom classes and add additional information.
  */
 
 void

io.c

@@ -9585,6 +9585,41 @@ rb_get_argv(void)
     return ARGF.argv;
 }
 
+/*
+ * Document-class: IOError
+ *
+ * Raised when an IO operation fails.
+ *
+ *    File.open("/etc/hosts") {|f| f << "example"}
+ *      #=> IOError: not opened for writing
+ *
+ *    File.open("/etc/hosts") {|f| f.close; f.read }
+ *      #=> IOError: closed stream
+ *
+ * Note that some IO failures raise +SystemCallError+s and these are not
+ * subclasses of IOError:
+ *
+ *    File.open("does/not/exist")
+ *      #=> Errno::ENOENT: No such file or directory - does/not/exist
+ */
+
+/*
+* Document-class: EOFError
+*
+ * Raised by some IO operations when reaching the end of file. Many IO
+ * methods exist in two forms,
+ *
+ * one that returns +nil+ when the end of file is reached, the other
+ * raises EOFError +EOFError+.
+ *
+ * +EOFError+ is a subclass of +IOError+.
+ *
+ *    file = File.open("/etc/hosts")
+ *    file.read
+ *    file.gets     #=> nil
+ *    file.readline #=> EOFError: end of file reached
+ */
+
 /*
  * Document-class:  ARGF
  *

math.c

@@ -734,6 +734,22 @@ exp1(sinh)
 exp1(sqrt)
 
 
+/*
+ *  Document-class: Math::DomainError
+ *
+ *  Raised when a mathematical function is evaluated outside of its
+ *  domain of definition.
+ *
+ *  For example, since +cos+ returns values in the range -1..1,
+ *  its inverse function +acos+ is only defined on that interval:
+ *
+ *     Math.acos(42)
+ *
+ *  <em>produces:</em>
+ *
+ *     Math::DomainError: Numerical argument is out of domain - "acos"
+ */
+
 /*
  *  The <code>Math</code> module contains module functions for basic
  *  trigonometric and transcendental functions. See class

numeric.c

@@ -3198,6 +3198,38 @@ fix_even_p(VALUE num)
     return Qtrue;
 }
 
+/*
+ *  Document-class: ZeroDivisionError
+ *
+ *  Raised when attempting to divide an integer by 0.
+ *
+ *     42 / 0
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     ZeroDivisionError: divided by 0
+ *
+ *  Note that only division by an exact 0 will raise that exception:
+ *
+ *     42 /  0.0 # => Float::INFINITY
+ *     42 / -0.0 # => -Float::INFINITY
+ *     0  /  0.0 # => NaN
+ */
+
+/*
+ *  Document-class: FloatDomainError
+ *
+ *  Raised when attempting to convert special float values
+ *  (in particular infinite or NaN)
+ *  to numerical classes which don't support them.
+ *
+ *     Float::INFINITY.to_r
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     FloatDomainError: Infinity
+ */
+
 void
 Init_Numeric(void)
 {

proc.c

@@ -2006,6 +2006,49 @@ proc_curry(int argc, VALUE *argv, VALUE self)
     return make_curry_proc(self, rb_ary_new(), arity);
 }
 
+/*
+ *  Document-class: LocalJumpError
+ *
+ *  Raised when Ruby can't yield as requested.
+ *
+ *  A typical scenario is attempting to yield when no block is given:
+ *
+ *     def call_block
+ *       yield 42
+ *     end
+ *     call_block
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     LocalJumpError: no block given (yield)
+ *
+ *  A more subtle example:
+ *
+ *     def get_me_a_return
+ *       Proc.new { return 42 }
+ *     end
+ *     get_me_a_return.call
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     LocalJumpError: unexpected return
+ */
+
+/*
+ *  Document-class: SystemStackError
+ *
+ *  Raised in case of a stack overflow.
+ *
+ *     def me_myself_and_i
+ *       me_myself_and_i
+ *     end
+ *     me_myself_and_i
+ *
+ *  <em>raises the exception:</em>
+ *
+ *    SystemStackError: stack level too deep
+ */
+
 /*
  *  <code>Proc</code> objects are blocks of code that have been bound to
  *  a set of local variables. Once bound, the code may be called in

re.c

@@ -3448,6 +3448,18 @@ re_warn(const char *s)
     rb_warn("%s", s);
 }
 
+/*
+ *  Document-class: RegexpError
+ *
+ *  Raised when given an invalid regexp expression.
+ *
+ *     Regexp.new("?")
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     RegexpError: target of repeat operator is not specified: /?/
+ */
+
 /*
  *  Document-class: Regexp
  *

thread.c

@@ -4126,6 +4126,20 @@ rb_thread_backtrace_m(VALUE thval)
     return rb_thread_backtrace(thval);
 }
 
+/*
+ *  Document-class: ThreadError
+ *
+ *  Raised when an invalid operation is attempted on a thread.
+ *
+ *  For example, when no other thread has been started:
+ *
+ *     Thread.stop
+ *
+ *  <em>raises the exception:</em>
+ *
+ *     ThreadError: stopping only thread
+ */
+
 /*
  *  +Thread+ encapsulates the behavior of a thread of
  *  execution, including the main thread of the Ruby script.

transcode.c

@@ -4217,6 +4217,28 @@ ecerr_incomplete_input(VALUE self)
 
 extern void Init_newline(void);
 
+/*
+ *  Document-class: Encoding::UndefinedConversionError
+ *
+ *  Raised by Encoding and String methods when a transcoding operation
+ *  fails.
+ */
+
+/*
+ *  Document-class: Encoding::InvalidByteSequenceError
+ *
+ *  Raised by Encoding and String methods when the string being
+ *  transcoded contains a byte invalid for the either the source or
+ *  target encoding.
+ */
+
+/*
+ *  Document-class: Encoding::ConverterNotFoundError
+ *
+ *  Raised by transcoding methods when a named encoding does not
+ *  correspond with a known converter.
+ */
+
 void
 Init_transcode(void)
 {