[DOC] missing docs at toplevel

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

dir.c

@@ -2859,6 +2859,26 @@ dir_s_each_child(int argc, VALUE *argv, VALUE io)
     return Qnil;
 }
 
+/*
+ *  call-seq:
+ *     dir.each_child {| filename | block }  -> nil
+ *     dir.each_child                        -> an_enumerator
+ *
+ *  Calls the block once for each entry except for "." and ".." in
+ *  this directory, passing the filename of each entry as a parameter
+ *  to the block.
+ *
+ *  If no block is given, an enumerator is returned instead.
+ *
+ *     d = Dir.new("testdir")
+ *     d.each_child  {|x| puts "Got #{x}" }
+ *
+ *  <em>produces:</em>
+ *
+ *     Got config.h
+ *     Got main.rb
+ *
+ */
 static VALUE
 dir_each_child_m(VALUE dir)
 {
@@ -2866,6 +2886,17 @@ dir_each_child_m(VALUE dir)
     return dir_each_entry(dir, dir_yield, Qnil, TRUE);
 }
 
+/*
+ *  call-seq:
+ *     dir.children  -> array
+ *
+ *  Returns an array containing all of the filenames except for "."
+ *  and ".." in this directory.
+ *
+ *     d = Dir.new("testdir")
+ *     d.children   #=> ["config.h", "main.rb"]
+ *
+ */
 static VALUE
 dir_collect_children(VALUE dir)
 {

error.c

@@ -1652,6 +1652,13 @@ nometh_err_args(VALUE self)
     return rb_attr_get(self, id_args);
 }
 
+/*
+ * call-seq:
+ *   no_method_error.private_call?  -> true or false
+ *
+ * Return true if the caused method was called as private.
+ */
+
 static VALUE
 nometh_err_private_call_p(VALUE self)
 {

file.c

@@ -6250,6 +6250,7 @@ Init_File(void)
     separator = rb_fstring_cstr("/");
     /* separates directory parts in path */
     rb_define_const(rb_cFile, "Separator", separator);
+    /* separates directory parts in path */
     rb_define_const(rb_cFile, "SEPARATOR", separator);
     rb_define_singleton_method(rb_cFile, "split",  rb_file_s_split, 1);
     rb_define_singleton_method(rb_cFile, "join",   rb_file_s_join, -2);

gc.c

@@ -8586,6 +8586,7 @@ wmap_has_key(VALUE self, VALUE key)
     return NIL_P(wmap_aref(self, key)) ? Qfalse : Qtrue;
 }
 
