ruby-changes:37286
From: nagachika <ko1@a...>
Date: Thu, 22 Jan 2015 00:51:09 +0900 (JST)
Subject: [ruby-changes:37286] nagachika:r49367 (ruby_2_1): merge revision(s) r45375, r48260, r48320, r48746: [Backport #10526]
nagachika 2015-01-22 00:50:58 +0900 (Thu, 22 Jan 2015) New Revision: 49367 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=49367 Log: merge revision(s) r45375,r48260,r48320,r48746: [Backport #10526] * complax.c: [DOC] Document number conversion of `nil` by @skade [fix GH-570] [ci skip] * object.c, rational.c: ditto. * object.c: fix document of Kernel.Stirng by @suzukaze [fix GH-743][ci skip] * object.c (Module#const_defined?): [DOC] Revise the documentation. Patch by Xavier Noria. [Fixes GH-754] https://github.com/ruby/ruby/pull/754 * object.c: [DOC] Revise documentation by Marcus Stollsteimer at [ruby-core:66368]. [Bug #10526] * #inspect: be more specific about generated string, remove obsolete example. * #nil?: use code examples instead of different call-seq's. * #tap: clarify what is yielded. * Integer(): be more specific about to_int and to_i, remove reference to Ruby 1.8. * Array(): fix error. * Class: fix variable name style and indentation in example. * improve consistency, fix typos and formatting. Modified directories: branches/ruby_2_1/ Modified files: branches/ruby_2_1/ChangeLog branches/ruby_2_1/complex.c branches/ruby_2_1/object.c branches/ruby_2_1/rational.c branches/ruby_2_1/version.h Index: ruby_2_1/complex.c =================================================================== --- ruby_2_1/complex.c (revision 49366) +++ ruby_2_1/complex.c (revision 49367) @@ -433,6 +433,8 @@ f_complex_new2(VALUE klass, VALUE x, VAL https://github.com/ruby/ruby/blob/trunk/ruby_2_1/complex.c#L433 * * Complex(1, 2) #=> (1+2i) * Complex('1+2i') #=> (1+2i) + * Complex(nil) #=> TypeError + * Complex(1, nil) #=> TypeError * * Syntax of string form: * Index: ruby_2_1/ChangeLog =================================================================== --- ruby_2_1/ChangeLog (revision 49366) +++ ruby_2_1/ChangeLog (revision 49367) @@ -1,3 +1,29 @@ https://github.com/ruby/ruby/blob/trunk/ruby_2_1/ChangeLog#L1 +Thu Jan 22 00:49:52 2015 Nobuyoshi Nakada <nobu@r...> + + * object.c: [DOC] Revise documentation by Marcus Stollsteimer at + [ruby-core:66368]. [Bug #10526] + + * #inspect: be more specific about generated string, remove + obsolete example. + * #nil?: use code examples instead of different call-seq's. + * #tap: clarify what is yielded. + * Integer(): be more specific about to_int and to_i, remove + reference to Ruby 1.8. + * Array(): fix error. + * Class: fix variable name style and indentation in example. + * improve consistency, fix typos and formatting. + +Thu Jan 22 00:49:52 2015 Benoit Daloze <eregontp@g...> + + * object.c (Module#const_defined?): [DOC] Revise the documentation. + Patch by Xavier Noria. + [Fixes GH-754] https://github.com/ruby/ruby/pull/754 + +Thu Jan 22 00:49:52 2015 SHIBATA Hiroshi <shibata.hiroshi@g...> + + * object.c: fix document of Kernel.Stirng by @suzukaze + [fix GH-743][ci skip] + Thu Jan 22 00:25:15 2015 Nobuyoshi Nakada <nobu@r...> * load.c (rb_f_load): path name needs to be transcoded to OS path Index: ruby_2_1/object.c =================================================================== --- ruby_2_1/object.c (revision 49366) +++ ruby_2_1/object.c (revision 49367) @@ -154,7 +154,7 @@ rb_obj_equal(VALUE obj1, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L154 * capacity of a Fixnum will be truncated before being used. * * The hash value for an object may not be identical across invocations or - * implementations of ruby. If you need a stable identifier across ruby + * implementations of Ruby. If you need a stable identifier across Ruby * invocations and implementations you will need to generate one with a custom * method. */ @@ -233,7 +233,7 @@ rb_obj_class(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L233 * obj.singleton_class -> class * * Returns the singleton class of <i>obj</i>. This method creates - * a new singleton class if <i>obj</i> does not have it. + * a new singleton class if <i>obj</i> does not have one. * * If <i>obj</i> is <code>nil</code>, <code>true</code>, or * <code>false</code>, it returns NilClass, TrueClass, or FalseClass, @@ -314,9 +314,9 @@ init_copy(VALUE dest, VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L314 * obj.clone -> an_object * * Produces a shallow copy of <i>obj</i>---the instance variables of - * <i>obj</i> are copied, but not the objects they reference. Copies - * the frozen and tainted state of <i>obj</i>. See also the discussion - * under <code>Object#dup</code>. + * <i>obj</i> are copied, but not the objects they reference. + * <code>clone</code> copies the frozen and tainted state of <i>obj</i>. + * See also the discussion under <code>Object#dup</code>. * * class Klass * attr_accessor :str @@ -364,8 +364,8 @@ rb_obj_clone(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L364 * obj.dup -> an_object * * Produces a shallow copy of <i>obj</i>---the instance variables of - * <i>obj</i> are copied, but not the objects they reference. <code>dup</code> - * copies the tainted state of <i>obj</i>. + * <i>obj</i> are copied, but not the objects they reference. + * <code>dup</code> copies the tainted state of <i>obj</i>. * * This method may have class-specific behavior. If so, that * behavior will be documented under the #+initialize_copy+ method of @@ -379,7 +379,7 @@ rb_obj_clone(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L379 * 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 + * When using #dup, any modules that the object has been extended with will not * be copied. * * class Klass @@ -445,7 +445,7 @@ rb_obj_init_dup_clone(VALUE obj, VALUE o https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L445 * Returns a string representing <i>obj</i>. The default * <code>to_s</code> 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.'' + * initial execution context of Ruby programs returns ``main''. */ VALUE @@ -462,7 +462,7 @@ rb_any_to_s(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L462 /* * If the default external encoding is ASCII compatible, the encoding of - * inspected result must be compatible with it. + * the inspected result must be compatible with it. * If the default external encoding is ASCII incompatible, * the result must be ASCII only. */ @@ -531,9 +531,10 @@ inspect_obj(VALUE obj, VALUE str, int re https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L531 * obj.inspect -> string * * Returns a string containing a human-readable representation of <i>obj</i>. - * By default, show the class name and the list of the instance variables and + * The default <code>inspect</code> 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 make better + * User defined classes should override this method to provide a better * representation of <i>obj</i>. When overriding this method, it should * return a string whose encoding is compatible with the default external * encoding. @@ -551,13 +552,6 @@ inspect_obj(VALUE obj, VALUE str, int re https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L552 * end * end * Bar.new.inspect #=> "#<Bar:0x0300c868 @bar=1>" - * - * class Baz - * def to_s - * "baz" - * end - * end - * Baz.new.inspect #=> "#<Baz:0x0300c868>" */ static VALUE @@ -680,14 +674,14 @@ rb_class_search_ancestor(VALUE cl, VALUE https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L674 * call-seq: * obj.tap{|x|...} -> obj * - * Yields <code>x</code> to the block, and then returns <code>x</code>. + * Yields self to the block, and then returns self. * The primary purpose of this method is to "tap into" a method chain, * in order to perform operations on intermediate results within the chain. * * (1..10) .tap {|x| puts "original: #{x.inspect}"} * .to_a .tap {|x| puts "array: #{x.inspect}"} * .select {|x| x%2==0} .tap {|x| puts "evens: #{x.inspect}"} - * .map { |x| x*x } .tap {|x| puts "squares: #{x.inspect}"} + * .map {|x| x*x} .tap {|x| puts "squares: #{x.inspect}"} * */ @@ -721,7 +715,7 @@ rb_obj_tap(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L715 * class Baz < Bar * end * - * produces: + * <em>produces:</em> * * New subclass: Bar * New subclass: Baz @@ -743,7 +737,7 @@ rb_obj_tap(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L737 * def some_instance_method() end * end * - * produces: + * <em>produces:</em> * * Adding :some_instance_method * @@ -769,7 +763,7 @@ rb_obj_tap(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L763 * remove_method :some_instance_method * end * - * produces: + * <em>produces:</em> * * Removing :some_instance_method * @@ -957,13 +951,13 @@ rb_obj_tainted(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L951 * * Objects that are marked as tainted will be restricted from various built-in * methods. This is to prevent insecure data, such as command-line arguments - * or strings read from Kernel#gets, from inadvertently compromising the users + * or strings read from Kernel#gets, from inadvertently compromising the user's * system. * - * To check whether an object is tainted, use #tainted? + * To check whether an object is tainted, use #tainted?. * * You should only untaint a tainted object if your code has inspected it and - * determined that it is safe. To do so use #untaint + * determined that it is safe. To do so use #untaint. * * In $SAFE level 3, all newly created objects are tainted and you can't untaint * objects. @@ -1249,7 +1243,7 @@ true_and(VALUE obj, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L1243 * call-seq: * true | obj -> true * - * Or---Returns <code>true</code>. As <i>anObject</i> is an argument to + * Or---Returns <code>true</code>. As <i>obj</i> is an argument to * a method call, it is always evaluated; there is no short-circuit * evaluation in this case. * @@ -1373,10 +1367,12 @@ rb_true(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L1367 /* * call-seq: - * nil.nil? -> true - * <anything_else>.nil? -> false + * obj.nil? -> true or false * * Only the object <i>nil</i> responds <code>true</code> to <code>nil?</code>. + * + * Object.new.nil? #=> false + * nil.nil? #=> true */ @@ -1453,7 +1449,7 @@ rb_obj_cmp(VALUE obj1, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L1449 * 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 <code>Module#module_function</code>) + * methods may not. (See <code>Module#module_function</code>.) * * In the descriptions that follow, the parameter <i>sym</i> refers * to a symbol, which is either a quoted string or a @@ -1476,7 +1472,7 @@ rb_obj_cmp(VALUE obj1, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L1472 * call-seq: * mod.to_s -> string * - * Return a string representing this module or class. For basic + * Returns a string representing this module or class. For basic * classes and modules, this is the name. For singletons, we * show information on the thing we're attached to as well. */ @@ -1536,7 +1532,7 @@ rb_mod_freeze(VALUE mod) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L1532 * call-seq: * mod === obj -> true or false * - * Case Equality---Returns <code>true</code> if <i>anObject</i> is an + * Case Equality---Returns <code>true</code> if <i>obj</i> is an * instance of <i>mod</i> or one of <i>mod</i>'s descendants. Of * limited use for modules, but can be used in <code>case</code> * statements to classify objects by class. @@ -1556,7 +1552,7 @@ rb_mod_eqq(VALUE mod, VALUE arg) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L1552 * is the same as <i>other</i>. Returns * <code>nil</code> if there's no relationship between the two. * (Think of the relationship in terms of the class definition: - * "class A<B" implies "A<B"). + * "class A<B" implies "A<B".) * */ @@ -1587,7 +1583,7 @@ rb_class_inherited_p(VALUE mod, VALUE ar https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L1583 * Returns true if <i>mod</i> is a subclass of <i>other</i>. Returns * <code>nil</code> if there's no relationship between the two. * (Think of the relationship in terms of the class definition: - * "class A<B" implies "A<B"). + * "class A<B" implies "A<B".) * */ @@ -1607,7 +1603,7 @@ rb_mod_lt(VALUE mod, VALUE arg) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L1603 * two modules are the same. Returns * <code>nil</code> if there's no relationship between the two. * (Think of the relationship in terms of the class definition: - * "class A<B" implies "B>A"). + * "class A<B" implies "B>A".) * */ @@ -1628,7 +1624,7 @@ rb_mod_ge(VALUE mod, VALUE arg) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L1624 * Returns true if <i>mod</i> is an ancestor of <i>other</i>. Returns * <code>nil</code> if there's no relationship between the two. * (Think of the relationship in terms of the class definition: - * "class A<B" implies "B>A"). + * "class A<B" implies "B>A".) * */ @@ -1875,7 +1871,7 @@ rb_class_new_instance(int argc, VALUE *a https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L1871 * class Bar < Foo; end * Bar.superclass #=> Foo * - * returns nil when the given class hasn't a parent class: + * Returns nil when the given class does not have a parent class: * * BasicObject.superclass #=> nil * @@ -2050,9 +2046,9 @@ rb_mod_attr_accessor(int argc, VALUE *ar https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L2046 * mod.const_get(sym, inherit=true) -> obj * mod.const_get(str, inherit=true) -> obj * - * Checks for a constant with the given name in <i>mod</i> + * Checks for a constant with the given name in <i>mod</i>. * If +inherit+ is set, the lookup will also search - * the ancestors (and +Object+ if <i>mod</i> is a +Module+.) + * the ancestors (and +Object+ if <i>mod</i> is a +Module+). * * The value of the constant is returned if a definition is found, * otherwise a +NameError+ is raised. @@ -2078,7 +2074,7 @@ rb_mod_attr_accessor(int argc, VALUE *ar https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L2074 * Object.const_get 'Foo::Baz::VAL' # => 10 * Object.const_get 'Foo::Baz::VAL', false # => NameError * - * If neither +sym+ nor +str+ is not a valid constant name a NameError will be + * If the argument is not a valid constant name a +NameError+ will be * raised with a warning "wrong constant name". * * Object.const_get 'foobar' #=> NameError: wrong constant name foobar @@ -2190,7 +2186,7 @@ rb_mod_const_get(int argc, VALUE *argv, https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L2186 * Math.const_set("HIGH_SCHOOL_PI", 22.0/7.0) #=> 3.14285714285714 * Math::HIGH_SCHOOL_PI - Math::PI #=> 0.00126448926734968 * - * If neither +sym+ nor +str+ is not a valid constant name a NameError will be + * If +sym+ or +str+ is not a valid constant name a +NameError+ will be * raised with a warning "wrong constant name". * * Object.const_set('foobar', 42) #=> NameError: wrong constant name foobar @@ -2210,20 +2206,39 @@ rb_mod_const_set(VALUE mod, VALUE name, https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L2206 * mod.const_defined?(sym, inherit=true) -> true or false * mod.const_defined?(str, inherit=true) -> true or false * - * Checks for a constant with the given name in <i>mod</i> - * If +inherit+ is set, the lookup will also search - * the ancestors (and +Object+ if <i>mod</i> is a +Module+.) + * Says whether _mod_ or its ancestors have a constant with the given name: * - * Returns whether or not a definition is found: + * Float.const_defined?(:EPSILON) #=> true, found in Float itself + * Float.const_defined?("String") #=> true, found in Object (ancestor) + * BasicObject.const_defined?(:Hash) #=> false * - * Math.const_defined? "PI" #=> true - * IO.const_defined? :SYNC #=> true - * IO.const_defined? :SYNC, false #=> false + * If _mod_ is a +Module+, additionally +Object+ and its ancestors are checked: * - * If neither +sym+ nor +str+ is not a valid constant name a NameError will be - * raised with a warning "wrong constant name". + * Math.const_defined?(:String) #=> true, found in Object + * + * In each of the checked classes or modules, if the constant is not present + * but there is an autoload for it, +true+ is returned directly without + * autoloading: + * + * module Admin + * autoload :User, 'admin/user' + * end + * Admin.const_defined?(:User) #=> true + * + * If the constant is not found the callback +const_missing+ is *not* called + * and the method returns +false+. + * + * If +inherit+ is false, the lookup only checks the constants in the receiver: * - * Hash.const_defined? 'foobar' #=> NameError: wrong constant name foobar + * IO.const_defined?(:SYNC) #=> true, found in File::Constants (ancestor) + * IO.const_defined?(:SYNC, false) #=> false, not found in IO itself + * + * In this case, the same logic for autoloading applies. + * + * If the argument is not a valid constant name a +NameError+ is raised with the + * message "wrong constant name _name_": + * + * Hash.const_defined? 'foobar' #=> NameError: wrong constant name foobar * */ @@ -2373,10 +2388,10 @@ rb_obj_ivar_get(VALUE obj, VALUE iv) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L2388 * obj.instance_variable_set(symbol, obj) -> obj * obj.instance_variable_set(string, obj) -> obj * - * Sets the instance variable names by <i>symbol</i> to - * <i>object</i>, thereby frustrating the efforts of the class's + * Sets the instance variable named by <i>symbol</i> to the given + * object, thereby frustrating the efforts of the class's * author to attempt to provide proper encapsulation. The variable - * did not have to exist prior to this call. + * does not have to exist prior to this call. * If the instance variable name is passed as a string, that string * is converted to a symbol. * @@ -2446,7 +2461,7 @@ rb_obj_ivar_defined(VALUE obj, VALUE iv) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L2461 * * Returns the value of the given class variable (or throws a * <code>NameError</code> exception). The <code>@@</code> part of the - * variable name should be included for regular class variables + * variable name should be included for regular class variables. * String arguments are converted to symbols. * * class Fred @@ -2482,8 +2497,8 @@ rb_mod_cvar_get(VALUE obj, VALUE iv) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L2497 * obj.class_variable_set(symbol, obj) -> obj * obj.class_variable_set(string, obj) -> obj * - * Sets the class variable names by <i>symbol</i> to - * <i>object</i>. + * Sets the class variable named by <i>symbol</i> to the given + * object. * If the class variable name is passed as a string, that string * is converted to a symbol. * @@ -2740,24 +2755,26 @@ rb_Integer(VALUE val) https://github.com/ruby/ruby/blob/trunk/ruby_2_1/object.c#L2755 /* * call-seq: - * Integer(arg,base=0) -> integer + * Integer(arg, base=0) -> integer * * Converts <i>arg</i> to a <code>Fixnum</code> or <code>Bignum</code>. * Numeric types are converted directly (with floating point numbers - * being truncated). <i>base</i> (0, or between 2 and 36) is a base for + * being truncated). <i>base</i> (0, or between 2 and 36) is a base for * integer string representation. If <i>arg</i> is a <code>String</code>, - * when <i>base</i> is omitted or equals to zero, radix indicators + * when <i>base</i> is omitted or equals zero, radix indicators * (<code>0</code>, <code>0b</code>, and <code>0x</code>) are honored. * In any case, strings should be strictly conformed to numeric * representation. This behavior is different from that of - * (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/