From 56557ec28a8712984a0e9744fd7547e797ec9b6b Mon Sep 17 00:00:00 2001 From: nobu Date: Fri, 22 Mar 2019 11:04:59 +0000 Subject: [DOC] fix markups [ci skip] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@67337 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- object.c | 153 +++++++++++++++++++++++++++++++-------------------------------- 1 file changed, 75 insertions(+), 78 deletions(-) (limited to 'object.c') 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 -- cgit v1.2.3