* thread.c: Document Thread::new, clean up ::fork and mention calling

super if subclassing Thread


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

ChangeLog

@@ -1,3 +1,8 @@
+Mon Feb 25 12:48:00 2013  Zachary Scott  <zachary@zacharyscott.net>
+
+	* thread.c: Document Thread::new, clean up ::fork and mention calling
+	  super if subclassing Thread
+
 Mon Feb 25 12:38:50 2013  Tanaka Akira  <akr@fsij.org>
 
 	* ext/socket/extconf.rb: don't test ss_family and ss_len member of

thread.c

@@ -622,7 +622,26 @@ thread_create_core(VALUE thval, VALUE args, VALUE (*fn)(ANYARGS))
     return thval;
 }
 
-/* :nodoc: */
+/*
+ * call-seq:
+ *  Thread.new { ... }			-> thread
+ *  Thread.new(*args, &proc)		-> thread
+ *  Thread.new(*args) { |args| ... }	-> thread
+ *
+ *  Creates a new thread executing the given block.
+ *
+ *  Any +args+ given to ::new will be passed to the block:
+ *
+ *	arr = []
+ *	a, b, c = 1, 2, 3
+ *	Thread.new(a,b,c) { |d,e,f| arr << d << e << f }.join
+ *	arr #=> [1, 2, 3]
+ *
+ *  A ThreadError exception is raised if ::new is called without a block.
+ *
+ *  If you're going to subclass Thread, be sure to call super in your
+ *  +initialize+ method, otherwise a ThreadError will be raised.
+ */
 static VALUE
 thread_s_new(int argc, VALUE *argv, VALUE klass)
 {
@@ -646,9 +665,12 @@ thread_s_new(int argc, VALUE *argv, VALUE klass)
  *     Thread.start([args]*) {|args| block }   -> thread
  *     Thread.fork([args]*) {|args| block }    -> thread
  *
- *  Basically the same as <code>Thread::new</code>. However, if class
+ *  Basically the same as ::new. However, if class Thread is subclassed, then
- *  <code>Thread</code> is subclassed, then calling <code>start</code> in that
+ *  calling +start+ in that subclass will not invoke the subclass's
- *  subclass will not invoke the subclass's <code>initialize</code> method.
+ *  +initialize+ method.
+ *
+ *  If you're going to subclass Thread, be sure to call super in your
+ *  +initialize+ method, otherwise a ThreadError will be raised.
  */
 
 static VALUE