ruby-changes:50427
From: nobu <ko1@a...>
Date: Fri, 23 Feb 2018 11:26:22 +0900 (JST)
Subject: [ruby-changes:50427] nobu:r62544 (trunk): [DOC] missing docs at toplevel
nobu 2018-02-23 11:18:52 +0900 (Fri, 23 Feb 2018) New Revision: 62544 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=62544 Log: [DOC] missing docs at toplevel Modified files: trunk/dir.c trunk/error.c trunk/file.c trunk/gc.c trunk/hash.c trunk/io.c trunk/parse.y trunk/process.c trunk/random.c trunk/thread.c trunk/thread_sync.c trunk/transcode.c trunk/vm.c Index: thread_sync.c =================================================================== --- thread_sync.c (revision 62543) +++ thread_sync.c (revision 62544) @@ -649,6 +649,13 @@ queue_closed_p(VALUE self) https://github.com/ruby/ruby/blob/trunk/thread_sync.c#L649 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) https://github.com/ruby/ruby/blob/trunk/thread_sync.c#L1168 return self; } +/* + * Document-method: SizedQueue#length + * call-seq: + * length + * size + * + * Returns the length of the queue. + */ + static VALUE rb_szqueue_length(VALUE self) { Index: io.c =================================================================== --- io.c (revision 62543) +++ io.c (revision 62544) @@ -12928,10 +12928,14 @@ Init_IO(void) https://github.com/ruby/ruby/blob/trunk/io.c#L12928 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) https://github.com/ruby/ruby/blob/trunk/io.c#L12946 /* 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); Index: thread.c =================================================================== --- thread.c (revision 62543) +++ thread.c (revision 62544) @@ -3182,6 +3182,19 @@ rb_thread_aref(VALUE thread, VALUE key) https://github.com/ruby/ruby/blob/trunk/thread.c#L3182 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) { Index: dir.c =================================================================== --- dir.c (revision 62543) +++ dir.c (revision 62544) @@ -2859,6 +2859,26 @@ dir_s_each_child(int argc, VALUE *argv, https://github.com/ruby/ruby/blob/trunk/dir.c#L2859 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) https://github.com/ruby/ruby/blob/trunk/dir.c#L2886 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) { Index: gc.c =================================================================== --- gc.c (revision 62543) +++ gc.c (revision 62544) @@ -8586,6 +8586,7 @@ wmap_has_key(VALUE self, VALUE key) https://github.com/ruby/ruby/blob/trunk/gc.c#L8586 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 cha https://github.com/ruby/ruby/blob/trunk/gc.c#L9527 #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, https://github.com/ruby/ruby/blob/trunk/gc.c#L9546 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) https://github.com/ruby/ruby/blob/trunk/gc.c#L9661 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) https://github.com/ruby/ruby/blob/trunk/gc.c#L9723 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); Index: parse.y =================================================================== --- parse.y (revision 62543) +++ parse.y (revision 62544) @@ -6069,6 +6069,13 @@ heredoc_dedent(struct parser_params *p, https://github.com/ruby/ruby/blob/trunk/parse.y#L6069 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) https://github.com/ruby/ruby/blob/trunk/parse.y#L11316 } #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) { Index: process.c =================================================================== --- process.c (revision 62543) +++ process.c (revision 62544) @@ -394,6 +394,12 @@ parent_redirect_close(int fd) https://github.com/ruby/ruby/blob/trunk/process.c#L394 #endif /* + * Document-module: Process + * + * Module to handle processes. + */ + +/* * call-seq: * Process.pid -> integer * @@ -7974,6 +7980,7 @@ InitVM_process(void) https://github.com/ruby/ruby/blob/trunk/process.c#L7980 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); Index: hash.c =================================================================== --- hash.c (revision 62543) +++ hash.c (revision 62544) @@ -3186,6 +3186,19 @@ hash_proc_call(VALUE key, VALUE hash, in https://github.com/ruby/ruby/blob/trunk/hash.c#L3186 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) { Index: error.c =================================================================== --- error.c (revision 62543) +++ error.c (revision 62544) @@ -1652,6 +1652,13 @@ nometh_err_args(VALUE self) https://github.com/ruby/ruby/blob/trunk/error.c#L1652 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) { Index: vm.c =================================================================== --- vm.c (revision 62543) +++ vm.c (revision 62544) @@ -2767,6 +2767,7 @@ core_hash_merge_kwd(int argc, VALUE *arg https://github.com/ruby/ruby/blob/trunk/vm.c#L2767 return hash; } +/* Returns true if JIT is enabled */ static VALUE mjit_enabled_p(void) { Index: file.c =================================================================== --- file.c (revision 62543) +++ file.c (revision 62544) @@ -6250,6 +6250,7 @@ Init_File(void) https://github.com/ruby/ruby/blob/trunk/file.c#L6250 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); Index: random.c =================================================================== --- random.c (revision 62543) +++ random.c (revision 62544) @@ -1378,6 +1378,16 @@ rand_random(int argc, VALUE *argv, VALUE https://github.com/ruby/ruby/blob/trunk/random.c#L1378 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) https://github.com/ruby/ruby/blob/trunk/random.c#L1654 { /* 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) https://github.com/ruby/ruby/blob/trunk/random.c#L1668 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); Index: transcode.c =================================================================== --- transcode.c (revision 62543) +++ transcode.c (revision 62544) @@ -2905,6 +2905,11 @@ encoded_dup(VALUE newstr, VALUE str, int https://github.com/ruby/ruby/blob/trunk/transcode.c#L2905 return str_encode_associate(newstr, encidx); } +/* + * Document-class: Encoding::Converter + * + * Encoding conversion class. + */ static void econv_free(void *ptr) { -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/