ruby-changes:36665
From: nobu <ko1@a...>
Date: Tue, 9 Dec 2014 18:20:21 +0900 (JST)
Subject: [ruby-changes:36665] nobu:r48746 (trunk): object.c: [DOC] Revise documentation
nobu 2014-12-09 18:20:05 +0900 (Tue, 09 Dec 2014) New Revision: 48746 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=48746 Log: object.c: [DOC] Revise documentation * 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 files: trunk/ChangeLog trunk/object.c Index: ChangeLog =================================================================== --- ChangeLog (revision 48745) +++ ChangeLog (revision 48746) @@ -1,3 +1,18 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Tue Dec 9 18:20:02 2014 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. + Tue Dec 9 12:48:32 2014 Josef Simanek <josef.simanek@g...> * vm_eval.c (rb_eval_string_wrap): [DOC] Fix `rb_eval_string_wrap` Index: object.c =================================================================== --- object.c (revision 48745) +++ object.c (revision 48746) @@ -155,7 +155,7 @@ rb_obj_equal(VALUE obj1, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/object.c#L155 * 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/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, @@ -299,9 +299,9 @@ init_copy(VALUE dest, VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L299 * 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 @@ -349,8 +349,8 @@ rb_obj_clone(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L349 * 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 @@ -364,7 +364,7 @@ rb_obj_clone(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L364 * 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 @@ -447,7 +447,7 @@ rb_obj_init_dup_clone(VALUE obj, VALUE o https://github.com/ruby/ruby/blob/trunk/object.c#L447 * 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 @@ -464,7 +464,7 @@ rb_any_to_s(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L464 /* * 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. */ @@ -527,9 +527,10 @@ inspect_obj(VALUE obj, VALUE str, int re https://github.com/ruby/ruby/blob/trunk/object.c#L527 * 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. @@ -547,13 +548,6 @@ inspect_obj(VALUE obj, VALUE str, int re https://github.com/ruby/ruby/blob/trunk/object.c#L548 * end * end * Bar.new.inspect #=> "#<Bar:0x0300c868 @bar=1>" - * - * class Baz - * def to_s - * "baz" - * end - * end - * Baz.new.inspect #=> "#<Baz:0x0300c868>" */ static VALUE @@ -676,14 +670,14 @@ rb_class_search_ancestor(VALUE cl, VALUE https://github.com/ruby/ruby/blob/trunk/object.c#L670 * 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}"} * */ @@ -717,7 +711,7 @@ rb_obj_tap(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L711 * class Baz < Bar * end * - * produces: + * <em>produces:</em> * * New subclass: Bar * New subclass: Baz @@ -739,7 +733,7 @@ rb_obj_tap(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L733 * def some_instance_method() end * end * - * produces: + * <em>produces:</em> * * Adding :some_instance_method * @@ -765,7 +759,7 @@ rb_obj_tap(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L759 * remove_method :some_instance_method * end * - * produces: + * <em>produces:</em> * * Removing :some_instance_method * @@ -953,13 +947,13 @@ rb_obj_tainted(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L947 * * 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. @@ -1238,7 +1232,7 @@ true_and(VALUE obj, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/object.c#L1232 * 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. * @@ -1362,10 +1356,12 @@ rb_true(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L1356 /* * 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 */ @@ -1442,7 +1438,7 @@ rb_obj_cmp(VALUE obj1, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/object.c#L1438 * 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 @@ -1465,7 +1461,7 @@ rb_obj_cmp(VALUE obj1, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/object.c#L1461 * 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. */ @@ -1525,7 +1521,7 @@ rb_mod_freeze(VALUE mod) https://github.com/ruby/ruby/blob/trunk/object.c#L1521 * 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. @@ -1545,7 +1541,7 @@ rb_mod_eqq(VALUE mod, VALUE arg) https://github.com/ruby/ruby/blob/trunk/object.c#L1541 * 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".) * */ @@ -1576,7 +1572,7 @@ rb_class_inherited_p(VALUE mod, VALUE ar https://github.com/ruby/ruby/blob/trunk/object.c#L1572 * 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".) * */ @@ -1596,7 +1592,7 @@ rb_mod_lt(VALUE mod, VALUE arg) https://github.com/ruby/ruby/blob/trunk/object.c#L1592 * 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".) * */ @@ -1617,7 +1613,7 @@ rb_mod_ge(VALUE mod, VALUE arg) https://github.com/ruby/ruby/blob/trunk/object.c#L1613 * 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, const VA https://github.com/ruby/ruby/blob/trunk/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 * @@ -2056,9 +2052,9 @@ rb_mod_attr_accessor(int argc, VALUE *ar https://github.com/ruby/ruby/blob/trunk/object.c#L2052 * 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. @@ -2084,7 +2080,7 @@ rb_mod_attr_accessor(int argc, VALUE *ar https://github.com/ruby/ruby/blob/trunk/object.c#L2080 * 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 @@ -2193,7 +2189,7 @@ rb_mod_const_get(int argc, VALUE *argv, https://github.com/ruby/ruby/blob/trunk/object.c#L2189 * 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 @@ -2242,7 +2238,7 @@ rb_mod_const_set(VALUE mod, VALUE name, https://github.com/ruby/ruby/blob/trunk/object.c#L2238 * * In this case, the same logic for autoloading applies. * - * If the argument is not a valid constant name +NameError+ is raised with the + * 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 @@ -2390,10 +2386,10 @@ rb_obj_ivar_get(VALUE obj, VALUE iv) https://github.com/ruby/ruby/blob/trunk/object.c#L2386 * 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. * @@ -2463,7 +2459,7 @@ rb_obj_ivar_defined(VALUE obj, VALUE iv) https://github.com/ruby/ruby/blob/trunk/object.c#L2459 * * 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 @@ -2499,8 +2495,8 @@ rb_mod_cvar_get(VALUE obj, VALUE iv) https://github.com/ruby/ruby/blob/trunk/object.c#L2495 * 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. * @@ -2766,18 +2762,18 @@ rb_Integer(VALUE val) https://github.com/ruby/ruby/blob/trunk/object.c#L2762 /* * 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 - * <code>String#to_i</code>. Non string values will be converted using - * <code>to_int</code>, and <code>to_i</code>. Passing <code>nil</code> + * <code>String#to_i</code>. Non string values will be converted by first + * trying <code>to_int</code>, then <code>to_i</code>. Passing <code>nil</code> * raises a TypeError. * * Integer(123.999) #=> 123 @@ -2951,8 +2947,8 @@ rb_Float(VALUE val) https://github.com/ruby/ruby/blob/trunk/object.c#L2947 * Float(arg) -> float * * Returns <i>arg</i> converted to a float. Numeric types are converted - * directly, the rest are converted using <i>arg</i>.to_f. As of Ruby - * 1.8, converting <code>nil</code> generates a <code>TypeError</code>. + * directly, the rest are converted using <i>arg</i>.to_f. + * Converting <code>nil</code> generates a <code>TypeError</code>. * * Float(1) #=> 1.0 * Float("123.456") #=> 123.456 @@ -3024,7 +3020,7 @@ rb_String(VALUE val) https://github.com/ruby/ruby/blob/trunk/object.c#L3020 * call-seq: * String(arg) -> string * - * Returns <i>arg</i> as an <code>String</code>. + * Returns <i>arg</i> as a <code>String</code>. * * First tries to call its <code>to_str</code> method, then its <code>to_s</code> method. * @@ -3059,7 +3055,7 @@ rb_Array(VALUE val) https://github.com/ruby/ruby/blob/trunk/object.c#L3055 * * Returns +arg+ as an Array. * - * First tries to call Array#to_ary on +arg+, then Array#to_a. + * First tries to call <code>to_ary</code> on +arg+, then <code>to_a</code>. * * Array(1..5) #=> [1, 2, 3, 4, 5] */ @@ -3114,7 +3110,7 @@ rb_f_hash(VALUE obj, VALUE arg) https://github.com/ruby/ruby/blob/trunk/object.c#L3110 * Typically, you create a new class by using: * * class Name - * # some class describing the class behavior + * # some code describing the class behavior * end * * When a new class is created, an object of type Class is initialized and @@ -3126,19 +3122,17 @@ rb_f_hash(VALUE obj, VALUE arg) https://github.com/ruby/ruby/blob/trunk/object.c#L3122 * <code>Class</code>: * * class Class - * alias oldNew new - * def new(*args) - * print "Creating a new ", self.name, "\n" - * oldNew(*args) - * end - * end - * - * - * class Name - * end + * alias old_new new + * def new(*args) + * print "Creating a new ", self.name, "\n" + * old_new(*args) + * end + * end * + * class Name + * end * - * n = Name.new + * n = Name.new * * <em>produces:</em> * @@ -3146,7 +3140,7 @@ rb_f_hash(VALUE obj, VALUE arg) https://github.com/ruby/ruby/blob/trunk/object.c#L3140 * * Classes, modules, and objects are interrelated. In the diagram * that follows, the vertical arrows represent inheritance, and the - * parentheses meta-classes. All metaclasses are instances + * parentheses metaclasses (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/