+/* Returns the number of referenced objects */
 static VALUE
 wmap_size(VALUE self)
 {
@@ -9526,6 +9527,13 @@ rb_gcdebug_sentinel(VALUE obj, const char *name)
 #endif /* GC_DEBUG */
 
 #if GC_DEBUG_STRESS_TO_CLASS
+/*
+ *  call-seq:
+ *    GC.add_stress_to_class(class[, ...])
+ *
+ *  Raises NoMemoryError when allocating an instance of the given classes.
+ *
+ */
 static VALUE
 rb_gcdebug_add_stress_to_class(int argc, VALUE *argv, VALUE self)
 {
@@ -9538,6 +9546,14 @@ rb_gcdebug_add_stress_to_class(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
+/*
+ *  call-seq:
+ *    GC.remove_stress_to_class(class[, ...])
+ *
+ *  No longer raises NoMemoryError when allocating an instance of the
+ *  given classes.
+ *
+ */
 static VALUE
 rb_gcdebug_remove_stress_to_class(int argc, VALUE *argv, VALUE self)
 {
@@ -9645,6 +9661,7 @@ Init_GC(void)
     rb_hash_aset(gc_constants, ID2SYM(rb_intern("HEAP_PAGE_BITMAP_SIZE")), SIZET2NUM(HEAP_PAGE_BITMAP_SIZE));
     rb_hash_aset(gc_constants, ID2SYM(rb_intern("HEAP_PAGE_BITMAP_PLANES")), SIZET2NUM(HEAP_PAGE_BITMAP_PLANES));
     OBJ_FREEZE(gc_constants);
+    /* internal constants */
     rb_define_const(rb_mGC, "INTERNAL_CONSTANTS", gc_constants);
 
     rb_mProfiler = rb_define_module_under(rb_mGC, "Profiler");
@@ -9706,9 +9723,9 @@ Init_GC(void)
     rb_define_singleton_method(rb_mGC, "remove_stress_to_class", rb_gcdebug_remove_stress_to_class, -1);
 #endif
 
-    /* ::GC::OPTS, which shows GC build options */
     {
 	VALUE opts;
+	/* GC build options */
 	rb_define_const(rb_mGC, "OPTS", opts = rb_ary_new());
 #define OPT(o) if (o) rb_ary_push(opts, rb_fstring_lit(#o))
 	OPT(GC_DEBUG);

hash.c

@@ -3186,6 +3186,19 @@ hash_proc_call(VALUE key, VALUE hash, int argc, const VALUE *argv, VALUE passed_
     return rb_hash_aref(hash, *argv);
 }
 
+/*
+ * call-seq:
+ *   hash.to_proc -> proc
+ *
+ * Returns a Proc which maps keys to values.
+ *
+ *   h = {a:1, b:2}
+ *   hp = h.to_proc
+ *   hp.call(:a)          #=> 1
+ *   hp.call(:b)          #=> 2
+ *   hp.call(:c)          #=> nil
+ *   [:a, :b, :c].map(&h) #=> [1, 2, nil]
+ */
 static VALUE
 rb_hash_to_proc(VALUE hash)
 {

io.c

@@ -12928,10 +12928,14 @@ Init_IO(void)
     rb_cIO = rb_define_class("IO", rb_cObject);
     rb_include_module(rb_cIO, rb_mEnumerable);
 
+    /* exception to wait for reading. see IO.select. */
     rb_mWaitReadable = rb_define_module_under(rb_cIO, "WaitReadable");
+    /* exception to wait for writing. see IO.select. */
     rb_mWaitWritable = rb_define_module_under(rb_cIO, "WaitWritable");
+    /* exception to wait for reading by EAGAIN. see IO.select. */
     rb_eEAGAINWaitReadable = rb_define_class_under(rb_cIO, "EAGAINWaitReadable", rb_eEAGAIN);
     rb_include_module(rb_eEAGAINWaitReadable, rb_mWaitReadable);
+    /* exception to wait for writing by EAGAIN. see IO.select. */
     rb_eEAGAINWaitWritable = rb_define_class_under(rb_cIO, "EAGAINWaitWritable", rb_eEAGAIN);
     rb_include_module(rb_eEAGAINWaitWritable, rb_mWaitWritable);
 #if EAGAIN == EWOULDBLOCK
@@ -12942,13 +12946,17 @@ Init_IO(void)
     /* same as IO::EAGAINWaitWritable */
     rb_define_const(rb_cIO, "EWOULDBLOCKWaitWritable", rb_eEAGAINWaitWritable);
 #else
+    /* exception to wait for reading by EWOULDBLOCK. see IO.select. */
     rb_eEWOULDBLOCKWaitReadable = rb_define_class_under(rb_cIO, "EWOULDBLOCKWaitReadable", rb_eEWOULDBLOCK);
     rb_include_module(rb_eEWOULDBLOCKWaitReadable, rb_mWaitReadable);
+    /* exception to wait for writing by EWOULDBLOCK. see IO.select. */
     rb_eEWOULDBLOCKWaitWritable = rb_define_class_under(rb_cIO, "EWOULDBLOCKWaitWritable", rb_eEWOULDBLOCK);
     rb_include_module(rb_eEWOULDBLOCKWaitWritable, rb_mWaitWritable);
 #endif
+    /* exception to wait for reading by EINPROGRESS. see IO.select. */
     rb_eEINPROGRESSWaitReadable = rb_define_class_under(rb_cIO, "EINPROGRESSWaitReadable", rb_eEINPROGRESS);
     rb_include_module(rb_eEINPROGRESSWaitReadable, rb_mWaitReadable);
+    /* exception to wait for writing by EINPROGRESS. see IO.select. */
     rb_eEINPROGRESSWaitWritable = rb_define_class_under(rb_cIO, "EINPROGRESSWaitWritable", rb_eEINPROGRESS);
     rb_include_module(rb_eEINPROGRESSWaitWritable, rb_mWaitWritable);
 

parse.y

@@ -6069,6 +6069,13 @@ heredoc_dedent(struct parser_params *p, VALUE array)
     return array;
 }
 
+/*
+ *  call-seq:
+ *    Ripper.dedent_string(input, width)   -> string
+ *
+ *  Strips leading +width+ whitespaces from +input+, and returns
+ *  stripped column width.
+ */
 static VALUE
 parser_dedent_string(VALUE self, VALUE input, VALUE width)
 {
@@ -11309,6 +11316,12 @@ ripper_value(VALUE self, VALUE obj)
 }
 #endif
 
+/*
+ *  call-seq:
+ *    Ripper.lex_state_name(integer)   -> string
+ *
+ *  Returns a string representation of lex_state.
+ */
 static VALUE
 ripper_lex_state_name(VALUE self, VALUE state)
 {

process.c

@@ -393,6 +393,12 @@ parent_redirect_close(int fd)
 #define parent_redirect_close(fd) close_unless_reserved(fd)
 #endif
 
+/*
+ * Document-module: Process
+ *
+ * Module to handle processes.
+ */
+
 /*
  *  call-seq:
  *     Process.pid   -> integer
@@ -7974,6 +7980,7 @@ InitVM_process(void)
     rb_define_module_function(rb_mProcess, "clock_getres", rb_clock_getres, -1);
 
 #if defined(HAVE_TIMES) || defined(_WIN32)
+    /* Placeholder for rusage */
     rb_cProcessTms = rb_struct_define_under(rb_mProcess, "Tms", "utime", "stime", "cutime", "cstime", NULL);
     /* An obsolete name of Process::Tms for the backward compatibility */
     rb_define_const(rb_cStruct, "Tms", rb_cProcessTms);

random.c

@@ -1378,6 +1378,16 @@ rand_random(int argc, VALUE *argv, VALUE obj, rb_random_t *rnd)
     return rand_range(obj, rnd, vmax);
 }
 
+/*
+ * call-seq:
+ *   prng.random_number      -> float
+ *   prng.random_number(max) -> number
+ *   prng.rand               -> float
+ *   prng.rand(max)          -> number
+ *
+ * Generates formatted random number from raw random bytes.
+ * See Random#rand.
+ */
 static VALUE
 rand_random_number(int argc, VALUE *argv, VALUE obj)
 {
@@ -1644,6 +1654,8 @@ InitVM_Random(void)
     {
 	/* Direct access to Ruby's Pseudorandom number generator (PRNG). */
 	VALUE rand_default = Init_Random_default();
+	/* The default Pseudorandom number generator.  Used by class
+	 * methods of Random. */
 	rb_define_const(rb_cRandom, "DEFAULT", rand_default);
     }
 
@@ -1656,6 +1668,7 @@ InitVM_Random(void)
     rb_define_private_method(CLASS_OF(rb_cRandom), "left", random_s_left, 0);
 
     {
+	/* Format raw random number as Random does */
 	VALUE m = rb_define_module_under(rb_cRandom, "Formatter");
 	rb_include_module(rb_cRandom, m);
 	rb_define_method(m, "random_number", rand_random_number, -1);

thread.c

@@ -3182,6 +3182,19 @@ rb_thread_aref(VALUE thread, VALUE key)
     return rb_thread_local_aref(thread, id);
 }
 
+/*
+ *  call-seq:
+ *      thr.fetch(sym)           -> obj
+ *      thr.fetch(sym) { }       -> obj
+ *      thr.fetch(sym, default)  -> obj
+ *
+ *  Returns a fiber-local for the given key. If the key can't be
+ *  found, there are several options: With no other arguments, it will
+ *  raise a <code>KeyError</code> exception; if <i>default</i> is
+ *  given, then that will be returned; if the optional code block is
+ *  specified, then that will be run and its result returned.
+ *  See Thread#[] and Hash#fetch.
+ */
 static VALUE
 rb_thread_fetch(int argc, VALUE *argv, VALUE self)
 {

thread_sync.c

@@ -649,6 +649,13 @@ queue_closed_p(VALUE self)
     return FL_TEST_RAW(self, QUEUE_CLOSED) != 0;
 }
 
+/*
+ *  Document-class: ClosedQueueError
+ *
+ *  The exception class which will be raised when pushing into a close
+ *  Queue.  See Queue#close and SizedQueue#close.
+ */
+
 NORETURN(static void raise_closed_queue_error(VALUE self));
 
 static void
@@ -1161,6 +1168,15 @@ rb_szqueue_clear(VALUE self)
     return self;
 }
 
+/*
+ * Document-method: SizedQueue#length
+ * call-seq:
+ *   length
+ *   size
+ *
+ * Returns the length of the queue.
+ */
+
 static VALUE
 rb_szqueue_length(VALUE self)
 {

transcode.c

@@ -2905,6 +2905,11 @@ encoded_dup(VALUE newstr, VALUE str, int encidx)
     return str_encode_associate(newstr, encidx);
 }
 
+/*
+ * Document-class: Encoding::Converter
+ *
+ * Encoding conversion class.
+ */
 static void
 econv_free(void *ptr)
 {

vm.c

@@ -2767,6 +2767,7 @@ core_hash_merge_kwd(int argc, VALUE *argv)
     return hash;
 }
 
+/* Returns true if JIT is enabled */
 static VALUE
 mjit_enabled_p(void)
 {