diff --git a/ast.c b/ast.c index 959529738e..18562f252c 100644 --- a/ast.c +++ b/ast.c @@ -77,10 +77,10 @@ ast_parse_done(rb_ast_t *ast) * call-seq: * RubyVM::AbstractSyntaxTree.parse(string) -> RubyVM::AbstractSyntaxTree::Node * - * Parses the given string into an abstract syntax tree, + * Parses the given _string_ into an abstract syntax tree, * returning the root node of that tree. * - * SyntaxError is raised if the given string is invalid syntax. + * SyntaxError is raised if the given _string_ is invalid syntax. * * RubyVM::AbstractSyntaxTree.parse("x = 1 + 2") * # => # @@ -105,10 +105,10 @@ rb_ast_parse_str(VALUE str) * call-seq: * RubyVM::AbstractSyntaxTree.parse_file(pathname) -> RubyVM::AbstractSyntaxTree::Node * - * Reads the file from pathname, then parses it like ::parse, + * Reads the file from _pathname_, then parses it like ::parse, * returning the root node of the abstract syntax tree. * - * SyntaxError is raised if pathname's contents are not + * SyntaxError is raised if _pathname_'s contents are not * valid Ruby syntax. * * RubyVM::AbstractSyntaxTree.parse_file("my-app/app.rb") @@ -205,7 +205,7 @@ script_lines(VALUE path) * RubyVM::AbstractSyntaxTree.of(proc) -> RubyVM::AbstractSyntaxTree::Node * RubyVM::AbstractSyntaxTree.of(method) -> RubyVM::AbstractSyntaxTree::Node * - * Returns AST nodes of the given proc or method. + * Returns AST nodes of the given _proc_ or _method_. * * RubyVM::AbstractSyntaxTree.of(proc {1 + 2}) * # => # diff --git a/bignum.c b/bignum.c index 2599def7be..212d19abdf 100644 --- a/bignum.c +++ b/bignum.c @@ -5500,8 +5500,8 @@ rb_big_le(VALUE x, VALUE y) * big == obj -> true or false * * Returns true only if obj has the same value - * as big. Contrast this with Integer#eql?, which - * requires obj to be a Integer. + * as big. Contrast this with Integer#eql?, which requires + * obj to be a Integer. * * 68719476736 == 68719476736.0 #=> true */ diff --git a/compar.c b/compar.c index 02529c9960..dbd4bce96d 100644 --- a/compar.c +++ b/compar.c @@ -207,16 +207,16 @@ cmp_clamp(VALUE x, VALUE min, VALUE max) } /* - * The Comparable mixin is used by classes whose objects - * may be ordered. The class must define the <=> operator, - * which compares the receiver against another object, returning -1, 0, - * or +1 depending on whether the receiver is less than, equal to, or - * greater than the other object. If the other object is not comparable - * then the <=> operator should return nil. - * Comparable uses - * <=> to implement the conventional comparison operators - * (<, <=, ==, >=, - * and >) and the method between?. + * The Comparable mixin is used by classes whose objects may be + * ordered. The class must define the <=> operator, + * which compares the receiver against another object, returning -1, + * 0, or +1 depending on whether the receiver is less than, equal to, + * or greater than the other object. If the other object is not + * comparable then the <=> operator should return +nil+. + * Comparable uses <=> to implement the conventional + * comparison operators (<, <=, + * ==, >=, and >) and the + * method between?. * * class SizeMatters * include Comparable diff --git a/cont.c b/cont.c index e05d9ee47b..5831a77657 100644 --- a/cont.c +++ b/cont.c @@ -1135,7 +1135,7 @@ cont_restore_0(rb_context_t *cont, VALUE *addr_in_prev_frame) * Continuation objects are generated by Kernel#callcc, * after having +require+d continuation. They hold * a return address and execution context, allowing a nonlocal return - * to the end of the callcc block from anywhere within a + * to the end of the #callcc block from anywhere within a * program. Continuations are somewhat analogous to a structured * version of C's setjmp/longjmp (although they contain * more state, so you might consider them closer to threads). @@ -1320,11 +1320,10 @@ rollback_ensure_stack(VALUE self,rb_ensure_list_t *current,rb_ensure_entry_t *ta * cont.call(args, ...) * cont[args, ...] * - * Invokes the continuation. The program continues from the end of the - * callcc block. If no arguments are given, the original - * callcc returns nil. If one argument is - * given, callcc returns it. Otherwise, an array - * containing args is returned. + * Invokes the continuation. The program continues from the end of + * the #callcc block. If no arguments are given, the original #callcc + * returns +nil+. If one argument is given, #callcc returns + * it. Otherwise, an array containing args is returned. * * callcc {|cont| cont.call } #=> nil * callcc {|cont| cont.call 1 } #=> 1 @@ -1376,10 +1375,10 @@ rb_cont_call(int argc, VALUE *argv, VALUE contval) * manpage to configure the size of the fiber stack(s). * * When a fiber is created it will not run automatically. Rather it must - * be explicitly asked to run using the Fiber#resume method. + * be explicitly asked to run using the Fiber#resume method. * The code running inside the fiber can give up control by calling - * Fiber.yield in which case it yields control back to caller - * (the caller of the Fiber#resume). + * Fiber.yield in which case it yields control back to caller (the + * caller of the Fiber#resume). * * Upon yielding or termination the Fiber returns the value of the last * executed expression @@ -1401,10 +1400,10 @@ rb_cont_call(int argc, VALUE *argv, VALUE contval) * 2 * FiberError: dead fiber called * - * The Fiber#resume method accepts an arbitrary number of - * parameters, if it is the first call to resume then they - * will be passed as block arguments. Otherwise they will be the return - * value of the call to Fiber.yield + * The Fiber#resume method accepts an arbitrary number of parameters, + * if it is the first call to #resume then they will be passed as + * block arguments. Otherwise they will be the return value of the + * call to Fiber.yield * * Example: * @@ -1946,16 +1945,16 @@ rb_fiber_alive_p(VALUE fibval) * call-seq: * fiber.resume(args, ...) -> obj * - * Resumes the fiber from the point at which the last Fiber.yield - * was called, or starts running it if it is the first call to - * resume. Arguments passed to resume will be the value of - * the Fiber.yield expression or will be passed as block - * parameters to the fiber's block if this is the first resume. + * Resumes the fiber from the point at which the last Fiber.yield was + * called, or starts running it if it is the first call to + * #resume. Arguments passed to resume will be the value of the + * Fiber.yield expression or will be passed as block parameters to + * the fiber's block if this is the first #resume. * * Alternatively, when resume is called it evaluates to the arguments passed - * to the next Fiber.yield statement inside the fiber's block + * to the next Fiber.yield statement inside the fiber's block * or to the block value if it runs to completion without any - * Fiber.yield + * Fiber.yield */ static VALUE rb_fiber_m_resume(int argc, VALUE *argv, VALUE fib) @@ -1970,7 +1969,7 @@ rb_fiber_m_resume(int argc, VALUE *argv, VALUE fib) * fiber.raise(exception [, string [, array]]) -> obj * * Raises an exception in the fiber at the point at which the last - * Fiber.yield was called, or at the start if neither +resume+ + * Fiber.yield was called, or at the start if neither +resume+ * nor +raise+ were called before. * * With no arguments, raises a +RuntimeError+. With a single +String+ @@ -1996,7 +1995,7 @@ rb_fiber_raise(int argc, VALUE *argv, VALUE fib) * Transfer control to another fiber, resuming it from where it last * stopped or starting it if it was not resumed before. The calling * fiber will be suspended much like in a call to - * Fiber.yield. You need to require 'fiber' + * Fiber.yield. You need to require 'fiber' * before using this method. * * The fiber which receives the transfer call is treats it much like @@ -2048,9 +2047,9 @@ rb_fiber_m_transfer(int argc, VALUE *argv, VALUE fibval) * * Yields control back to the context that resumed the fiber, passing * along any arguments that were passed to it. The fiber will resume - * processing at this point when resume is called next. - * Any arguments passed to the next resume will be the - * value that this Fiber.yield expression evaluates to. + * processing at this point when #resume is called next. + * Any arguments passed to the next #resume will be the value that + * this Fiber.yield expression evaluates to. */ static VALUE rb_fiber_s_yield(int argc, VALUE *argv, VALUE klass) diff --git a/dir.c b/dir.c index 3348fd59e8..1dbedb763f 100644 --- a/dir.c +++ b/dir.c @@ -592,11 +592,10 @@ dir_initialize(int argc, VALUE *argv, VALUE dir) * The optional encoding keyword argument specifies the encoding of the directory. * If not specified, the filesystem encoding is used. * - * With no block, open is a synonym for - * Dir::new. If a block is present, it is passed - * aDir as a parameter. The directory is closed at the end of - * the block, and Dir::open returns the value of the - * block. + * With no block, open is a synonym for Dir::new. If a + * block is present, it is passed aDir as a parameter. The + * directory is closed at the end of the block, and Dir::open returns + * the value of the block. */ static VALUE dir_s_open(int argc, VALUE *argv, VALUE klass) @@ -870,8 +869,7 @@ dir_each_entry(VALUE dir, VALUE (*each)(VALUE, VALUE), VALUE arg, int children_o * dir.pos -> integer * dir.tell -> integer * - * Returns the current position in dir. See also - * Dir#seek. + * Returns the current position in dir. See also Dir#seek. * * d = Dir.new("testdir") * d.tell #=> 0 @@ -898,7 +896,7 @@ dir_tell(VALUE dir) * dir.seek( integer ) -> dir * * Seeks to a particular location in dir. integer - * must be a value returned by Dir#tell. + * must be a value returned by Dir#tell. * * d = Dir.new("testdir") #=> # * d.read #=> "." @@ -926,8 +924,7 @@ dir_seek(VALUE dir, VALUE pos) * call-seq: * dir.pos = integer -> integer * - * Synonym for Dir#seek, but returns the position - * parameter. + * Synonym for Dir#seek, but returns the position parameter. * * d = Dir.new("testdir") #=> # * d.read #=> "." @@ -1044,8 +1041,8 @@ chdir_restore(struct chdir_data *args) * Changes the current working directory of the process to the given * string. When called without an argument, changes the directory to * the value of the environment variable HOME, or - * LOGDIR. SystemCallError (probably - * Errno::ENOENT) if the target directory does not exist. + * LOGDIR. SystemCallError (probably Errno::ENOENT) if + * the target directory does not exist. * * If a block is given, it is passed the name of the new current * directory, and the block is executed with that as the current @@ -1242,11 +1239,10 @@ nogvl_mkdir(void *ptr) * * Makes a new directory named by string, with permissions * specified by the optional parameter anInteger. The - * permissions may be modified by the value of - * File::umask, and are ignored on NT. Raises a - * SystemCallError if the directory cannot be created. See - * also the discussion of permissions in the class documentation for - * File. + * permissions may be modified by the value of File::umask, and are + * ignored on NT. Raises a SystemCallError if the directory cannot be + * created. See also the discussion of permissions in the class + * documentation for File. * * Dir.mkdir(File.join(Dir.home, ".foo"), 0700) #=> 0 * @@ -1288,8 +1284,8 @@ nogvl_rmdir(void *ptr) * Dir.rmdir( string ) -> 0 * Dir.unlink( string ) -> 0 * - * Deletes the named directory. Raises a subclass of - * SystemCallError if the directory isn't empty. + * Deletes the named directory. Raises a subclass of SystemCallError + * if the directory isn't empty. */ static VALUE dir_s_rmdir(VALUE obj, VALUE dir) @@ -2974,8 +2970,8 @@ dir_collect(VALUE dir) * Dir.entries( dirname, encoding: enc ) -> array * * Returns an array containing all of the filenames in the given - * directory. Will raise a SystemCallError if the named - * directory doesn't exist. + * directory. Will raise a SystemCallError if the named directory + * doesn't exist. * * The optional encoding keyword argument specifies the encoding of the * directory. If not specified, the filesystem encoding is used. @@ -3082,8 +3078,8 @@ dir_collect_children(VALUE dir) * Dir.children( dirname, encoding: enc ) -> array * * Returns an array containing all of the filenames except for "." - * and ".." in the given directory. Will raise a - * SystemCallError if the named directory doesn't exist. + * and ".." in the given directory. Will raise a SystemCallError if + * the named directory doesn't exist. * * The optional encoding keyword argument specifies the encoding of the * directory. If not specified, the filesystem encoding is used. @@ -3390,10 +3386,9 @@ rb_dir_s_empty_p(VALUE obj, VALUE dirname) } /* - * Objects of class Dir are directory streams representing - * directories in the underlying file system. They provide a variety of - * ways to list directories and their contents. See also - * File. + * Objects of class Dir are directory streams representing + * directories in the underlying file system. They provide a variety + * of ways to list directories and their contents. See also File. * * The directory used in these examples contains the two regular files * (config.h and main.rb), the parent diff --git a/encoding.c b/encoding.c index 10a0ab0371..f4606eeb14 100644 --- a/encoding.c +++ b/encoding.c @@ -1756,11 +1756,11 @@ rb_enc_aliases(VALUE klass) * "some string".encode "ISO-8859-1" * #=> "some string" * - * Encoding::ASCII_8BIT is a special encoding that is usually - * used for a byte string, not a character string. But as the name insists, - * its characters in the range of ASCII are considered as ASCII characters. - * This is useful when you use ASCII-8BIT characters with other ASCII - * compatible characters. + * Encoding::ASCII_8BIT is a special encoding that is usually used for + * a byte string, not a character string. But as the name insists, its + * characters in the range of ASCII are considered as ASCII + * characters. This is useful when you use ASCII-8BIT characters with + * other ASCII compatible characters. * * == Changing an encoding * @@ -1798,11 +1798,12 @@ rb_enc_aliases(VALUE klass) * All Ruby script code has an associated Encoding which any String literal * created in the source code will be associated to. * - * The default script encoding is Encoding::UTF-8 after v2.0, but it can - * be changed by a magic comment on the first line of the source code file (or - * second line, if there is a shebang line on the first). The comment must - * contain the word coding or encoding, followed - * by a colon, space and the Encoding name or alias: + * The default script encoding is Encoding::UTF_8 after v2.0, but it + * can be changed by a magic comment on the first line of the source + * code file (or second line, if there is a shebang line on the + * first). The comment must contain the word coding or + * encoding, followed by a colon, space and the Encoding + * name or alias: * * # encoding: UTF-8 * diff --git a/enum.c b/enum.c index d3df6e5b94..c25b17f383 100644 --- a/enum.c +++ b/enum.c @@ -1123,10 +1123,10 @@ sort_by_cmp(const void *ap, const void *bp, void *data) * %w{apple pear fig}.sort_by { |word| word.length } * #=> ["fig", "pear", "apple"] * - * The current implementation of sort_by generates an - * array of tuples containing the original collection element and the - * mapped value. This makes sort_by fairly expensive when - * the keysets are simple. + * The current implementation of #sort_by generates an array of + * tuples containing the original collection element and the mapped + * value. This makes #sort_by fairly expensive when the keysets are + * simple. * * require 'benchmark' * @@ -1145,15 +1145,15 @@ sort_by_cmp(const void *ap, const void *bp, void *data) * * However, consider the case where comparing the keys is a non-trivial * operation. The following code sorts some files on modification time - * using the basic sort method. + * using the basic #sort method. * * files = Dir["*"] * sorted = files.sort { |a, b| File.new(a).mtime <=> File.new(b).mtime } * sorted #=> ["mon", "tues", "wed", "thurs"] * - * This sort is inefficient: it generates two new File + * This sort is inefficient: it generates two new File * objects during every comparison. A slightly better technique is to - * use the Kernel#test method to generate the modification + * use the Kernel#test method to generate the modification * times directly. * * files = Dir["*"] @@ -1162,20 +1162,20 @@ sort_by_cmp(const void *ap, const void *bp, void *data) * } * sorted #=> ["mon", "tues", "wed", "thurs"] * - * This still generates many unnecessary Time objects. A - * more efficient technique is to cache the sort keys (modification - * times in this case) before the sort. Perl users often call this - * approach a Schwartzian transform, after Randal Schwartz. We - * construct a temporary array, where each element is an array - * containing our sort key along with the filename. We sort this array, - * and then extract the filename from the result. + * This still generates many unnecessary Time objects. A more + * efficient technique is to cache the sort keys (modification times + * in this case) before the sort. Perl users often call this approach + * a Schwartzian transform, after Randal Schwartz. We construct a + * temporary array, where each element is an array containing our + * sort key along with the filename. We sort this array, and then + * extract the filename from the result. * * sorted = Dir["*"].collect { |f| * [test(?M, f), f] * }.sort.collect { |f| f[1] } * sorted #=> ["mon", "tues", "wed", "thurs"] * - * This is exactly what sort_by does internally. + * This is exactly what #sort_by does internally. * * sorted = Dir["*"].sort_by { |f| test(?M, f) } * sorted #=> ["mon", "tues", "wed", "thurs"] @@ -1716,7 +1716,7 @@ min_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, args)) * enum.min(n) { |a, b| block } -> array * * Returns the object in _enum_ with the minimum value. The - * first form assumes all objects implement Comparable; + * first form assumes all objects implement Comparable; * the second uses the block to return a <=> b. * * a = %w(albatross dog horse) @@ -1808,7 +1808,7 @@ max_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, args)) * enum.max(n) { |a, b| block } -> array * * Returns the object in _enum_ with the maximum value. The - * first form assumes all objects implement Comparable; + * first form assumes all objects implement Comparable; * the second uses the block to return a <=> b. * * a = %w(albatross dog horse) @@ -1967,7 +1967,7 @@ minmax_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, _memo)) * * Returns a two element array which contains the minimum and the * maximum value in the enumerable. The first form assumes all - * objects implement Comparable; the second uses the + * objects implement Comparable; the second uses the * block to return a <=> b. * * a = %w(albatross dog horse) @@ -4070,14 +4070,13 @@ enum_uniq(VALUE obj) } /* - * The Enumerable mixin provides collection classes with - * several traversal and searching methods, and with the ability to - * sort. The class must provide a method each, which - * yields successive members of the collection. If - * Enumerable#max, #min, or - * #sort is used, the objects in the collection must also - * implement a meaningful <=> operator, as these methods - * rely on an ordering between members of the collection. + * The Enumerable mixin provides collection classes with several + * traversal and searching methods, and with the ability to sort. The + * class must provide a method #each, which yields + * successive members of the collection. If Enumerable#max, #min, or + * #sort is used, the objects in the collection must also implement a + * meaningful <=> operator, as these methods rely on an + * ordering between members of the collection. */ void diff --git a/error.c b/error.c index 3b8bdce46b..e61a3844cf 100644 --- a/error.c +++ b/error.c @@ -155,7 +155,7 @@ rb_warning_s_warn(VALUE mod, VALUE str) * Document-module: Warning * * The Warning module contains a single method named #warn, and the - * module extends itself, making Warning.warn available. + * module extends itself, making Warning.warn available. * Warning.warn is called for all warnings issued by Ruby. * By default, warnings are printed to $stderr. * @@ -306,7 +306,7 @@ warning_write(int argc, VALUE *argv, VALUE buf) * -W0 flag), does nothing. Otherwise, * converts each of the messages to strings, appends a newline * character to the string if the string does not end in a newline, - * and calls Warning.warn with the string. + * and calls Warning.warn with the string. * * warn("warning 1", "warning 2") * @@ -1266,7 +1266,7 @@ try_convert_to_exception(VALUE obj) * call-seq: * exc == obj -> true or false * - * Equality---If obj is not an Exception, returns + * Equality---If obj is not an Exception, returns * false. Otherwise, returns true if exc and * obj share same class, messages, and backtrace. */ @@ -1442,7 +1442,7 @@ name_err_init_attr(VALUE exc, VALUE recv, VALUE method) * NameError.new(msg=nil, name=nil, receiver: nil) -> name_error * * Construct a new NameError exception. If given the name - * parameter may subsequently be examined using the NameError#name + * parameter may subsequently be examined using the NameError#name * method. receiver parameter allows to pass object in * context of which the error happened. Example: * @@ -1852,19 +1852,18 @@ syntax_error_initialize(int argc, VALUE *argv, VALUE self) /* * Document-module: Errno * - * Ruby exception objects are subclasses of Exception. - * However, operating systems typically report errors using plain - * integers. Module Errno is created dynamically to map - * these operating system errors to Ruby classes, with each error - * number generating its own subclass of SystemCallError. - * As the subclass is created in module Errno, its name - * will start Errno::. + * Ruby exception objects are subclasses of Exception. However, + * operating systems typically report errors using plain + * integers. Module Errno is created dynamically to map these + * operating system errors to Ruby classes, with each error number + * generating its own subclass of SystemCallError. As the subclass + * is created in module Errno, its name will start + * Errno::. * - * The names of the Errno:: classes depend on - * the environment in which Ruby runs. On a typical Unix or Windows - * platform, there are Errno classes such as - * Errno::EACCES, Errno::EAGAIN, - * Errno::EINTR, and so on. + * The names of the Errno:: classes depend on the + * environment in which Ruby runs. On a typical Unix or Windows + * platform, there are Errno classes such as Errno::EACCES, + * Errno::EAGAIN, Errno::EINTR, and so on. * * The integer operating system error number corresponding to a * particular error is available as the class constant @@ -1875,7 +1874,7 @@ syntax_error_initialize(int argc, VALUE *argv, VALUE self) * Errno::EINTR::Errno #=> 4 * * The full list of operating system errors on your particular platform - * are available as the constants of Errno. + * are available as the constants of Errno. * * Errno.constants #=> :E2BIG, :EACCES, :EADDRINUSE, :EADDRNOTAVAIL, ... */ @@ -1934,11 +1933,10 @@ get_syserr(int n) * call-seq: * SystemCallError.new(msg, errno) -> system_call_error_subclass * - * If _errno_ corresponds to a known system error code, constructs - * the appropriate Errno class for that error, otherwise - * constructs a generic SystemCallError object. The - * error number is subsequently available via the errno - * method. + * If _errno_ corresponds to a known system error code, constructs the + * appropriate Errno class for that error, otherwise constructs a + * generic SystemCallError object. The error number is subsequently + * available via the #errno method. */ static VALUE diff --git a/eval.c b/eval.c index 1b4b9b1bea..59b3b30293 100644 --- a/eval.c +++ b/eval.c @@ -714,7 +714,7 @@ extract_raise_opts(int argc, const VALUE *argv, VALUE *opts) * fail(exception [, string [, array]], cause: $!) * * With no arguments, raises the exception in $! or raises - * a RuntimeError if $! is +nil+. + * a RuntimeError if $! is +nil+. * With a single +String+ argument, raises a * +RuntimeError+ with the string as a message. Otherwise, * the first parameter should be the name of an +Exception+ @@ -1200,11 +1200,11 @@ rb_frame_last_func(void) * append_features(mod) -> mod * * When this module is included in another, Ruby calls - * append_features in this module, passing it the - * receiving module in _mod_. Ruby's default implementation is - * to add the constants, methods, and module variables of this module - * to _mod_ if this module has not already been added to - * _mod_ or one of its ancestors. See also Module#include. + * #append_features in this module, passing it the receiving module + * in _mod_. Ruby's default implementation is to add the constants, + * methods, and module variables of this module to _mod_ if this + * module has not already been added to _mod_ or one of its + * ancestors. See also Module#include. */ static VALUE @@ -1222,7 +1222,7 @@ rb_mod_append_features(VALUE module, VALUE include) * call-seq: * include(module, ...) -> self * - * Invokes Module.append_features on each parameter in reverse order. + * Invokes Module.append_features on each parameter in reverse order. */ static VALUE @@ -1249,11 +1249,11 @@ rb_mod_include(int argc, VALUE *argv, VALUE module) * prepend_features(mod) -> mod * * When this module is prepended in another, Ruby calls - * prepend_features in this module, passing it the - * receiving module in _mod_. Ruby's default implementation is - * to overlay the constants, methods, and module variables of this module - * to _mod_ if this module has not already been added to - * _mod_ or one of its ancestors. See also Module#prepend. + * #prepend_features in this module, passing it the receiving module + * in _mod_. Ruby's default implementation is to overlay the + * constants, methods, and module variables of this module to _mod_ + * if this module has not already been added to _mod_ or one of its + * ancestors. See also Module#prepend. */ static VALUE @@ -1271,7 +1271,7 @@ rb_mod_prepend_features(VALUE module, VALUE prepend) * call-seq: * prepend(module, ...) -> self * - * Invokes Module.prepend_features on each parameter in reverse order. + * Invokes Module.prepend_features on each parameter in reverse order. */ static VALUE @@ -1646,7 +1646,7 @@ rb_extend_object(VALUE obj, VALUE module) * * Extends the specified object by adding this module's constants and * methods (which are added as singleton methods). This is the callback - * method used by Object#extend. + * method used by Object#extend. * * module Picky * def Picky.extend_object(o) @@ -1722,9 +1722,9 @@ rb_obj_extend(int argc, VALUE *argv, VALUE obj) * call-seq: * include(module, ...) -> self * - * Invokes Module.append_features - * on each parameter in turn. Effectively adds the methods and constants - * in each module to the receiver. + * Invokes Module.append_features on each parameter in turn. + * Effectively adds the methods and constants in each module to the + * receiver. */ static VALUE @@ -1744,7 +1744,7 @@ top_include(int argc, VALUE *argv, VALUE self) * using(module) -> self * * Import class refinements from module into the scope where - * using is called. + * #using is called. */ static VALUE diff --git a/file.c b/file.c index fd68d41081..36389f5978 100644 --- a/file.c +++ b/file.c @@ -431,8 +431,8 @@ apply2files(int (*func)(const char *, void *), int argc, VALUE *argv, void *arg) * For instance, the pathname becomes void when the file has been * moved or deleted. * - * This method raises IOError for a file created using - * File::Constants::TMPFILE because they don't have a pathname. + * This method raises IOError for a file created using + * File::Constants::TMPFILE because they don't have a pathname. * * File.new("testfile").path #=> "testfile" * File.new("/tmp/../tmp/xxx", "w").path #=> "/tmp/../tmp/xxx" @@ -912,7 +912,7 @@ typedef struct stat statx_data; * stat.atime -> time * * Returns the last access time for this file as an object of class - * Time. + * Time. * * File.stat("testfile").atime #=> Wed Dec 31 18:00:00 CST 1969 * @@ -1248,8 +1248,7 @@ rb_stat(VALUE file, struct stat *st) * call-seq: * File.stat(file_name) -> stat * - * Returns a File::Stat object for the named file (see - * File::Stat). + * Returns a File::Stat object for the named file (see File::Stat). * * File.stat("testfile").mtime #=> Tue Apr 08 12:58:04 CDT 2003 * @@ -1273,7 +1272,7 @@ rb_file_s_stat(VALUE klass, VALUE fname) * ios.stat -> stat * * Returns status information for ios as an object of type - * File::Stat. + * File::Stat. * * f = File.new("testfile") * s = f.stat @@ -1321,8 +1320,8 @@ lstat_without_gvl(const char *path, struct stat *st) * call-seq: * File.lstat(file_name) -> stat * - * Same as File::stat, but does not follow the last symbolic - * link. Instead, reports on the link itself. + * Same as File::stat, but does not follow the last symbolic link. + * Instead, reports on the link itself. * * File.symlink("testfile", "link2test") #=> 0 * File.stat("testfile").size #=> 66 @@ -1352,8 +1351,8 @@ rb_file_s_lstat(VALUE klass, VALUE fname) * call-seq: * file.lstat -> stat * - * Same as IO#stat, but does not follow the last symbolic - * link. Instead, reports on the link itself. + * Same as IO#stat, but does not follow the last symbolic link. + * Instead, reports on the link itself. * * File.symlink("testfile", "link2test") #=> 0 * File.stat("testfile").size #=> 66 @@ -1533,10 +1532,10 @@ rb_access(VALUE fname, int mode) /* * Document-class: FileTest * - * FileTest implements file test operations similar to - * those used in File::Stat. It exists as a standalone - * module, and its methods are also insinuated into the File - * class. (Note that this is not done by inclusion: the interpreter cheats). + * FileTest implements file test operations similar to those used in + * File::Stat. It exists as a standalone module, and its methods are + * also insinuated into the File class. (Note that this is not done + * by inclusion: the interpreter cheats). * */ @@ -2266,8 +2265,8 @@ rb_file_s_atime(VALUE klass, VALUE fname) * call-seq: * file.atime -> time * - * Returns the last access time (a Time object) - * for file, or epoch if file has not been accessed. + * Returns the last access time (a Time object) for file, or + * epoch if file has not been accessed. * * File.new("testfile").atime #=> Wed Dec 31 18:00:00 CST 1969 * @@ -2512,7 +2511,7 @@ rb_file_s_chmod(int argc, VALUE *argv) * Changes permission bits on file to the bit pattern * represented by mode_int. Actual effects are platform * dependent; on Unix systems, see chmod(2) for details. - * Follows symbolic links. Also see File#lchmod. + * Follows symbolic links. Also see File#lchmod. * * f = File.new("out", "w"); * f.chmod(0644) #=> 0 @@ -2560,9 +2559,9 @@ lchmod_internal(const char *path, void *mode) * call-seq: * File.lchmod(mode_int, file_name, ...) -> integer * - * Equivalent to File::chmod, but does not follow symbolic - * links (so it will change the permissions associated with the link, - * not the file referenced by the link). Often not available. + * Equivalent to File::chmod, but does not follow symbolic links (so + * it will change the permissions associated with the link, not the + * file referenced by the link). Often not available. * */ @@ -2646,7 +2645,7 @@ rb_file_s_chown(int argc, VALUE *argv) * change the owner of a file. The current owner of a file may change * the file's group to any group to which the owner belongs. A * nil or -1 owner or group id is ignored. Follows - * symbolic links. See also File#lchown. + * symbolic links. See also File#lchown. * * File.new("testfile").chown(502, 1000) * @@ -2690,7 +2689,7 @@ lchown_internal(const char *path, void *arg) * call-seq: * File.lchown(owner_int, group_int, file_name,..) -> integer * - * Equivalent to File::chown, but does not follow symbolic + * Equivalent to File::chown, but does not follow symbolic * links (so it will change the owner associated with the link, not the * file referenced by the link). Often not available. Returns number * of files in the argument list. @@ -2942,7 +2941,7 @@ syserr_fail2_in(const char *func, int e, VALUE s1, VALUE s2) * * Creates a new name for an existing file using a hard link. Will not * overwrite new_name if it already exists (raising a subclass - * of SystemCallError). Not available on all platforms. + * of SystemCallError). Not available on all platforms. * * File.link("testfile", ".testfile") #=> 0 * IO.readlines(".testfile")[0] #=> "This is line one\n" @@ -2971,7 +2970,7 @@ rb_file_s_link(VALUE klass, VALUE from, VALUE to) * File.symlink(old_name, new_name) -> 0 * * Creates a symbolic link called new_name for the existing file - * old_name. Raises a NotImplemented exception on + * old_name. Raises a NotImplemented exception on * platforms that do not support symbolic links. * * File.symlink("testfile", "link2test") #=> 0 @@ -3091,9 +3090,9 @@ unlink_internal(const char *path, void *arg) * unlink(2) system call, the type of * exception raised depends on its error type (see * https://linux.die.net/man/2/unlink) and has the form of - * e.g. Errno::ENOENT. + * e.g. Errno::ENOENT. * - * See also Dir::rmdir. + * See also Dir::rmdir. */ static VALUE @@ -3119,8 +3118,8 @@ no_gvl_rename(void *ptr) * call-seq: * File.rename(old_name, new_name) -> 0 * - * Renames the given file to the new name. Raises a - * SystemCallError if the file cannot be renamed. + * Renames the given file to the new name. Raises a SystemCallError + * if the file cannot be renamed. * * File.rename("afile", "afile.bak") #=> 0 */ @@ -4429,12 +4428,11 @@ ruby_enc_find_basename(const char *name, long *baselen, long *alllen, rb_encodin * * Returns the last component of the filename given in * file_name (after first stripping trailing separators), - * which can be formed using both File::SEPARATOR and - * File::ALT_SEPARATOR as the separator when - * File::ALT_SEPARATOR is not nil. If - * suffix is given and present at the end of file_name, - * it is removed. If suffix is ".*", any extension will be - * removed. + * which can be formed using both File::SEPARATOR and + * File::ALT_SEPARATOR as the separator when File::ALT_SEPARATOR is + * not nil. If suffix is given and present at the + * end of file_name, it is removed. If suffix is ".*", + * any extension will be removed. * * File.basename("/home/gumby/work/ruby.rb") #=> "ruby.rb" * File.basename("/home/gumby/work/ruby.rb", ".rb") #=> "ruby" @@ -4492,9 +4490,9 @@ rb_file_s_basename(int argc, VALUE *argv) * * Returns all components of the filename given in file_name * except the last one (after first stripping trailing separators). - * The filename can be formed using both File::SEPARATOR - * and File::ALT_SEPARATOR as the separator when - * File::ALT_SEPARATOR is not nil. + * The filename can be formed using both File::SEPARATOR and + * File::ALT_SEPARATOR as the separator when File::ALT_SEPARATOR is + * not nil. * * File.dirname("/home/gumby/work/ruby.rb") #=> "/home/gumby/work" */ @@ -4676,8 +4674,8 @@ rb_file_s_path(VALUE klass, VALUE fname) * File.split(file_name) -> array * * Splits the given string into a directory and a file component and - * returns them in a two-element array. See also - * File::dirname and File::basename. + * returns them in a two-element array. See also File::dirname and + * File::basename. * * File.split("/home/gumby/.profile") #=> ["/home/gumby", ".profile"] */ @@ -4957,9 +4955,9 @@ rb_thread_flock(void *data) * * Locks or unlocks a file according to locking_constant (a * logical or of the values in the table below). - * Returns false if File::LOCK_NB is - * specified and the operation would otherwise have blocked. Not - * available on all platforms. + * Returns false if File::LOCK_NB is specified and the + * operation would otherwise have blocked. Not available on all + * platforms. * * Locking constants (in class File): * @@ -5260,15 +5258,13 @@ rb_f_test(int argc, VALUE *argv) /* * Document-class: File::Stat * - * Objects of class File::Stat encapsulate common status - * information for File objects. The information is - * recorded at the moment the File::Stat object is - * created; changes made to the file after that point will not be - * reflected. File::Stat objects are returned by - * IO#stat, File::stat, - * File#lstat, and File::lstat. Many of these + * Objects of class File::Stat encapsulate common status information + * for File objects. The information is recorded at the moment the + * File::Stat object is created; changes made to the file after that + * point will not be reflected. File::Stat objects are returned by + * IO#stat, File::stat, File#lstat, and File::lstat. Many of these * methods return platform-specific values, and not all values are - * meaningful on all systems. See also Kernel#test. + * meaningful on all systems. See also Kernel#test. */ static VALUE @@ -5389,10 +5385,9 @@ rb_stat_p(VALUE obj) * * Returns true if stat is a symbolic link, * false if it isn't or if the operating system doesn't - * support this feature. As File::stat automatically - * follows symbolic links, symlink? will always be - * false for an object returned by - * File::stat. + * support this feature. As File::stat automatically follows symbolic + * links, #symlink? will always be false for an object + * returned by File::stat. * * File.symlink("testfile", "alink") #=> 0 * File.stat("alink").symlink? #=> false @@ -6283,11 +6278,10 @@ const char ruby_null_device[] = ; /* - * A File is an abstraction of any file object accessible - * by the program and is closely associated with class IO. - * File includes the methods of module - * FileTest as class methods, allowing you to write (for - * example) File.exist?("foo"). + * A File is an abstraction of any file object accessible by the + * program and is closely associated with class IO. File includes + * the methods of module FileTest as class methods, allowing you to + * write (for example) File.exist?("foo"). * * In the description of File methods, * permission bits are a platform-specific diff --git a/gc.c b/gc.c index 1331ef21dc..e84cb80b99 100644 --- a/gc.c +++ b/gc.c @@ -2692,9 +2692,9 @@ os_obj_of(VALUE of) * module. Returns the number of objects found. Immediate * objects (Fixnums, Symbols * true, false, and nil) are - * never returned. In the example below, each_object - * returns both the numbers we defined and several constants defined in - * the Math module. + * never returned. In the example below, #each_object returns both + * the numbers we defined and several constants defined in the Math + * module. * * If no block is given, an enumerator is returned instead. * diff --git a/hash.c b/hash.c index a57f627ebc..658a105177 100644 --- a/hash.c +++ b/hash.c @@ -1703,9 +1703,9 @@ rb_hash_rehash_i(VALUE key, VALUE value, VALUE arg) * * Rebuilds the hash based on the current hash values for each key. If * values of key objects have changed since they were inserted, this - * method will reindex hsh. If Hash#rehash is + * method will reindex hsh. If Hash#rehash is * called while an iterator is traversing the hash, a - * RuntimeError will be raised in the iterator. + * RuntimeError will be raised in the iterator. * * a = [ "a", "b" ] * c = [ "c", "d" ] @@ -1788,7 +1788,7 @@ rb_hash_stlike_lookup(VALUE hash, st_data_t key, st_data_t *pval) * * Element Reference---Retrieves the value object corresponding * to the key object. If not found, returns the default value (see - * Hash::new for details). + * Hash::new for details). * * h = { "a" => 100, "b" => 200 } * h["a"] #=> 100 @@ -1835,7 +1835,7 @@ rb_hash_lookup(VALUE hash, VALUE key) * * Returns a value from the hash 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, + * 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. * @@ -1905,7 +1905,7 @@ rb_hash_fetch(VALUE hash, VALUE key) * * Returns the default value, the value that would be returned by * hsh[key] if key did not exist in hsh. - * See also Hash::new and Hash#default=. + * See also Hash::new and Hash#default=. * * h = Hash.new #=> {} * h.default #=> nil @@ -1942,7 +1942,7 @@ rb_hash_default(int argc, VALUE *argv, VALUE hash) * * Sets the default value, the value returned for a key that does not * exist in the hash. It is not possible to set the default to a - * Proc that will be executed on each key lookup. + * Proc that will be executed on each key lookup. * * h = { "a" => 100, "b" => 200 } * h.default = "Go fish" @@ -1968,7 +1968,7 @@ rb_hash_set_default(VALUE hash, VALUE ifnone) * call-seq: * hsh.default_proc -> anObject * - * If Hash::new was invoked with a block, return that + * If Hash::new was invoked with a block, return that * block, otherwise return nil. * * h = Hash.new {|h,k| h[k] = k*k } #=> {} @@ -2268,7 +2268,7 @@ rb_hash_delete_if(VALUE hash) * hsh.reject! {| key, value | block } -> hsh or nil * hsh.reject! -> an_enumerator * - * Equivalent to Hash#delete_if, but returns + * Equivalent to Hash#delete_if, but returns * nil if no changes were made. */ @@ -2365,7 +2365,7 @@ rb_hash_slice(int argc, VALUE *argv, VALUE hash) * hsh.values_at(key, ...) -> array * * Return an array containing the values associated with the given keys. - * Also see Hash.select. + * Also see Hash.select. * * h = { "cat" => "feline", "dog" => "canine", "cow" => "bovine" } * h.values_at("cow", "cat") #=> ["bovine", "feline"] @@ -2389,8 +2389,8 @@ rb_hash_values_at(int argc, VALUE *argv, VALUE hash) * hsh.fetch_values(key, ...) { |key| block } -> array * * Returns an array containing the values associated with the given keys - * but also raises KeyError when one of keys can't be found. - * Also see Hash#values_at and Hash#fetch. + * but also raises KeyError when one of keys can't be found. + * Also see Hash#values_at and Hash#fetch. * * h = { "cat" => "feline", "dog" => "canine", "cow" => "bovine" } * @@ -3188,7 +3188,7 @@ keys_i(VALUE key, VALUE value, VALUE ary) * hsh.keys -> array * * Returns a new array populated with the keys from this hash. See also - * Hash#values. + * Hash#values. * * h = { "a" => 100, "b" => 200, "c" => 300, "d" => 400 } * h.keys #=> ["a", "b", "c", "d"] @@ -3235,7 +3235,7 @@ values_i(VALUE key, VALUE value, VALUE ary) * hsh.values -> array * * Returns a new array populated with the values from hsh. See - * also Hash#keys. + * also Hash#keys. * * h = { "a" => 100, "b" => 200, "c" => 300 } * h.values #=> [100, 200, 300] @@ -3287,7 +3287,7 @@ rb_hash_values(VALUE hash) * h.has_key?("a") #=> true * h.has_key?("z") #=> false * - * Note that include? and member? do not test member + * Note that #include? and #member? do not test member * equality using == as do other Enumerables. * * See also Enumerable#include? @@ -3427,8 +3427,7 @@ hash_equal(VALUE hash1, VALUE hash2, int eql) * * Equality---Two hashes are equal if they each contain the same number * of keys and if each key-value pair is equal to (according to - * Object#==) the corresponding elements in the other - * hash. + * Object#==) the corresponding elements in the other hash. * * h1 = { "a" => 1, "c" => 2 } * h2 = { 7 => 35, "c" => 2, "a" => 1 } @@ -3796,7 +3795,7 @@ assoc_i(VALUE key, VALUE val, VALUE arg) * * Searches through the hash comparing _obj_ with the key using ==. * Returns the key-value pair (two elements array) or +nil+ - * if no match is found. See Array#assoc. + * if no match is found. See Array#assoc. * * h = {"colors" => ["red", "blue", "green"], * "letters" => ["a", "b", "c" ]} @@ -3858,7 +3857,7 @@ rassoc_i(VALUE key, VALUE val, VALUE arg) * * Searches through the hash comparing _obj_ with the value using ==. * Returns the first key-value pair (two-element array) that matches. See - * also Array#rassoc. + * also Array#rassoc. * * a = {1=> "one", 2 => "two", 3 => "three", "ii" => "two"} * a.rassoc("two") #=> [2, "two"] @@ -4048,7 +4047,7 @@ rb_hash_compare_by_id(VALUE hash) * hsh.compare_by_identity? -> true or false * * Returns true if hsh will compare its keys by - * their identity. Also see Hash#compare_by_identity. + * their identity. Also see Hash#compare_by_identity. * */ diff --git a/io.c b/io.c index 8cbe34706c..cd83f520af 100644 --- a/io.c +++ b/io.c @@ -2003,7 +2003,7 @@ static void clear_readconv(rb_io_t *fptr); * ios.rewind -> 0 * * Positions ios to the beginning of input, resetting - * lineno to zero. + * #lineno to zero. * * f = File.new("testfile") * f.readline #=> "This is line one\n" @@ -2089,14 +2089,14 @@ io_fillbuf(rb_io_t *fptr) * * Returns true if ios is at end of file that means * there are no more data to read. - * The stream must be opened for reading or an IOError will be + * The stream must be opened for reading or an IOError will be * raised. * * f = File.new("testfile") * dummy = f.readlines * f.eof #=> true * - * If ios is a stream such as pipe or socket, IO#eof? + * If ios is a stream such as pipe or socket, IO#eof? * blocks until the other end sends some data or closes it. * * r, w = IO.pipe @@ -2110,10 +2110,9 @@ io_fillbuf(rb_io_t *fptr) * r, w = IO.pipe * r.eof? # blocks forever * - * Note that IO#eof? reads data to the input byte buffer. - * So IO#sysread may not behave as you intend with - * IO#eof?, unless you call IO#rewind - * first (which is not available for some streams). + * Note that IO#eof? reads data to the input byte buffer. So + * IO#sysread may not behave as you intend with IO#eof?, unless you + * call IO#rewind first (which is not available for some streams). */ VALUE @@ -2145,7 +2144,7 @@ rb_io_eof(VALUE io) * Returns the current ``sync mode'' of ios. When sync mode is * true, all output is immediately flushed to the underlying operating * system and is not buffered by Ruby internally. See also - * IO#fsync. + * IO#fsync. * * f = File.new("testfile") * f.sync #=> false @@ -2170,7 +2169,7 @@ rb_io_sync(VALUE io) * Sets the ``sync mode'' to true or false. * When sync mode is true, all output is immediately flushed to the * underlying operating system and is not buffered internally. Returns - * the new state. See also IO#fsync. + * the new state. See also IO#fsync. * * f = File.new("testfile") * f.sync = true @@ -2197,12 +2196,11 @@ rb_io_set_sync(VALUE io, VALUE sync) * ios.fsync -> 0 or nil * * Immediately writes all buffered data in ios to disk. - * Note that fsync differs from - * using IO#sync=. The latter ensures that data is flushed - * from Ruby's buffers, but does not guarantee that the underlying - * operating system actually writes it to disk. + * Note that #fsync differs from using IO#sync=. The latter ensures + * that data is flushed from Ruby's buffers, but does not guarantee + * that the underlying operating system actually writes it to disk. * - * NotImplementedError is raised + * NotImplementedError is raised * if the underlying operating system does not support fsync(2). */ @@ -2251,8 +2249,8 @@ nogvl_fdatasync(void *ptr) * Immediately writes all buffered data in ios to disk. * * If the underlying operating system does not support fdatasync(2), - * IO#fsync is called instead (which might raise a - * NotImplementedError). + * IO#fsync is called instead (which might raise a + * NotImplementedError). */ static VALUE @@ -2305,7 +2303,7 @@ rb_io_fileno(VALUE io) * ios.pid -> integer * * Returns the process ID of a child process associated with - * ios. This will be set by IO.popen. + * ios. This will be set by IO.popen. * * pipe = IO.popen("-") * if pipe @@ -2868,7 +2866,7 @@ io_getpartial(int argc, VALUE *argv, VALUE io, VALUE opts, int nonblock) * The _outbuf_ will contain only the received data after the method call * even if it is not empty at the beginning. * - * It raises EOFError on end of file. + * It raises EOFError on end of file. * * readpartial is designed for streams such as pipe, socket, tty, etc. * It blocks only when no data immediately available. @@ -3581,12 +3579,12 @@ rb_io_gets_internal(VALUE io) * sep. A separator of +nil+ reads the entire * contents, and a zero-length separator reads the input a paragraph at * a time (two successive newlines in the input separate paragraphs). - * The stream must be opened for reading or an IOError - * will be raised. The line read in will be returned and also assigned - * to $_. Returns +nil+ if called at end of - * file. If the first argument is an integer, or optional second - * argument is given, the returning string would not be longer than the - * given value in bytes. + * The stream must be opened for reading or an IOError will be raised. + * The line read in will be returned and also assigned to + * $_. Returns +nil+ if called at end of file. If the + * first argument is an integer, or optional second argument is given, + * the returning string would not be longer than the given value in + * bytes. * * File.new("testfile").gets #=> "This is line one\n" * $_ #=> "This is line one\n" @@ -3620,12 +3618,12 @@ rb_io_gets_m(int argc, VALUE *argv, VALUE io) * ios.lineno -> integer * * Returns the current line number in ios. The stream must be - * opened for reading. lineno counts the number of times - * #gets is called rather than the number of newlines encountered. The two - * values will differ if #gets is called with a separator other than newline. + * opened for reading. #lineno counts the number of times #gets is called + * rather than the number of newlines encountered. The two values will + * differ if #gets is called with a separator other than newline. * * Methods that use $/ like #each, #lines and #readline will - * also increment lineno. + * also increment #lineno. * * See also the $. variable. * @@ -3681,8 +3679,7 @@ rb_io_set_lineno(VALUE io, VALUE lineno) * ios.readline(limit [, getline_args]) -> string * ios.readline(sep, limit [, getline_args]) -> string * - * Reads a line as with IO#gets, but raises an - * EOFError on end of file. + * Reads a line as with IO#gets, but raises an EOFError on end of file. */ static VALUE @@ -3711,7 +3708,7 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io); * If the first argument is an integer, or an * optional second argument is given, the returning string would not be * longer than the given value in bytes. The stream must be opened for - * reading or an IOError will be raised. + * reading or an IOError will be raised. * * f = File.new("testfile") * f.readlines[0] #=> "This is line one\n" @@ -3759,7 +3756,7 @@ io_readlines(const struct getline_arg *arg, VALUE io) * * Executes the block for every line in ios, where lines are * separated by sep. ios must be opened for - * reading or an IOError will be raised. + * reading or an IOError will be raised. * * If no block is given, an enumerator is returned instead. * @@ -3793,7 +3790,7 @@ rb_io_each_line(int argc, VALUE *argv, VALUE io) } /* - * This is a deprecated alias for each_line. + * This is a deprecated alias for #each_line. */ static VALUE @@ -3812,7 +3809,7 @@ rb_io_lines(int argc, VALUE *argv, VALUE io) * * Calls the given block once for each byte (0..255) in ios, * passing the byte as an argument. The stream must be opened for - * reading or an IOError will be raised. + * reading or an IOError will be raised. * * If no block is given, an enumerator is returned instead. * @@ -3844,7 +3841,7 @@ rb_io_each_byte(VALUE io) } /* - * This is a deprecated alias for each_byte. + * This is a deprecated alias for #each_byte. */ static VALUE @@ -3970,7 +3967,7 @@ io_getc(rb_io_t *fptr, rb_encoding *enc) * * Calls the given block once for each character in ios, * passing the character as an argument. The stream must be opened for - * reading or an IOError will be raised. + * reading or an IOError will be raised. * * If no block is given, an enumerator is returned instead. * @@ -3998,7 +3995,7 @@ rb_io_each_char(VALUE io) } /* - * This is a deprecated alias for each_char. + * This is a deprecated alias for #each_char. */ static VALUE @@ -4018,9 +4015,9 @@ rb_io_chars(VALUE io) * ios.each_codepoint -> an_enumerator * ios.codepoints -> an_enumerator * - * Passes the Integer ordinal of each character in ios, + * Passes the Integer ordinal of each character in ios, * passing the codepoint as an argument. The stream must be opened for - * reading or an IOError will be raised. + * reading or an IOError will be raised. * * If no block is given, an enumerator is returned instead. * @@ -4126,7 +4123,7 @@ rb_io_each_codepoint(VALUE io) } /* - * This is a deprecated alias for each_codepoint. + * This is a deprecated alias for #each_codepoint. */ static VALUE @@ -4170,7 +4167,7 @@ rb_io_getc(VALUE io) * ios.readchar -> string * * Reads a one-character string from ios. Raises an - * EOFError on end of file. + * EOFError on end of file. * * f = File.new("testfile") * f.readchar #=> "h" @@ -4229,8 +4226,8 @@ rb_io_getbyte(VALUE io) * call-seq: * ios.readbyte -> integer * - * Reads a byte as with IO#getbyte, but raises an - * EOFError on end of file. + * Reads a byte as with IO#getbyte, but raises an EOFError on end of + * file. */ static VALUE @@ -4253,7 +4250,7 @@ rb_io_readbyte(VALUE io) * such that a subsequent buffered read will return it. Only one byte * may be pushed back before a subsequent read operation (that is, * you will be able to read only the last of several bytes that have been pushed - * back). Has no effect with unbuffered reads (such as IO#sysread). + * back). Has no effect with unbuffered reads (such as IO#sysread). * * f = File.new("testfile") #=> # * b = f.getbyte #=> 0x38 @@ -4292,7 +4289,7 @@ rb_io_ungetbyte(VALUE io, VALUE b) * such that a subsequent buffered character read will return it. Only one character * may be pushed back before a subsequent read operation (that is, * you will be able to read only the last of several characters that have been pushed - * back). Has no effect with unbuffered reads (such as IO#sysread). + * back). Has no effect with unbuffered reads (such as IO#sysread). * * f = File.new("testfile") #=> # * c = f.getc #=> "8" @@ -4819,12 +4816,11 @@ rb_io_close(VALUE io) * * Closes ios and flushes any pending writes to the operating * system. The stream is unavailable for any further data operations; - * an IOError is raised if such an attempt is made. I/O - * streams are automatically closed when they are claimed by the - * garbage collector. + * an IOError is raised if such an attempt is made. I/O streams are + * automatically closed when they are claimed by the garbage collector. * - * If ios is opened by IO.popen, - * close sets $?. + * If ios is opened by IO.popen, #close sets + * $?. * * Calling this method on closed IO object is just ignored since Ruby 2.3. */ @@ -4914,7 +4910,7 @@ rb_io_closed(VALUE io) * * Closes the read end of a duplex I/O stream (i.e., one that contains * both a read and a write stream, such as a pipe). Will raise an - * IOError if the stream is not duplexed. + * IOError if the stream is not duplexed. * * f = IO.popen("/bin/sh","r+") * f.close_read @@ -4975,7 +4971,7 @@ rb_io_close_read(VALUE io) * * Closes the write end of a duplex I/O stream (i.e., one that contains * both a read and a write stream, such as a pipe). Will raise an - * IOError if the stream is not duplexed. + * IOError if the stream is not duplexed. * * f = IO.popen("/bin/sh","r+") * f.close_write @@ -5028,8 +5024,8 @@ rb_io_close_write(VALUE io) * ios.sysseek(offset, whence=IO::SEEK_SET) -> integer * * Seeks to a given offset in the stream according to the value - * of whence (see IO#seek for values of - * whence). Returns the new offset into the file. + * of whence (see IO#seek for values of whence). Returns + * the new offset into the file. * * f = File.new("testfile") * f.sysseek(-13, IO::SEEK_END) #=> 53 @@ -5070,7 +5066,7 @@ rb_io_sysseek(int argc, VALUE *argv, VALUE io) * Writes the given string to ios using a low-level write. * Returns the number of bytes written. Do not mix with other methods * that write to ios or you may get unpredictable results. - * Raises SystemCallError on error. + * Raises SystemCallError on error. * * f = File.new("out", "w") * f.syswrite("ABCDEF") #=> 6 @@ -5117,8 +5113,7 @@ rb_io_syswrite(VALUE io, VALUE str) * The _outbuf_ will contain only the received data after the method call * even if it is not empty at the beginning. * - * Raises SystemCallError on error and - * EOFError at end of file. + * Raises SystemCallError on error and EOFError at end of file. * * f = File.new("testfile") * f.sysread(16) #=> "This is line one" @@ -5212,9 +5207,8 @@ pread_internal_call(VALUE arg) * This bypasses any userspace buffering of the IO layer. * If the optional outbuf argument is present, it must * reference a String, which will receive the data. - * Raises SystemCallError on error, EOFError - * at end of file and NotImplementedError if platform does not - * implement the system call. + * Raises SystemCallError on error, EOFError at end of file and + * NotImplementedError if platform does not implement the system call. * * File.write("testfile", "This is line one\nThis is line two\n") * File.open("testfile") do |f| @@ -5283,7 +5277,7 @@ internal_pwrite_func(void *ptr) * same IO object for reading the file at various locations. * This bypasses any userspace buffering of the IO layer. * Returns the number of bytes written. - * Raises SystemCallError on error and NotImplementedError + * Raises SystemCallError on error and NotImplementedError * if platform does not implement the system call. * * File.open("out", "w") do |f| @@ -6795,7 +6789,7 @@ pipe_close(VALUE io) * * Runs the specified command as a subprocess; the subprocess's * standard input and output will be connected to the returned - * IO object. + * IO object. * * The PID of the started process can be obtained by IO#pid method. * @@ -6814,7 +6808,7 @@ pipe_close(VALUE io) * If cmd is an +Array+ of +String+, * then it will be used as the subprocess's +argv+ bypassing a shell. * The array can contain a hash at first for environments and - * a hash at last for options similar to spawn. + * a hash at last for options similar to #spawn. * * The default mode for the new file object is ``r'', * but mode may be set to any of the modes listed in the description for class IO. @@ -6836,15 +6830,13 @@ pipe_close(VALUE io) * ls_result_with_error = ls_io.read * } * - * Raises exceptions which IO.pipe and - * Kernel.spawn raise. + * Raises exceptions which IO.pipe and Kernel.spawn raise. * * If a block is given, Ruby will run the command as a child connected * to Ruby with a pipe. Ruby's end of the pipe will be passed as a * parameter to the block. * At the end of block, Ruby closes the pipe and sets $?. - * In this case IO.popen returns - * the value of the block. + * In this case IO.popen returns the value of the block. * * If a block is given with a _cmd_ of ``-'', * the block will be run in two separate processes: once in the parent, @@ -6989,11 +6981,11 @@ rb_open_file(int argc, const VALUE *argv, VALUE io) * File.open(filename, mode="r" [, opt]) {|file| block } -> obj * File.open(filename [, mode [, perm]] [, opt]) {|file| block } -> obj * - * With no associated block, File.open is a synonym for + * With no associated block, File.open is a synonym for * File.new. If the optional code block is given, it will * be passed the opened +file+ as an argument and the File object will * automatically be closed when the block terminates. The value of the block - * will be returned from File.open. + * will be returned from File.open. * * If a file is being created, its initial permissions may be set using the * +perm+ parameter. See File.new for further discussion. @@ -7008,7 +7000,7 @@ rb_open_file(int argc, const VALUE *argv, VALUE io) * IO.open(fd, mode="r" [, opt]) -> io * IO.open(fd, mode="r" [, opt]) {|io| block } -> obj * - * With no associated block, IO.open is a synonym for IO.new. If + * With no associated block, IO.open is a synonym for IO.new. If * the optional code block is given, it will be passed +io+ as an argument, * and the IO object will automatically be closed when the block terminates. * In this instance, IO.open returns the value of the block. @@ -7033,7 +7025,7 @@ rb_io_s_open(int argc, VALUE *argv, VALUE klass) * IO.sysopen(path, [mode, [perm]]) -> integer * * Opens the given path, returning the underlying file descriptor as a - * Integer. + * Integer. * * IO.sysopen("testfile") #=> 3 */ @@ -7493,8 +7485,7 @@ rb_io_init_copy(VALUE dest, VALUE io) * ios.printf(format_string [, obj, ...]) -> nil * * Formats and writes to ios, converting parameters under - * control of the format string. See Kernel#sprintf - * for details. + * control of the format string. See Kernel#sprintf for details. */ VALUE @@ -7617,11 +7608,10 @@ rb_f_print(int argc, const VALUE *argv) * call-seq: * ios.putc(obj) -> obj * - * If obj is Numeric, write the character whose code is - * the least-significant byte of obj. - * If obj is String, write the first character - * of obj to ios. - * Otherwise, raise TypeError. + * If obj is Numeric, write the character whose code is the + * least-significant byte of obj. If obj is String, + * write the first character of obj to ios. Otherwise, + * raise TypeError. * * $stdout.putc "A" * $stdout.putc 65 @@ -8138,8 +8128,8 @@ rb_io_make_open_file(VALUE obj) * "t" Text file mode * * The exclusive access mode ("x") can be used together with "w" to ensure - * the file is created. Errno::EEXIST is raised when it already - * exists. It may not be supported with all kinds of streams (e.g. pipes). + * the file is created. Errno::EEXIST is raised when it already exists. + * It may not be supported with all kinds of streams (e.g. pipes). * * When the open mode of original IO is read only, the mode cannot be * changed to be writable. Similarly, the open mode cannot be changed from @@ -8229,7 +8219,7 @@ rb_io_make_open_file(VALUE obj) * io.puts "Hello, World!" * * Both of above print "Hello, World!" in UTF-16LE to standard error output - * with converting EOL generated by puts to CR. + * with converting EOL generated by #puts to CR. */ static VALUE @@ -8307,8 +8297,7 @@ rb_io_initialize(int argc, VALUE *argv, VALUE io) * * The new File object is buffered mode (or non-sync mode), unless * +filename+ is a tty. - * See IO#flush, IO#fsync, IO#fdatasync, and IO#sync= - * about sync mode. + * See IO#flush, IO#fsync, IO#fdatasync, and IO#sync= about sync mode. * * === Examples * @@ -8354,7 +8343,7 @@ rb_io_s_new(int argc, VALUE *argv, VALUE klass) * call-seq: * IO.for_fd(fd, mode [, opt]) -> io * - * Synonym for IO.new. + * Synonym for IO.new. * */ @@ -8882,7 +8871,7 @@ static VALUE argf_readline(int, VALUE *, VALUE); * readline(limit) -> string * readline(sep, limit) -> string * - * Equivalent to Kernel::gets, except + * Equivalent to Kernel::gets, except * +readline+ raises +EOFError+ at end of file. */ @@ -9314,17 +9303,17 @@ advice_arg_check(VALUE advice) * * If an error occurs, one of the following exceptions will be raised: * - * IOError:: The IO stream is closed. - * Errno::EBADF:: + * IOError:: The IO stream is closed. + * Errno::EBADF:: * The file descriptor of the current file is invalid. - * Errno::EINVAL:: An invalid value for _advice_ was given. - * Errno::ESPIPE:: + * Errno::EINVAL:: An invalid value for _advice_ was given. + * Errno::ESPIPE:: * The file descriptor of the current file refers to a FIFO or - * pipe. (Linux raises Errno::EINVAL in this case). - * TypeError:: + * pipe. (Linux raises Errno::EINVAL in this case). + * TypeError:: * Either _advice_ was not a Symbol, or one of the - * other arguments was not an Integer. - * RangeError:: One of the arguments given was too big/small. + * other arguments was not an Integer. + * RangeError:: One of the arguments given was too big/small. * * This list is not exhaustive; other Errno:: exceptions are also possible. */ @@ -9357,29 +9346,28 @@ rb_io_advise(int argc, VALUE *argv, VALUE io) * IO.select(read_array [, write_array [, error_array [, timeout]]]) -> array or nil * * Calls select(2) system call. - * It monitors given arrays of IO objects, waits until one or more - * of IO objects are ready for reading, are ready for writing, - * and have pending exceptions respectively, and returns an array that - * contains arrays of those IO objects. It will return +nil+ - * if optional timeout value is given and no IO object - * is ready in timeout seconds. + * It monitors given arrays of IO objects, waits until one or more of + * IO objects are ready for reading, are ready for writing, and have + * pending exceptions respectively, and returns an array that contains + * arrays of those IO objects. It will return +nil+ if optional + * timeout value is given and no IO object is ready in + * timeout seconds. * - * IO.select peeks the buffer of IO objects for testing readability. - * If the IO buffer is not empty, - * IO.select immediately notifies readability. - * This "peek" only happens for IO objects. - * It does not happen for IO-like objects such as OpenSSL::SSL::SSLSocket. + * IO.select peeks the buffer of IO objects for testing readability. + * If the IO buffer is not empty, IO.select immediately notifies + * readability. This "peek" only happens for IO objects. It does not + * happen for IO-like objects such as OpenSSL::SSL::SSLSocket. * - * The best way to use IO.select is invoking it - * after nonblocking methods such as read_nonblock, write_nonblock, etc. - * The methods raise an exception which is extended by - * IO::WaitReadable or IO::WaitWritable. - * The modules notify how the caller should wait with IO.select. - * If IO::WaitReadable is raised, the caller should wait for reading. - * If IO::WaitWritable is raised, the caller should wait for writing. + * The best way to use IO.select is invoking it after nonblocking + * methods such as #read_nonblock, #write_nonblock, etc. The methods + * raise an exception which is extended by IO::WaitReadable or + * IO::WaitWritable. The modules notify how the caller should wait + * with IO.select. If IO::WaitReadable is raised, the caller should + * wait for reading. If IO::WaitWritable is raised, the caller should + * wait for writing. * - * So, blocking read (readpartial) can be emulated using - * read_nonblock and IO.select as follows: + * So, blocking read (#readpartial) can be emulated using + * #read_nonblock and IO.select as follows: * * begin * result = io_like.read_nonblock(maxlen) @@ -9391,57 +9379,57 @@ rb_io_advise(int argc, VALUE *argv, VALUE io) * retry * end * - * Especially, the combination of nonblocking methods and - * IO.select is preferred for IO like - * objects such as OpenSSL::SSL::SSLSocket. - * It has to_io method to return underlying IO object. - * IO.select calls to_io to obtain the file descriptor to wait. + * Especially, the combination of nonblocking methods and IO.select is + * preferred for IO like objects such as OpenSSL::SSL::SSLSocket. It + * has #to_io method to return underlying IO object. IO.select calls + * #to_io to obtain the file descriptor to wait. * - * This means that readability notified by IO.select doesn't mean - * readability from OpenSSL::SSL::SSLSocket object. + * This means that readability notified by IO.select doesn't mean + * readability from OpenSSL::SSL::SSLSocket object. * - * The most likely situation is that OpenSSL::SSL::SSLSocket buffers some data. - * IO.select doesn't see the buffer. - * So IO.select can block when OpenSSL::SSL::SSLSocket#readpartial doesn't block. + * The most likely situation is that OpenSSL::SSL::SSLSocket buffers + * some data. IO.select doesn't see the buffer. So IO.select can + * block when OpenSSL::SSL::SSLSocket#readpartial doesn't block. * * However, several more complicated situations exist. * * SSL is a protocol which is sequence of records. * The record consists of multiple bytes. - * So, the remote side of SSL sends a partial record, - * IO.select notifies readability but - * OpenSSL::SSL::SSLSocket cannot decrypt a byte and - * OpenSSL::SSL::SSLSocket#readpartial will block. + * So, the remote side of SSL sends a partial record, IO.select + * notifies readability but OpenSSL::SSL::SSLSocket cannot decrypt a + * byte and OpenSSL::SSL::SSLSocket#readpartial will block. * * Also, the remote side can request SSL renegotiation which forces * the local SSL engine to write some data. - * This means OpenSSL::SSL::SSLSocket#readpartial may - * invoke write system call and it can block. - * In such a situation, OpenSSL::SSL::SSLSocket#read_nonblock - * raises IO::WaitWritable instead of blocking. - * So, the caller should wait for ready for writability as above example. + * This means OpenSSL::SSL::SSLSocket#readpartial may invoke #write + * system call and it can block. + * In such a situation, OpenSSL::SSL::SSLSocket#read_nonblock raises + * IO::WaitWritable instead of blocking. + * So, the caller should wait for ready for writability as above + * example. * - * The combination of nonblocking methods and IO.select is - * also useful for streams such as tty, pipe socket socket when - * multiple processes read from a stream. + * The combination of nonblocking methods and IO.select is also useful + * for streams such as tty, pipe socket socket when multiple processes + * read from a stream. * * Finally, Linux kernel developers don't guarantee that * readability of select(2) means readability of following read(2) even * for a single process. * See select(2) manual on GNU/Linux system. * - * Invoking IO.select before IO#readpartial works well as usual. - * However it is not the best way to use IO.select. + * Invoking IO.select before IO#readpartial works well as usual. + * However it is not the best way to use IO.select. * * The writability notified by select(2) doesn't show * how many bytes are writable. - * IO#write method blocks until given whole string is written. - * So, IO#write(two or more bytes) can block after writability is notified by IO.select. - * IO#write_nonblock is required to avoid the blocking. + * IO#write method blocks until given whole string is written. + * So, IO#write(two or more bytes) can block after + * writability is notified by IO.select. IO#write_nonblock is required + * to avoid the blocking. * - * Blocking write (write) can be emulated using - * write_nonblock and IO.select as follows: - * IO::WaitReadable should also be rescued for SSL renegotiation in OpenSSL::SSL::SSLSocket. + * Blocking write (#write) can be emulated using #write_nonblock and + * IO.select as follows: IO::WaitReadable should also be rescued for + * SSL renegotiation in OpenSSL::SSL::SSLSocket. * * while 0 < string.bytesize * begin @@ -9457,9 +9445,9 @@ rb_io_advise(int argc, VALUE *argv, VALUE io) * end * * === Parameters - * read_array:: an array of IO objects that wait until ready for read - * write_array:: an array of IO objects that wait until ready for write - * error_array:: an array of IO objects that wait for exceptions + * read_array:: an array of IO objects that wait until ready for read + * write_array:: an array of IO objects that wait until ready for write + * error_array:: an array of IO objects that wait for exceptions * timeout:: a numeric value in second * * === Example @@ -9910,9 +9898,9 @@ rb_fcntl(VALUE io, VALUE req, VALUE arg) * query file-oriented I/O streams. Arguments and results are platform * dependent. If arg is a number, its value is passed * directly. If it is a string, it is interpreted as a binary sequence - * of bytes (Array#pack might be a useful way to build this - * string). On Unix platforms, see fcntl(2) for details. - * Not implemented on all platforms. + * of bytes (Array#pack might be a useful way to build this string). On + * Unix platforms, see fcntl(2) for details. Not + * implemented on all platforms. */ static VALUE @@ -10166,7 +10154,7 @@ pipe_pair_close(VALUE rw) * IO.pipe(...) {|read_io, write_io| ... } * * Creates a pair of pipe endpoints (connected to each other) and - * returns them as a two-element array of IO objects: + * returns them as a two-element array of IO objects: * [ read_io, write_io ]. * * If a block is given, the block is called and @@ -10463,8 +10451,8 @@ seek_before_access(VALUE argp) * IO.read(name, [length [, offset]] [, opt] ) -> string * * Opens the file, optionally seeks to the given +offset+, then returns - * +length+ bytes (defaulting to the rest of the file). read - * ensures the file is closed before returning. + * +length+ bytes (defaulting to the rest of the file). #read ensures + * the file is closed before returning. * * If +name+ starts with a pipe character ("|"), a subprocess is * created in the same way as Kernel#open, and its output is returned. @@ -10529,10 +10517,10 @@ rb_io_s_read(int argc, VALUE *argv, VALUE io) * call-seq: * IO.binread(name, [length [, offset]] ) -> string * - * Opens the file, optionally seeks to the given offset, then returns - * length bytes (defaulting to the rest of the file). - * binread ensures the file is closed before returning. - * The open mode would be "rb:ASCII-8BIT". + * Opens the file, optionally seeks to the given offset, then + * returns length bytes (defaulting to the rest of the file). + * #binread ensures the file is closed before returning. The open mode + * would be "rb:ASCII-8BIT". * * IO.binread("testfile") #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n" * IO.binread("testfile", 20) #=> "This is line one\nThi" @@ -10635,10 +10623,9 @@ io_s_write(int argc, VALUE *argv, VALUE klass, int binary) * IO.write(name, string [, offset] [, opt]) -> integer * * Opens the file, optionally seeks to the given offset, writes - * string, then returns the length written. - * write ensures the file is closed before returning. - * If offset is not given in write mode, the file is truncated. - * Otherwise, it is not truncated. + * string, then returns the length written. #write ensures the + * file is closed before returning. If offset is not given in + * write mode, the file is truncated. Otherwise, it is not truncated. * * IO.write("testfile", "0123456789", 20) #=> 10 * # File could contain: "This is line one\nThi0123456789two\nThis is line three\nAnd so on...\n" @@ -10684,8 +10671,8 @@ rb_io_s_write(int argc, VALUE *argv, VALUE io) * IO.binwrite(name, string, [offset] ) -> integer * IO.binwrite(name, string, [offset], open_args ) -> integer * - * Same as IO.write except opening the file in binary mode - * and ASCII-8BIT encoding ("wb:ASCII-8BIT"). + * Same as IO.write except opening the file in binary mode and + * ASCII-8BIT encoding ("wb:ASCII-8BIT"). */ static VALUE @@ -11578,9 +11565,8 @@ copy_stream_finalize(VALUE arg) * * IO.copy_stream copies src to dst. * src and dst is either a filename or an IO-like object. - * IO-like object for src should have readpartial or - * read method. - * IO-like object for dst should have write method. + * IO-like object for src should have #readpartial or #read + * method. IO-like object for dst should have #write method. * (Specialized mechanisms, such as sendfile system call, may be used * on appropriate situation.) * @@ -12103,11 +12089,11 @@ static VALUE argf_getpartial(int argc, VALUE *argv, VALUE argf, VALUE opts, * The _outbuf_ will contain only the received data after the method call * even if it is not empty at the beginning. * - * It raises EOFError on end of ARGF stream. + * It raises EOFError on end of ARGF stream. * Since ARGF stream is a concatenation of multiple files, * internally EOF is occur for each file. * ARGF.readpartial returns empty strings for EOFs except the last one and - * raises EOFError for the last one. + * raises EOFError for the last one. * */ @@ -12417,7 +12403,7 @@ argf_each_line(int argc, VALUE *argv, VALUE argf) } /* - * This is a deprecated alias for each_line. + * This is a deprecated alias for #each_line. */ static VALUE @@ -12464,7 +12450,7 @@ argf_each_byte(VALUE argf) } /* - * This is a deprecated alias for each_byte. + * This is a deprecated alias for #each_byte. */ static VALUE @@ -12503,7 +12489,7 @@ argf_each_char(VALUE argf) } /* - * This is a deprecated alias for each_char. + * This is a deprecated alias for #each_char. */ static VALUE @@ -12542,7 +12528,7 @@ argf_each_codepoint(VALUE argf) } /* - * This is a deprecated alias for each_codepoint. + * This is a deprecated alias for #each_codepoint. */ static VALUE diff --git a/load.c b/load.c index d44a11c97d..576464fb68 100644 --- a/load.c +++ b/load.c @@ -1120,8 +1120,8 @@ ruby_init_ext(const char *name, void (*init)(void)) * call-seq: * mod.autoload(module, filename) -> nil * - * Registers _filename_ to be loaded (using Kernel::require) - * the first time that _module_ (which may be a String or + * Registers _filename_ to be loaded (using Kernel::require) + * the first time that _module_ (which may be a String or * a symbol) is accessed in the namespace of _mod_. * * module A @@ -1167,8 +1167,8 @@ rb_mod_autoload_p(VALUE mod, VALUE sym) * call-seq: * autoload(module, filename) -> nil * - * Registers _filename_ to be loaded (using Kernel::require) - * the first time that _module_ (which may be a String or + * Registers _filename_ to be loaded (using Kernel::require) + * the first time that _module_ (which may be a String or * a symbol) is accessed. * * autoload(:MyModule, "/usr/local/lib/modules/my_module.rb") diff --git a/object.c b/object.c index d37c923fa6..d31755323e 100644 --- a/object.c +++ b/object.c @@ -167,15 +167,15 @@ rb_eql(VALUE obj1, VALUE obj2) * obj.equal?(other) -> true or false * obj.eql?(other) -> true or false * - * Equality --- At the Object level, == returns - * true only if +obj+ and +other+ are the same object. - * Typically, this method is overridden in descendant classes to provide + * Equality --- At the Object level, #== returns true + * only if +obj+ and +other+ are the same object. Typically, this + * method is overridden in descendant classes to provide * class-specific meaning. * - * Unlike ==, the equal? method should never be - * overridden by subclasses as it is used to determine object identity - * (that is, a.equal?(b) if and only if a is the - * same object as b): + * Unlike #==, the #equal? method should never be overridden by + * subclasses as it is used to determine object identity (that is, + * a.equal?(b) if and only if a is the same + * object as b): * * obj = "a" * other = obj.dup @@ -184,14 +184,13 @@ rb_eql(VALUE obj1, VALUE obj2) * obj.equal? other #=> false * obj.equal? obj #=> true * - * The eql? method returns true if +obj+ and - * +other+ refer to the same hash key. This is used by Hash to test members - * for equality. For objects of class Object, eql? - * is synonymous with ==. Subclasses normally continue this - * tradition by aliasing eql? to their overridden == - * method, but there are exceptions. Numeric types, for - * example, perform type conversion across ==, but not across - * eql?, so: + * The #eql? method returns true if +obj+ and +other+ + * refer to the same hash key. This is used by Hash to test members + * for equality. For objects of class Object, #eql? is synonymous + * with #==. Subclasses normally continue this tradition by aliasing + * #eql? to their overridden #== method, but there are exceptions. + * Numeric types, for example, perform type conversion across #==, + * but not across #eql?, so: * * 1 == 1.0 #=> true * 1.eql? 1.0 #=> false @@ -263,9 +262,9 @@ rb_class_real(VALUE cl) * call-seq: * obj.class -> class * - * Returns the class of obj. This method must always be - * called with an explicit receiver, as class is also a - * reserved word in Ruby. + * Returns the class of obj. This method must always be called + * with an explicit receiver, as #class is also a reserved word in + * Ruby. * * 1.class #=> Integer * self.class #=> Object @@ -375,9 +374,9 @@ special_object_p(VALUE obj) * * Produces a shallow copy of obj---the instance variables of * obj are copied, but not the objects they reference. - * clone copies the frozen (unless :freeze keyword argument - * is given with a false value) and tainted state of obj. - * See also the discussion under Object#dup. + * #clone copies the frozen (unless +:freeze+ keyword argument is + * given with a false value) and tainted state of obj. See + * also the discussion under Object#dup. * * class Klass * attr_accessor :str @@ -484,7 +483,7 @@ rb_obj_clone(VALUE obj) * * Produces a shallow copy of obj---the instance variables of * obj are copied, but not the objects they reference. - * dup copies the tainted state of obj. + * #dup copies the tainted state of obj. * * This method may have class-specific behavior. If so, that * behavior will be documented under the #+initialize_copy+ method of @@ -492,11 +491,10 @@ rb_obj_clone(VALUE obj) * * === on dup vs clone * - * In general, clone and dup may have different - * semantics in descendant classes. While clone is used to - * duplicate an object, including its internal state, dup - * typically uses the class of the descendant object to create the new - * instance. + * In general, #clone and #dup may have different semantics in + * descendant classes. While #clone is used to duplicate an object, + * including its internal state, #dup typically uses the class of the + * descendant object to create the new instance. * * When using #dup, any modules that the object has been extended with will not * be copied. @@ -637,10 +635,10 @@ rb_obj_init_dup_clone(VALUE obj, VALUE orig) * call-seq: * obj.to_s -> string * - * Returns a string representing obj. The default - * to_s prints the object's class and an encoding of the - * object id. As a special case, the top-level object that is the - * initial execution context of Ruby programs returns ``main''. + * Returns a string representing obj. The default #to_s prints + * the object's class and an encoding of the object id. As a special + * case, the top-level object that is the initial execution context + * of Ruby programs returns ``main''. * *-- * Default implementation of \c #to_s. @@ -732,13 +730,12 @@ inspect_obj(VALUE obj, VALUE str, int recur) * obj.inspect -> string * * Returns a string containing a human-readable representation of obj. - * The default inspect shows the object's class name, - * an encoding of the object id, and a list of the instance variables and - * their values (by calling #inspect on each of them). - * User defined classes should override this method to provide a better - * representation of obj. When overriding this method, it should - * return a string whose encoding is compatible with the default external - * encoding. + * The default #inspect shows the object's class name, an encoding of + * the object id, and a list of the instance variables and their + * values (by calling #inspect on each of them). User defined classes + * should override this method to provide a better representation of + * obj. When overriding this method, it should return a string + * whose encoding is compatible with the default external encoding. * * [ 1, 2, 3..4, 'five' ].inspect #=> "[1, 2, 3..4, \"five\"]" * Time.new.inspect #=> "2008-03-08 19:43:39 +0900" @@ -794,7 +791,7 @@ static VALUE class_search_ancestor(VALUE cl, VALUE c); * obj.instance_of?(class) -> true or false * * Returns true if obj is an instance of the given - * class. See also Object#kind_of?. + * class. See also Object#kind_of?. * * class A; end * class B < A; end @@ -1322,9 +1319,9 @@ rb_obj_infect(VALUE victim, VALUE carrier) * obj.freeze -> obj * * Prevents further modifications to obj. A - * RuntimeError will be raised if modification is attempted. + * RuntimeError will be raised if modification is attempted. * There is no way to unfreeze a frozen object. See also - * Object#frozen?. + * Object#frozen?. * * This method returns self. * @@ -1496,7 +1493,7 @@ nil_match(VALUE obj1, VALUE obj2) * Document-class: TrueClass * * The global value true is the only instance of class - * TrueClass and represents a logically true value in + * TrueClass and represents a logically true value in * boolean expressions. The class provides operators allowing * true to be used in logical expressions. */ @@ -1573,7 +1570,7 @@ true_xor(VALUE obj, VALUE obj2) * Document-class: FalseClass * * The global value false is the only instance of class - * FalseClass and represents a logically false value in + * FalseClass and represents a logically false value in * boolean expressions. The class provides operators allowing * false to participate correctly in logical expressions. * @@ -1715,16 +1712,16 @@ rb_obj_not_match(VALUE obj1, VALUE obj2) * Returns 0 if +obj+ and +other+ are the same object * or obj == other, otherwise nil. * - * The <=> is used by various methods to compare objects, for example + * The #<=> is used by various methods to compare objects, for example * Enumerable#sort, Enumerable#max etc. * - * Your implementation of <=> should return one of the following values: -1, 0, + * Your implementation of #<=> should return one of the following values: -1, 0, * 1 or nil. -1 means self is smaller than other. 0 means self is equal to other. * 1 means self is bigger than other. Nil means the two values could not be * compared. * - * When you define <=>, you can include Comparable to gain the methods - * <=, <, ==, >=, > and between?. + * When you define #<=>, you can include Comparable to gain the + * methods #<=, #<, #==, #>=, #> and #between?. */ static VALUE rb_obj_cmp(VALUE obj1, VALUE obj2) @@ -1738,16 +1735,16 @@ rb_obj_cmp(VALUE obj1, VALUE obj2) * * Document-class: Module * - * A Module is a collection of methods and constants. The + * A Module is a collection of methods and constants. The * methods in a module may be instance methods or module methods. * Instance methods appear as methods in a class when the module is * included, module methods do not. Conversely, module methods may be * called without creating an encapsulating object, while instance - * methods may not. (See Module#module_function.) + * methods may not. (See Module#module_function.) * * In the descriptions that follow, the parameter sym refers * to a symbol, which is either a quoted string or a - * Symbol (such as :name). + * Symbol (such as :name). * * module Mod * include Math @@ -1986,7 +1983,7 @@ rb_class_s_alloc(VALUE klass) * * Creates a new anonymous module. If a block is given, it is passed * the module object, and the block is evaluated in the context of this - * module like module_eval. + * module like #module_eval. * * fred = Module.new do * def meth1 @@ -2031,12 +2028,12 @@ rb_mod_initialize_clone(VALUE clone, VALUE orig) * Class.new(super_class=Object) { |mod| ... } -> a_class * * Creates a new anonymous (unnamed) class with the given superclass - * (or Object if no parameter is given). You can give a + * (or Object if no parameter is given). You can give a * class a name by assigning the class object to a constant. * * If a block is given, it is passed the class object, and the block * is evaluated in the context of this class like - * class_eval. + * #class_eval. * * fred = Class.new do * def meth1 @@ -2170,11 +2167,10 @@ rb_class_allocate_instance(VALUE klass) * call-seq: * class.new(args, ...) -> obj * - * Calls allocate to create a new object of - * class's class, then invokes that object's - * initialize method, passing it args. - * This is the method that ends up getting called whenever - * an object is constructed using .new. + * Calls #allocate to create a new object of class's class, + * then invokes that object's #initialize method, passing it + * args. This is the method that ends up getting called + * whenever an object is constructed using .new. * */ @@ -2340,7 +2336,7 @@ rb_mod_attr_reader(int argc, VALUE *argv, VALUE klass) * attr(name, true) -> nil * attr(name, false) -> nil * - * The first form is equivalent to attr_reader. + * The first form is equivalent to #attr_reader. * The second form is equivalent to attr_accessor(name) but deprecated. * The last form is equivalent to attr_reader(name) but deprecated. *-- @@ -2706,7 +2702,7 @@ rb_mod_const_defined(int argc, VALUE *argv, VALUE mod) * Returns the value of the given instance variable, or nil if the * instance variable is not set. The @ part of the * variable name should be included for regular instance - * variables. Throws a NameError exception if the + * variables. Throws a NameError exception if the * supplied symbol is not valid as an instance variable name. * String arguments are converted to symbols. * @@ -2799,7 +2795,7 @@ rb_obj_ivar_defined(VALUE obj, VALUE iv) * mod.class_variable_get(string) -> obj * * Returns the value of the given class variable (or throws a - * NameError exception). The @@ part of the + * NameError exception). The @@ part of the * variable name should be included for regular class variables. * String arguments are converted to symbols. * @@ -3223,15 +3219,15 @@ opts_exception_p(VALUE opts) * call-seq: * Integer(arg, base=0, exception: true) -> integer or nil * - * Converts arg to an Integer. + * Converts arg to an Integer. * Numeric types are converted directly (with floating point numbers * being truncated). base (0, or between 2 and 36) is a base for - * integer string representation. If arg is a String, + * integer string representation. If arg is a String, * when base is omitted or equals zero, radix indicators * (0, 0b, and 0x) are honored. * In any case, strings should be strictly conformed to numeric * representation. This behavior is different from that of - * String#to_i. Non string values will be converted by first + * String#to_i. Non string values will be converted by first * trying to_int, then to_i. * * Passing nil raises a TypeError, while passing a String that @@ -3585,11 +3581,13 @@ rb_Float(VALUE val) * call-seq: * Float(arg, exception: true) -> float or nil * - * Returns arg converted to a float. Numeric types are converted - * directly, and with exception to string and nil the rest are converted using arg.to_f. - * Converting a string with invalid characters will result in a ArgumentError. - * Converting nil generates a TypeError. - * Exceptions can be suppressed by passing exception: false. + * Returns arg converted to a float. Numeric types are + * converted directly, and with exception to String and + * nil the rest are converted using + * arg.to_f. Converting a String with invalid + * characters will result in a ArgumentError. Converting + * nil generates a TypeError. Exceptions can be + * suppressed by passing exception: false. * * Float(1) #=> 1.0 * Float("123.456") #=> 123.456 @@ -3746,7 +3744,7 @@ rb_String(VALUE val) * call-seq: * String(arg) -> string * - * Returns arg as a String. + * Returns arg as a String. * * First tries to call its to_str method, then its to_s method. * @@ -3789,7 +3787,7 @@ rb_Array(VALUE val) * returns an Array of length 1 containing +arg+. * * If to_ary or to_a returns something other than - * an Array, raises a TypeError. + * an Array, raises a TypeError. * * Array(["a", "b"]) #=> ["a", "b"] * Array(1..5) #=> [1, 2, 3, 4, 5] @@ -3826,8 +3824,8 @@ rb_Hash(VALUE val) * call-seq: * Hash(arg) -> hash * - * Converts arg to a Hash by calling - * arg.to_hash. Returns an empty Hash when + * Converts arg to a Hash by calling + * arg.to_hash. Returns an empty Hash when * arg is nil or []. * * Hash([]) #=> {} @@ -3910,7 +3908,7 @@ rb_obj_dig(int argc, VALUE *argv, VALUE obj, VALUE notfound) * Document-class: Class * * Classes in Ruby are first-class objects---each is an instance of - * class Class. + * class Class. * * Typically, you create a new class by using: * @@ -3919,12 +3917,11 @@ rb_obj_dig(int argc, VALUE *argv, VALUE obj, VALUE notfound) * end * * When a new class is created, an object of type Class is initialized and - * assigned to a global constant (Name in this case). + * assigned to a global constant (Name in this case). * * When Name.new is called to create a new object, the - * new method in Class is run by default. - * This can be demonstrated by overriding new in - * Class: + * #new method in Class is run by default. + * This can be demonstrated by overriding #new in Class: * * class Class * alias old_new new