fill rdocs

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

error.c

@@ -1753,6 +1753,7 @@ Init_Exception(void)
     rb_eSyntaxError = rb_define_class("SyntaxError", rb_eScriptError);
 
     rb_eLoadError   = rb_define_class("LoadError", rb_eScriptError);
+    /* the path failed to load */
     rb_attr(rb_eLoadError, rb_intern("path"), 1, 0, Qfalse);
 
     rb_eNotImpError = rb_define_class("NotImplementedError", rb_eScriptError);

file.c

@@ -5571,16 +5571,19 @@ Init_File(void)
     rb_define_singleton_method(rb_cFile, "path", rb_file_s_path, 1);
 
     separator = rb_obj_freeze(rb_usascii_str_new2("/"));
+    /* separates directory parts in path */
     rb_define_const(rb_cFile, "Separator", separator);
     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);
 
 #ifdef DOSISH
+    /* platform specific alternative separator */
     rb_define_const(rb_cFile, "ALT_SEPARATOR", rb_obj_freeze(rb_usascii_str_new2(file_alt_separator)));
 #else
     rb_define_const(rb_cFile, "ALT_SEPARATOR", Qnil);
 #endif
+    /* path list separator */
     rb_define_const(rb_cFile, "PATH_SEPARATOR", rb_obj_freeze(rb_str_new2(PATH_SEP)));
 
     rb_define_method(rb_cIO, "stat",  rb_io_stat, 0); /* this is IO's method */

hash.c

@@ -1262,6 +1262,7 @@ replace_i(VALUE key, VALUE val, VALUE hash)
     return ST_CONTINUE;
 }
 
+/* :nodoc: */
 static VALUE
 rb_hash_initialize_copy(VALUE hash, VALUE hash2)
 {

io.c

@@ -11735,8 +11735,10 @@ Init_IO(void)
     rb_include_module(rb_eEAGAINWaitWritable, rb_mWaitWritable);
 #if EAGAIN == EWOULDBLOCK
     rb_eEWOULDBLOCKWaitReadable = rb_eEAGAINWaitReadable;
+    /* same as IO::EAGAINWaitReadable */
     rb_define_const(rb_cIO, "EWOULDBLOCKWaitReadable", rb_eEAGAINWaitReadable);
     rb_eEWOULDBLOCKWaitWritable = rb_eEAGAINWaitWritable;
+    /* same as IO::EAGAINWaitWritable */
     rb_define_const(rb_cIO, "EWOULDBLOCKWaitWritable", rb_eEAGAINWaitWritable);
 #else
     rb_eEWOULDBLOCKWaitReadable = rb_define_class_under(rb_cIO, "EWOULDBLOCKWaitReadable", rb_eEWOULDBLOCK);
@@ -11838,8 +11840,11 @@ Init_IO(void)
     rb_define_method(rb_cIO, "flush", rb_io_flush, 0);
     rb_define_method(rb_cIO, "tell", rb_io_tell, 0);
     rb_define_method(rb_cIO, "seek", rb_io_seek_m, -1);
+    /* Set I/O position from the beginning */
     rb_define_const(rb_cIO, "SEEK_SET", INT2FIX(SEEK_SET));
+    /* Set I/O position from the current position */
     rb_define_const(rb_cIO, "SEEK_CUR", INT2FIX(SEEK_CUR));
+    /* Set I/O position from the end */
     rb_define_const(rb_cIO, "SEEK_END", INT2FIX(SEEK_END));
     rb_define_method(rb_cIO, "rewind", rb_io_rewind, 0);
     rb_define_method(rb_cIO, "pos", rb_io_tell, 0);

marshal.c

@@ -2146,7 +2146,9 @@ Init_marshal(void)
     rb_define_module_function(rb_mMarshal, "load", marshal_load, -1);
     rb_define_module_function(rb_mMarshal, "restore", marshal_load, -1);
 
+    /* major version */
     rb_define_const(rb_mMarshal, "MAJOR_VERSION", INT2FIX(MARSHAL_MAJOR));
+    /* minor version */
     rb_define_const(rb_mMarshal, "MINOR_VERSION", INT2FIX(MARSHAL_MINOR));
 
     compat_allocator_tbl = st_init_numtable();

parse.y

@@ -11436,6 +11436,7 @@ InitVM_ripper(void)
     VALUE Ripper;
 
     Ripper = rb_define_class("Ripper", rb_cObject);
+    /* version of Ripper */
     rb_define_const(Ripper, "Version", rb_usascii_str_new2(RIPPER_VERSION));
     rb_define_alloc_func(Ripper, ripper_s_allocate);
     rb_define_method(Ripper, "initialize", ripper_initialize, -1);

process.c

@@ -4787,6 +4787,17 @@ obj2uid(VALUE id
 }
 
 # ifdef p_uid_from_name
+/*
+ *  call-seq:
+ *     Process::UID.from_name(name)   -> uid
+ *
+ *  Get the user ID by the _name_.
+ *  If the user is not found, +ArgumentError+ will be raised.
+ *
+ *     Process::UID.from_name("root") #=> 0
+ *     Process::UID.from_name("nosuchuser") #=> can't find user for nosuchuser (ArgumentError)
+ */
+
 static VALUE
 p_uid_from_name(VALUE self, VALUE id)
 {
@@ -4835,6 +4846,17 @@ obj2gid(VALUE id
 }
 
 # ifdef p_gid_from_name
+/*
+ *  call-seq:
+ *     Process::GID.from_name(name)   -> gid
+ *
+ *  Get the group ID by the _name_.
+ *  If the group is not found, +ArgumentError+ will be raised.
+ *
+ *     Process::GID.from_name("wheel") #=> 0
+ *     Process::GID.from_name("nosuchgroup") #=> can't find group for nosuchgroup (ArgumentError)
+ */
+
 static VALUE
 p_gid_from_name(VALUE self, VALUE id)
 {

vm.c

@@ -2422,9 +2422,11 @@ Init_VM(void)
 
 #if VM_COLLECT_USAGE_DETAILS
     /* ::RubyVM::USAGE_ANALYSIS_* */
-    rb_define_const(rb_cRubyVM, "USAGE_ANALYSIS_INSN", rb_hash_new());
-    rb_define_const(rb_cRubyVM, "USAGE_ANALYSIS_REGS", rb_hash_new());
-    rb_define_const(rb_cRubyVM, "USAGE_ANALYSIS_INSN_BIGRAM", rb_hash_new());
+#define define_usage_analysis_hash(name) /* shut up rdoc -C */ \
+    rb_define_const(rb_cRubyVM, "USAGE_ANALYSIS_"#name, rb_hash_new())
+    define_usage_analysis_hash("INSN");
+    define_usage_analysis_hash("REGS");
+    define_usage_analysis_hash("INSN_BIGRAM");
 
     rb_define_singleton_method(rb_cRubyVM, "USAGE_ANALYSIS_INSN_STOP", usage_analysis_insn_stop, 0);
     rb_define_singleton_method(rb_cRubyVM, "USAGE_ANALYSIS_OPERAND_STOP", usage_analysis_operand_stop, 0);