From 9e256261b3d5118e547ab73ae2234e4f1d124177 Mon Sep 17 00:00:00 2001 From: nobu Date: Tue, 9 Dec 2014 09:20:05 +0000 Subject: 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. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@48746 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- object.c | 140 ++++++++++++++++++++++++++++++--------------------------------- 1 file changed, 67 insertions(+), 73 deletions(-) (limited to 'object.c') diff --git a/object.c b/object.c index 446d52a1d6..d771e1e115 100644 --- a/object.c +++ b/object.c @@ -155,7 +155,7 @@ rb_obj_equal(VALUE obj1, VALUE obj2) * 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) * obj.singleton_class -> class * * Returns the singleton class of obj. This method creates - * a new singleton class if obj does not have it. + * a new singleton class if obj does not have one. * * If obj is nil, true, or * false, it returns NilClass, TrueClass, or FalseClass, @@ -299,9 +299,9 @@ init_copy(VALUE dest, VALUE obj) * obj.clone -> an_object * * Produces a shallow copy of obj---the instance variables of - * obj are copied, but not the objects they reference. Copies - * the frozen and tainted state of obj. See also the discussion - * under Object#dup. + * obj are copied, but not the objects they reference. + * clone copies the frozen and tainted state of obj. + * See also the discussion under Object#dup. * * class Klass * attr_accessor :str @@ -349,8 +349,8 @@ rb_obj_clone(VALUE obj) * obj.dup -> an_object * * 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. + * obj are copied, but not the objects they reference. + * 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 @@ -364,7 +364,7 @@ rb_obj_clone(VALUE obj) * 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 orig) * 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.'' + * initial execution context of Ruby programs returns ``main''. */ VALUE @@ -464,7 +464,7 @@ rb_any_to_s(VALUE obj) /* * 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 recur) * obj.inspect -> string * * Returns a string containing a human-readable representation of obj. - * By default, show the class name and the list of the instance variables and + * 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 make better + * 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. @@ -547,13 +548,6 @@ inspect_obj(VALUE obj, VALUE str, int recur) * end * end * Bar.new.inspect #=> "#" - * - * class Baz - * def to_s - * "baz" - * end - * end - * Baz.new.inspect #=> "#" */ static VALUE @@ -676,14 +670,14 @@ rb_class_search_ancestor(VALUE cl, VALUE c) * call-seq: * obj.tap{|x|...} -> obj * - * Yields x to the block, and then returns x. + * 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) * class Baz < Bar * end * - * produces: + * produces: * * New subclass: Bar * New subclass: Baz @@ -739,7 +733,7 @@ rb_obj_tap(VALUE obj) * def some_instance_method() end * end * - * produces: + * produces: * * Adding :some_instance_method * @@ -765,7 +759,7 @@ rb_obj_tap(VALUE obj) * remove_method :some_instance_method * end * - * produces: + * produces: * * Removing :some_instance_method * @@ -953,13 +947,13 @@ rb_obj_tainted(VALUE obj) * * 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) * call-seq: * true | obj -> true * - * Or---Returns true. As anObject is an argument to + * Or---Returns true. As obj 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) /* * call-seq: - * nil.nil? -> true - * .nil? -> false + * obj.nil? -> true or false * * Only the object nil responds true to nil?. + * + * Object.new.nil? #=> false + * nil.nil? #=> true */ @@ -1442,7 +1438,7 @@ rb_obj_cmp(VALUE obj1, VALUE obj2) * 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 @@ -1465,7 +1461,7 @@ rb_obj_cmp(VALUE obj1, VALUE obj2) * 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) * call-seq: * mod === obj -> true or false * - * Case Equality---Returns true if anObject is an + * Case Equality---Returns true if obj is an * instance of mod or one of mod's descendants. Of * limited use for modules, but can be used in case * statements to classify objects by class. @@ -1545,7 +1541,7 @@ rb_mod_eqq(VALUE mod, VALUE arg) * is the same as other. Returns * nil if there's no relationship between the two. * (Think of the relationship in terms of the class definition: - * "class Amod is a subclass of other. Returns * nil if there's no relationship between the two. * (Think of the relationship in terms of the class definition: - * "class Anil if there's no relationship between the two. * (Think of the relationship in terms of the class definition: - * "class AA"). + * "class AA".) * */ @@ -1617,7 +1613,7 @@ rb_mod_ge(VALUE mod, VALUE arg) * Returns true if mod is an ancestor of other. Returns * nil if there's no relationship between the two. * (Think of the relationship in terms of the class definition: - * "class AA"). + * "class AA".) * */ @@ -1875,7 +1871,7 @@ rb_class_new_instance(int argc, const VALUE *argv, VALUE klass) * 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 *argv, VALUE klass) * mod.const_get(sym, inherit=true) -> obj * mod.const_get(str, inherit=true) -> obj * - * Checks for a constant with the given name in mod + * Checks for a constant with the given name in mod. * If +inherit+ is set, the lookup will also search - * the ancestors (and +Object+ if mod is a +Module+.) + * the ancestors (and +Object+ if mod 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 *argv, VALUE klass) * 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, VALUE mod) * 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, VALUE value) * * 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) * obj.instance_variable_set(symbol, obj) -> obj * obj.instance_variable_set(string, obj) -> obj * - * Sets the instance variable names by symbol to - * object, thereby frustrating the efforts of the class's + * Sets the instance variable named by symbol 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) * * Returns the value of the given class variable (or throws a * NameError exception). The @@ 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) * obj.class_variable_set(symbol, obj) -> obj * obj.class_variable_set(string, obj) -> obj * - * Sets the class variable names by symbol to - * object. + * Sets the class variable named by symbol 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) /* * call-seq: - * Integer(arg,base=0) -> integer + * Integer(arg, base=0) -> integer * * Converts arg to a Fixnum or Bignum. * Numeric types are converted directly (with floating point numbers - * being truncated). base (0, or between 2 and 36) is a base for + * being truncated). base (0, or between 2 and 36) is a base for * integer string representation. If arg is a String, - * when base is omitted or equals to zero, radix indicators + * 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 using - * to_int, and to_i. Passing nil + * String#to_i. Non string values will be converted by first + * trying to_int, then to_i. Passing nil * raises a TypeError. * * Integer(123.999) #=> 123 @@ -2951,8 +2947,8 @@ rb_Float(VALUE val) * Float(arg) -> float * * Returns arg converted to a float. Numeric types are converted - * directly, the rest are converted using arg.to_f. As of Ruby - * 1.8, converting nil generates a TypeError. + * directly, the rest are converted using arg.to_f. + * Converting nil generates a TypeError. * * Float(1) #=> 1.0 * Float("123.456") #=> 123.456 @@ -3024,7 +3020,7 @@ rb_String(VALUE val) * call-seq: * String(arg) -> string * - * Returns arg as an String. + * Returns arg as a String. * * First tries to call its to_str method, then its to_s method. * @@ -3059,7 +3055,7 @@ rb_Array(VALUE val) * * Returns +arg+ as an Array. * - * First tries to call Array#to_ary on +arg+, then Array#to_a. + * First tries to call to_ary on +arg+, then to_a. * * Array(1..5) #=> [1, 2, 3, 4, 5] */ @@ -3114,7 +3110,7 @@ rb_f_hash(VALUE obj, VALUE arg) * 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) * Class: * * 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 * * produces: * @@ -3146,7 +3140,7 @@ rb_f_hash(VALUE obj, VALUE arg) * * 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. All metaclasses are instances * of the class `Class'. * +---------+ +-... * | | | @@ -3207,7 +3201,7 @@ rb_f_hash(VALUE obj, VALUE arg) * * BasicObject does not include Kernel (for methods like +puts+) and * BasicObject is outside of the namespace of the standard library so common - * classes will not be found without a using a full class path. + * classes will not be found without using a full class path. * * A variety of strategies can be used to provide useful portions of the * standard library to subclasses of BasicObject. A subclass could @@ -3245,7 +3239,7 @@ rb_f_hash(VALUE obj, VALUE arg) * * Object is the default root of all Ruby objects. Object inherits from * BasicObject which allows creating alternate object hierarchies. Methods - * on object are available to all classes unless explicitly overridden. + * on Object are available to all classes unless explicitly overridden. * * Object mixes in the Kernel module, making the built-in kernel functions * globally accessible. Although the instance methods of Object are defined -- cgit v1.2.3