ruby-changes:47274
From: yugui <ko1@a...>
Date: Sat, 22 Jul 2017 15:31:01 +0900 (JST)
Subject: [ruby-changes:47274] yugui:r59389 (trunk): Add documents
yugui 2017-07-22 15:30:53 +0900 (Sat, 22 Jul 2017) New Revision: 59389 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=59389 Log: Add documents Modified files: trunk/include/ruby/ruby.h trunk/object.c trunk/template/Doxyfile.tmpl Index: include/ruby/ruby.h =================================================================== --- include/ruby/ruby.h (revision 59388) +++ include/ruby/ruby.h (revision 59389) @@ -1272,6 +1272,11 @@ int rb_big_sign(VALUE); https://github.com/ruby/ruby/blob/trunk/include/ruby/ruby.h#L1272 #define RB_OBJ_FREEZE_RAW(x) (void)(RBASIC(x)->flags |= RUBY_FL_FREEZE) #define RB_OBJ_FREEZE(x) rb_obj_freeze_inline((VALUE)x) +/*! + * \defgroup deprecated_macros deprecated macro APIs + * \{ + * \par These macros are deprecated. Prefer their `RB_`-prefixed versions. + */ #define FL_ABLE(x) RB_FL_ABLE(x) #define FL_TEST_RAW(x,f) RB_FL_TEST_RAW(x,f) #define FL_TEST(x,f) RB_FL_TEST(x,f) @@ -1300,6 +1305,8 @@ int rb_big_sign(VALUE); https://github.com/ruby/ruby/blob/trunk/include/ruby/ruby.h#L1305 #define OBJ_FREEZE_RAW(x) RB_OBJ_FREEZE_RAW(x) #define OBJ_FREEZE(x) RB_OBJ_FREEZE(x) +/* \} */ + void rb_freeze_singleton_class(VALUE klass); static inline void @@ -1652,7 +1659,7 @@ rb_alloc_tmp_buffer2(volatile VALUE *sto https://github.com/ruby/ruby/blob/trunk/include/ruby/ruby.h#L1659 #define MEMMOVE(p1,p2,type,n) memmove((p1), (p2), sizeof(type)*(size_t)(n)) #define MEMCMP(p1,p2,type,n) memcmp((p1), (p2), sizeof(type)*(size_t)(n)) -void rb_obj_infect(VALUE,VALUE); +void rb_obj_infect(VALUE victim, VALUE carrier); typedef int ruby_glob_func(const char*,VALUE, void*); void rb_glob(const char*,void(*)(const char*,VALUE,void*),VALUE); Index: template/Doxyfile.tmpl =================================================================== --- template/Doxyfile.tmpl (revision 59388) +++ template/Doxyfile.tmpl (revision 59389) @@ -61,7 +61,7 @@ SYMBOL_CACHE_SIZE = 0 https://github.com/ruby/ruby/blob/trunk/template/Doxyfile.tmpl#L61 #--------------------------------------------------------------------------- EXTRACT_ALL = YES EXTRACT_PRIVATE = NO -EXTRACT_STATIC = YES +EXTRACT_STATIC = NO EXTRACT_LOCAL_CLASSES = YES EXTRACT_LOCAL_METHODS = NO EXTRACT_ANON_NSPACES = NO @@ -69,7 +69,7 @@ HIDE_UNDOC_MEMBERS = NO https://github.com/ruby/ruby/blob/trunk/template/Doxyfile.tmpl#L69 HIDE_UNDOC_CLASSES = NO HIDE_FRIEND_COMPOUNDS = NO HIDE_IN_BODY_DOCS = YES -INTERNAL_DOCS = YES +INTERNAL_DOCS = NO CASE_SENSE_NAMES = NO HIDE_SCOPE_NAMES = NO SHOW_INCLUDE_FILES = YES @@ -104,7 +104,7 @@ WARN_LOGFILE = https://github.com/ruby/ruby/blob/trunk/template/Doxyfile.tmpl#L104 INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.c *.h *.y *.def RECURSIVE = YES -EXCLUDE = ext/dl/callback ccan +EXCLUDE = <%=srcdir%>/ext/dl/callback <%=srcdir%>/ccan <%=srcdir%>/ext/psych/yaml EXCLUDE_SYMLINKS = YES EXCLUDE_PATTERNS = *.src doc enc build */ext/-test-/* tmp test yarvtest lib bootstraptest spec .ext .git .svn extconf.h *prelude.c encdb.h transdb.h insns.def EXCLUDE_SYMBOLS = Index: object.c =================================================================== --- object.c (revision 59388) +++ object.c (revision 59389) @@ -23,16 +23,23 @@ https://github.com/ruby/ruby/blob/trunk/object.c#L23 #include "id.h" #include "probes.h" -VALUE rb_cBasicObject; -VALUE rb_mKernel; -VALUE rb_cObject; -VALUE rb_cModule; -VALUE rb_cClass; -VALUE rb_cData; - -VALUE rb_cNilClass; -VALUE rb_cTrueClass; -VALUE rb_cFalseClass; +/*! + * \defgroup object Core objects and their operations + * \{ + */ + +VALUE rb_cBasicObject; /*!< BasicObject class */ +VALUE rb_mKernel; /*!< Kernel module */ +VALUE rb_cObject; /*!< Object class */ +VALUE rb_cModule; /*!< Module class */ +VALUE rb_cClass; /*!< Class class */ +VALUE rb_cData; /*!< Data class */ + +VALUE rb_cNilClass; /*!< NilClass class */ +VALUE rb_cTrueClass; /*!< TrueClass class */ +VALUE rb_cFalseClass; /*!< FalseClass class */ + +/*! \cond INTERNAL_MACRO */ #define id_eq idEq #define id_eql idEqlP @@ -47,6 +54,20 @@ VALUE rb_cFalseClass; https://github.com/ruby/ruby/blob/trunk/object.c#L54 (!SPECIAL_CONST_P(obj) && \ (BUILTIN_TYPE(obj) == T_CLASS || BUILTIN_TYPE(obj) == T_MODULE)) +/*! \endcond */ + +/*! + * Make the object invisible from Ruby code. + * + * It is useful to let Ruby's GC manage your internal data structure -- + * The object keeps being managed by GC, but \c ObjectSpace#each_objects + * never yields the object. + * + * Note that the object also lose a way to call a method on it. + * + * \param[in] obj a Ruby object + * \sa rb_obj_reveal + */ VALUE rb_obj_hide(VALUE obj) { @@ -56,6 +77,14 @@ rb_obj_hide(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L77 return obj; } +/*! + * Make a hidden object visible again. + * + * It is the caller's responsibility to pass the right \a klass + * which \a obj originally used to belong to. + * + * \sa rb_obj_hide + */ VALUE rb_obj_reveal(VALUE obj, VALUE klass) { @@ -65,6 +94,14 @@ rb_obj_reveal(VALUE obj, VALUE klass) https://github.com/ruby/ruby/blob/trunk/object.c#L94 return obj; } +/*! + * Fills common (\c RBasic) fields in \a obj. + * + * \note Prefer rb_newobj_of() to this function. + * \param[in,out] obj a Ruby object to be set up. + * \param[in] klass \c obj will belong to this class. + * \param[in] type one of \c ruby_value_type + */ VALUE rb_obj_setup(VALUE obj, VALUE klass, VALUE type) { @@ -73,13 +110,16 @@ rb_obj_setup(VALUE obj, VALUE klass, VAL https://github.com/ruby/ruby/blob/trunk/object.c#L110 return obj; } -/* +/** * call-seq: * obj === other -> true or false * * Case Equality -- For class Object, effectively the same as calling * <code>#==</code>, but typically overridden by descendants to provide * meaningful semantics in +case+ statements. + *-- + * Same as \c Object#===, case equality. + *++ */ VALUE @@ -96,6 +136,15 @@ rb_equal(VALUE obj1, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/object.c#L136 return Qfalse; } +/** + * Determines if \a obj1 and \a obj2 are equal in terms of + * \c Object#eql?. + * + * \note It actually calls \c #eql? when necessary. + * So you cannot implement \c #eql? with this function. + * \retval non-zero if they are eql? + * \retval zero if they are not eql?. + */ int rb_eql(VALUE obj1, VALUE obj2) { @@ -110,7 +159,7 @@ rb_eql(VALUE obj1, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/object.c#L159 return Qfalse; } -/* +/** * call-seq: * obj == other -> true or false * obj.equal?(other) -> true or false @@ -144,8 +193,10 @@ rb_eql(VALUE obj1, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/object.c#L193 * * 1 == 1.0 #=> true * 1.eql? 1.0 #=> false + *-- + * \private + *++ */ - VALUE rb_obj_equal(VALUE obj1, VALUE obj2) { @@ -153,45 +204,16 @@ rb_obj_equal(VALUE obj1, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/object.c#L204 return Qfalse; } -#if 0 -/* - * call-seq: - * obj.hash -> integer - * - * Generates an Integer hash value for this object. This function must have the - * property that <code>a.eql?(b)</code> implies <code>a.hash == b.hash</code>. - * - * The hash value is used along with #eql? by the Hash class to determine if - * two objects reference the same hash key. Any hash value that exceeds the - * capacity of an Integer 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 - * invocations and implementations you will need to generate one with a custom - * method. - */ -VALUE -rb_obj_hash(VALUE obj) -{ - VALUE oid = rb_obj_id(obj); -#if SIZEOF_LONG == SIZEOF_VOIDP - st_index_t index = NUM2LONG(oid); -#elif SIZEOF_LONG_LONG == SIZEOF_VOIDP - st_index_t index = NUM2LL(oid); -#else -# error not supported -#endif - return LONG2FIX(rb_objid_hash(index)); -} -#else VALUE rb_obj_hash(VALUE obj); -#endif -/* +/** * call-seq: * !obj -> true or false * * Boolean negate. + *-- + * \private + *++ */ VALUE @@ -200,11 +222,14 @@ rb_obj_not(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L222 return RTEST(obj) ? Qfalse : Qtrue; } -/* +/** * call-seq: * obj != other -> true or false * * Returns true if two objects are not-equal, otherwise false. + *-- + * \private + *++ */ VALUE @@ -214,6 +239,14 @@ rb_obj_not_equal(VALUE obj1, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/object.c#L239 return RTEST(result) ? Qfalse : Qtrue; } +/*! + * Looks up the nearest ancestor of \a cl, skipping singleton classes or + * module inclusions. + * It returns the \a cl itself if it is neither a singleton class or a module. + * + * \param[in] cl a Class object. + * \return the ancestor class found, or a falsthy vaule if nothing found. + */ VALUE rb_class_real(VALUE cl) { @@ -224,7 +257,7 @@ rb_class_real(VALUE cl) https://github.com/ruby/ruby/blob/trunk/object.c#L257 return cl; } -/* +/** * call-seq: * obj.class -> class * @@ -234,8 +267,12 @@ rb_class_real(VALUE cl) https://github.com/ruby/ruby/blob/trunk/object.c#L267 * * 1.class #=> Integer * self.class #=> Object + *-- + * Equivalent to \c Object\#class in Ruby. + * + * Returns the class of \c obj, skipping singleton classes or module inclusions. + *++ */ - VALUE rb_obj_class(VALUE obj) { @@ -265,6 +302,7 @@ rb_obj_singleton_class(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L302 return rb_singleton_class(obj); } +/*! \private */ void rb_obj_copy_ivar(VALUE dest, VALUE obj) { @@ -311,7 +349,7 @@ init_copy(VALUE dest, VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L349 static int freeze_opt(int argc, VALUE *argv); static VALUE immutable_obj_clone(VALUE obj, int kwfreeze); static VALUE mutable_obj_clone(VALUE obj, int kwfreeze); -PUREFUNC(static inline int special_object_p(VALUE obj)); +PUREFUNC(static inline int special_object_p(VALUE obj)); /*!< \private */ static inline int special_object_p(VALUE obj) { @@ -363,6 +401,7 @@ rb_obj_clone2(int argc, VALUE *argv, VAL https://github.com/ruby/ruby/blob/trunk/object.c#L401 return immutable_obj_clone(obj, kwfreeze); } +/*! \private */ VALUE rb_immutable_obj_clone(int argc, VALUE *argv, VALUE obj) { @@ -426,6 +465,12 @@ mutable_obj_clone(VALUE obj, int kwfreez https://github.com/ruby/ruby/blob/trunk/object.c#L465 return clone; } +/** + * :nodoc + *-- + * Almost same as \c Object#clone + *++ + */ VALUE rb_obj_clone(VALUE obj) { @@ -433,7 +478,7 @@ rb_obj_clone(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L478 return mutable_obj_clone(obj, Qtrue); } -/* +/** * call-seq: * obj.dup -> an_object * @@ -473,9 +518,10 @@ rb_obj_clone(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L518 * * s3 = s1.dup #=> #<Klass:0x401b3a38> * s3.foo #=> NoMethodError: undefined method `foo' for #<Klass:0x401b3a38> - * + *-- + * Equivalent to \c Object\#dup in Ruby + *++ */ - VALUE rb_obj_dup(VALUE obj) { @@ -532,7 +578,14 @@ rb_obj_yield_self(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L578 return rb_yield_values2(1, &obj); } -/* :nodoc: */ +/** + * :nodoc: + *-- + * Default implemenentation of \c #initialize_copy + * \param[in,out] obj the receiver being initialized + * \param[in] orig the object to be copied from. + *++ + */ VALUE rb_obj_init_copy(VALUE obj, VALUE orig) { @@ -545,7 +598,15 @@ rb_obj_init_copy(VALUE obj, VALUE orig) https://github.com/ruby/ruby/blob/trunk/object.c#L598 return obj; } -/* :nodoc: */ +/*! + * :nodoc: + *-- + * Default implementation of \c #initialize_dup and \c #initialize_clone + * + * \param[in,out] obj the receiver being initialized + * \param[in] orig the object to be dup or cloned from. + *++ + **/ VALUE rb_obj_init_dup_clone(VALUE obj, VALUE orig) { @@ -553,7 +614,7 @@ rb_obj_init_dup_clone(VALUE obj, VALUE o https://github.com/ruby/ruby/blob/trunk/object.c#L614 return obj; } -/* +/** * call-seq: * obj.to_s -> string * @@ -561,8 +622,11 @@ rb_obj_init_dup_clone(VALUE obj, VALUE o https://github.com/ruby/ruby/blob/trunk/object.c#L622 * <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''. + * + *-- + * Default implementation of \c #to_s. + *++ */ - VALUE rb_any_to_s(VALUE obj) { @@ -576,7 +640,13 @@ rb_any_to_s(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L640 } VALUE rb_str_escape(VALUE str); -/* +/*! + * Convenient wrapper of \c Object#inspect. + * Returns a human-readable strng representation of \a obj, + * similarly to \c Object#inspect. + * + * Unlike Ruby-level \c #inspect, it escapes characters to keep the + * result compatible to the default internal or external encoding. * If the default internal or external encoding is ASCII compatible, * the encoding of the inspected result must be compatible with it. * If the default internal or external encoding is ASCII incompatible, @@ -586,6 +656,7 @@ VALUE https://github.com/ruby/ruby/blob/trunk/object.c#L656 rb_inspect(VALUE obj) { VALUE str = rb_obj_as_string(rb_funcallv(obj, id_inspect, 0, 0)); + rb_encoding *enc = rb_default_internal_encoding(); if (enc == NULL) enc = rb_default_external_encoding(); if (!rb_enc_asciicompat(enc)) { @@ -699,7 +770,7 @@ class_or_module_required(VALUE c) https://github.com/ruby/ruby/blob/trunk/object.c#L770 static VALUE class_search_ancestor(VALUE cl, VALUE c); -/* +/** * call-seq: * obj.instance_of?(class) -> true or false * @@ -714,6 +785,13 @@ static VALUE class_search_ancestor(VALUE https://github.com/ruby/ruby/blob/trunk/object.c#L785 * b.instance_of? A #=> false * b.instance_of? B #=> true * b.instance_of? C #=> false + *-- + * Determines if \a obj is an instance of \a c. + * + * Equivalent to \c Object\#is_instance_of in Ruby. + * \param[in] obj the object to be determined. + * \param[in] c a Class object + *++ */ VALUE @@ -725,7 +803,7 @@ rb_obj_is_instance_of(VALUE obj, VALUE c https://github.com/ruby/ruby/blob/trunk/object.c#L803 } -/* +/** * call-seq: * obj.is_a?(class) -> true or false * obj.kind_of?(class) -> true or false @@ -751,6 +829,13 @@ rb_obj_is_instance_of(VALUE obj, VALUE c https://github.com/ruby/ruby/blob/trunk/object.c#L829 * b.kind_of? B #=> true * b.kind_of? C #=> false * b.kind_of? M #=> true + *-- + * Determines if \a obj is a kind of \a c. + * + * Equivalent to \c Object\#kind_of? in Ruby. + * \param[in] obj the object to be determined + * \param[in] c a Module object. + *++ */ VALUE @@ -773,6 +858,7 @@ class_search_ancestor(VALUE cl, VALUE c) https://github.com/ruby/ruby/blob/trunk/object.c#L858 return 0; } +/*! \private */ VALUE rb_class_search_ancestor(VALUE cl, VALUE c) { @@ -781,7 +867,7 @@ rb_class_search_ancestor(VALUE cl, VALUE https://github.com/ruby/ruby/blob/trunk/object.c#L867 return class_search_ancestor(cl, RCLASS_ORIGIN(c)); } -/* +/** * call-seq: * obj.tap {|x| block } -> obj * @@ -794,6 +880,9 @@ rb_class_search_ancestor(VALUE cl, VALUE https://github.com/ruby/ruby/blob/trunk/object.c#L880 * .select {|x| x.even? } .tap {|x| puts "evens: #{x}" } * .map {|x| x*x } .tap {|x| puts "squares: #{x}" } * + *-- + * \private + *++ */ VALUE @@ -1037,13 +1126,21 @@ rb_obj_dummy(void) https://github.com/ruby/ruby/blob/trunk/object.c#L1126 return Qnil; } -/* +/** * call-seq: * obj.tainted? -> true or false * * Returns true if the object is tainted. * * See #taint for more information. + *-- + * Determines if \a obj is tainted. Equivalent to \c Object\#tainted? in Ruby. + * \param[in] obj the object to be determined + * \retval Qtrue if the object is tainted + * \retval Qfalse if the object is not tainted + * \sa rb_obj_taint + * \sa rb_obj_untaint + *++ */ VALUE @@ -1054,7 +1151,7 @@ rb_obj_tainted(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L1151 return Qfalse; } -/* +/** * call-seq: * obj.taint -> obj * @@ -1069,6 +1166,13 @@ rb_obj_tainted(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L1166 * * You should only untaint a tainted object if your code has inspected it and * determined that it is safe. To do so use #untaint. + *-- + * Marks the object as tainted. Equivalent to \c Object\#taint in Ruby + * \param[in] obj the object to be tainted + * \return the object itself + * \sa rb_obj_untaint + * \sa rb_obj_tainted + *++ */ VALUE @@ -1082,13 +1186,22 @@ rb_obj_taint(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L1186 } -/* +/** * call-seq: * obj.untaint -> obj * * Removes the tainted mark from the object. * * See #taint for more information. + *-- + * Removes the tainted mark from the object. + * Equivalent to \c Object\#untaint in Ruby. + * + * \param[in] obj the object to be tainted + * \return the object itself + * \sa rb_obj_taint + * \sa rb_obj_tainted + *++ */ VALUE @@ -1101,11 +1214,20 @@ rb_obj_untaint(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L1214 return obj; } -/* +/** * call-seq: * obj.untrusted? -> true or false * * Deprecated method that is equivalent to #tainted?. + *-- + * \deprecated Use rb_obj_tainted. + * + * Trustiness used to have independent semantics from taintedness. + * But now trustiness of objects is obsolete and this function behaves + * the same as rb_obj_tainted. + * + * \sa rb_obj_tainted + *++ */ VALUE @@ -1115,11 +1237,20 @@ rb_obj_untrusted(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L1237 return rb_obj_tainted(obj); } -/* +/** * call-seq: * obj.untrust -> obj * * Deprecated method that is equivalent to #taint. + *-- + * \deprecated Use rb_obj_taint(obj) + * + * Trustiness used to have independent semantics from taintedness. + * But now trustiness of objects is obsolete and this function behaves + * the same as rb_obj_taint. + * + * \sa rb_obj_taint + *++ */ VALUE @@ -1130,11 +1261,20 @@ rb_obj_untrust(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L1261 } -/* +/** * call-seq: * obj.trust -> obj * * Deprecated method that is equivalent to #untaint. + *-- + * \deprecated Use rb_obj_untaint(obj) + * + * Trustiness used to have independent semantics from taintedness. + * But now trustiness of objects is obsolete and this function behaves + * the same as rb_obj_untaint. + * + * \sa rb_obj_untaint + *++ */ VALUE @@ -1144,13 +1284,21 @@ rb_obj_trust(VALUE obj) https://github.com/ruby/ruby/blob/trunk/object.c#L1284 return rb_obj_untaint(obj); } +/** + * Convenient function to infect \a victim with the taintedness of \a carrier. + * + * It just keeps the taintedness of \a victim if \a carrier is not tainted. + * \param[in,out] victim the object being infected with the taintness of \a carrier + * \param[in] carrier a possibly tainted object + */ + void -rb_obj_infect(VALUE obj1, VALUE obj2) +rb_obj_infect(VALUE victim, VALUE carrier) { - OBJ_INFECT(obj1, obj2); + OBJ_INFECT(victim, carrier); } -/* +/** * call-seq: * obj.freeze -> obj * @@ -1172,6 +1320,11 @@ rb_obj_infect(VALUE obj1, VALUE obj2) https://github.com/ruby/ruby/blob/trunk/object.c#L1320 * * Objects of the following classes are always frozen: Integer, * Float, Symbol. + *-- + * Make the object unmodifiable. Equivalent to \c Object\#freeze in Ruby. + * \param[in,out] obj the object to be frozen + * \return the frozen object + *++ */ VALUE @@ -1186,7 +1339,7 @ (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/