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
This commit is contained in:
nobu 2014-12-09 09:20:05 +00:00
Родитель 3992aaa36c
Коммит 9e256261b3
2 изменённых файлов: 82 добавлений и 73 удалений

Просмотреть файл

@ -1,3 +1,18 @@
Tue Dec 9 18:20:02 2014 Nobuyoshi Nakada <nobu@ruby-lang.org>
* 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@gmail.com>
* vm_eval.c (rb_eval_string_wrap): [DOC] Fix `rb_eval_string_wrap`

140
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 <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)
* 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)
* 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)
* 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 <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)
/*
* 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 <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 recur)
* 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 c)
* 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)
* class Baz < Bar
* end
*
* produces:
* <em>produces:</em>
*
* New subclass: Bar
* New subclass: Baz
@ -739,7 +733,7 @@ rb_obj_tap(VALUE obj)
* def some_instance_method() end
* end
*
* produces:
* <em>produces:</em>
*
* Adding :some_instance_method
*
@ -765,7 +759,7 @@ rb_obj_tap(VALUE obj)
* remove_method :some_instance_method
* end
*
* produces:
* <em>produces:</em>
*
* 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 <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)
/*
* 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)
* 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)
* 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 <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)
* 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 arg)
* 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)
* 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)
* 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 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 <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 *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 <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)
*
* 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)
* 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)
/*
* 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)
* 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)
* 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)
*
* 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)
* 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)
* <code>Class</code>:
*
* class Class
* alias oldNew new
* def new(*args)
* print "Creating a new ", self.name, "\n"
* oldNew(*args)
* end
* end
* alias old_new new
* def new(*args)
* print "Creating a new ", self.name, "\n"
* old_new(*args)
* end
* end
*
* class Name
* end
*
* class Name
* end
*
*
* n = Name.new
* n = Name.new
*
* <em>produces:</em>
*
@ -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