From 96db72ce38b27799dd8e80ca00696e41234db6ba Mon Sep 17 00:00:00 2001 From: nobu Date: Fri, 23 Feb 2018 02:18:52 +0000 Subject: [DOC] missing docs at toplevel git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@62544 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- dir.c | 31 +++++++++++++++++++++++++++++++ error.c | 7 +++++++ file.c | 1 + gc.c | 19 ++++++++++++++++++- hash.c | 13 +++++++++++++ io.c | 8 ++++++++ parse.y | 13 +++++++++++++ process.c | 7 +++++++ random.c | 13 +++++++++++++ thread.c | 13 +++++++++++++ thread_sync.c | 16 ++++++++++++++++ transcode.c | 5 +++++ vm.c | 1 + 13 files changed, 146 insertions(+), 1 deletion(-) diff --git a/dir.c b/dir.c index 71eb93516f..8ac8ee9a89 100644 --- a/dir.c +++ b/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}" } + * + * produces: + * + * 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) { diff --git a/error.c b/error.c index 0f60f491ec..0a992b2701 100644 --- a/error.c +++ b/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) { diff --git a/file.c b/file.c index 980d2af461..9c777ca2b7 100644 --- a/file.c +++ b/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); diff --git a/gc.c b/gc.c index af7c2a202d..c345f2113f 100644 --- a/gc.c +++ b/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); diff --git a/hash.c b/hash.c index 85c6e8529f..d2ca057e33 100644 --- a/hash.c +++ b/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) { diff --git a/io.c b/io.c index 82c5940538..4e071c93b6 100644 --- a/io.c +++ b/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); diff --git a/parse.y b/parse.y index 0e5d9454ad..5380d93b92 100644 --- a/parse.y +++ b/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) { diff --git a/process.c b/process.c index 70a2eef67f..cbdbe8f8f2 100644 --- a/process.c +++ b/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); diff --git a/random.c b/random.c index b800f1d9a1..88c05fbb20 100644 --- a/random.c +++ b/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); diff --git a/thread.c b/thread.c index 56fd7f9926..27f5e5dabf 100644 --- a/thread.c +++ b/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 KeyError exception; if default 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) { diff --git a/thread_sync.c b/thread_sync.c index f1537b6a90..e4a28ccb5c 100644 --- a/thread_sync.c +++ b/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) { diff --git a/transcode.c b/transcode.c index ff9576d019..375346a30d 100644 --- a/transcode.c +++ b/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) { diff --git a/vm.c b/vm.c index 043d7e15e8..71e465346f 100644 --- a/vm.c +++ b/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) { -- cgit v1.2.3