From e4e7ed03af5499dbf03aaf99a8e662e866f69b8e Mon Sep 17 00:00:00 2001 From: hsbt Date: Tue, 15 Mar 2016 03:51:19 +0000 Subject: [PATCH] * doc/extension.ja.rdoc: Fix RDoc markup in doc/extension*.rdoc. [ci skip][Bug #12143][ruby-core:74143] * doc/extension.rdoc: ditto. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@54110 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 6 ++ doc/extension.ja.rdoc | 191 ++++++++++++++++++++++-------------------- doc/extension.rdoc | 128 ++++++++++++++-------------- 3 files changed, 169 insertions(+), 156 deletions(-) diff --git a/ChangeLog b/ChangeLog index 4ad38768b3..d35148817c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +Tue Mar 15 12:51:06 2016 Marcus Stollsteimer + + * doc/extension.ja.rdoc: Fix RDoc markup in doc/extension*.rdoc. + [ci skip][Bug #12143][ruby-core:74143] + * doc/extension.rdoc: ditto. + Tue Mar 15 09:56:41 2016 Ian Lunderskov * time.c: Minor typo in Time#dst? documentation. diff --git a/doc/extension.ja.rdoc b/doc/extension.ja.rdoc index 575b1ac742..dfa526f2d4 100644 --- a/doc/extension.ja.rdoc +++ b/doc/extension.ja.rdoc @@ -203,29 +203,29 @@ rb_str_new(const char *ptr, long len) :: 新しいRubyの文字列を生成する． -rb_str_new2(const char *ptr) -rb_str_new_cstr(const char *ptr) +rb_str_new2(const char *ptr) :: +rb_str_new_cstr(const char *ptr) :: Cの文字列からRubyの文字列を生成する．この関数の機能は rb_str_new(ptr, strlen(ptr))と同等である． -rb_str_new_literal(const char *ptr) +rb_str_new_literal(const char *ptr) :: Cのリテラル文字列からRubyの文字列を生成する． -rb_tainted_str_new(const char *ptr, long len) +rb_tainted_str_new(const char *ptr, long len) :: 汚染マークが付加された新しいRubyの文字列を生成する．外部 からのデータに基づく文字列には汚染マークが付加されるべき である． -rb_tainted_str_new2(const char *ptr) -rb_tainted_str_new_cstr(const char *ptr) +rb_tainted_str_new2(const char *ptr) :: +rb_tainted_str_new_cstr(const char *ptr) :: Cの文字列から汚染マークが付加されたRubyの文字列を生成する． -rb_sprintf(const char *format, ...) -rb_vsprintf(const char *format, va_list ap) +rb_sprintf(const char *format, ...) :: +rb_vsprintf(const char *format, va_list ap) :: Cの文字列formatと続く引数をprintf(3)のフォーマットにしたがって 整形し，Rubyの文字列を生成する． @@ -234,52 +234,52 @@ rb_vsprintf(const char *format, va_list ap) ときはObject#inspect)を使ったVALUEの出力に利用できる．これ は"%i"と衝突するため，整数には"%d"を使用すること． -rb_str_cat(VALUE str, const char *ptr, long len) +rb_str_cat(VALUE str, const char *ptr, long len) :: Rubyの文字列strにlenバイトの文字列ptrを追加する． -rb_str_cat2(VALUE str, const char* ptr) -rb_str_cat_cstr(VALUE str, const char* ptr) +rb_str_cat2(VALUE str, const char* ptr) :: +rb_str_cat_cstr(VALUE str, const char* ptr) :: Rubyの文字列strにCの文字列ptrを追加する．この関数の機能は rb_str_cat(str, ptr, strlen(ptr))と同等である． -rb_str_catf(VALUE str, const char* format, ...) -rb_str_vcatf(VALUE str, const char* format, va_list ap) +rb_str_catf(VALUE str, const char* format, ...) :: +rb_str_vcatf(VALUE str, const char* format, va_list ap) :: Cの文字列formatと続く引数をprintf(3)のフォーマットにしたがって 整形し，Rubyの文字列strに追加する．この関数の機能は，それぞれ rb_str_cat2(str, rb_sprintf(format, ...)) や rb_str_cat2(str, rb_vsprintf(format, ap)) と同等である． -rb_enc_str_new(const char *ptr, long len, rb_encoding *enc) -rb_enc_str_new_cstr(const char *ptr, rb_encoding *enc) +rb_enc_str_new(const char *ptr, long len, rb_encoding *enc) :: +rb_enc_str_new_cstr(const char *ptr, rb_encoding *enc) :: 指定されたエンコーディングでRubyの文字列を生成する. -rb_enc_str_new_literal(const char *ptr) +rb_enc_str_new_literal(const char *ptr) :: Cのリテラル文字列から指定されたエンコーディングでRubyの文字列を生成する． -rb_usascii_str_new(const char *ptr, long len) -rb_usascii_str_new_cstr(const char *ptr) +rb_usascii_str_new(const char *ptr, long len) :: +rb_usascii_str_new_cstr(const char *ptr) :: エンコーディングがUS-ASCIIのRubyの文字列を生成する. -rb_usascii_str_new_literal(const char *ptr) +rb_usascii_str_new_literal(const char *ptr) :: Cのリテラル文字列からエンコーディングがUS-ASCIIのRubyの文字列を生成する． -rb_utf8_str_new(const char *ptr, long len) -rb_utf8_str_new_cstr(const char *ptr) +rb_utf8_str_new(const char *ptr, long len) :: +rb_utf8_str_new_cstr(const char *ptr) :: エンコーディングがUTF-8のRubyの文字列を生成する. -rb_usascii_str_new_literal(const char *ptr) +rb_usascii_str_new_literal(const char *ptr) :: Cのリテラル文字列からエンコーディングがUTF-8のRubyの文字列を生成する． -rb_str_resize(VALUE str, long len) +rb_str_resize(VALUE str, long len) :: Rubyの文字列のサイズをlenバイトに変更する．strの長さは前 以てセットされていなければならない．lenが元の長さよりも短 @@ -288,37 +288,36 @@ rb_str_resize(VALUE str, long len) れないでゴミになるだろう．この関数の呼び出しによって RSTRING_PTR(str)が変更されるかもしれないことに注意． -rb_str_set_len(VALUE str, long len) +rb_str_set_len(VALUE str, long len) :: Rubyの文字列のサイズをlenバイトにセットする．strが変更可 能でなければ例外が発生する．RSTRING_LEN(str)とは無関係に， lenバイトまでの内容は保存される．lenはstrの容量を越えてい てはならない． +=== 配列に対する関数 -== 配列に対する関数 - -rb_ary_new() +rb_ary_new() :: 要素が0の配列を生成する． -rb_ary_new2(long len) -rb_ary_new_capa(long len) +rb_ary_new2(long len) :: +rb_ary_new_capa(long len) :: 要素が0の配列を生成する．len要素分の領域をあらかじめ割り 当てておく． -rb_ary_new3(long n, ...) -rb_ary_new_from_args(long n, ...) +rb_ary_new3(long n, ...) :: +rb_ary_new_from_args(long n, ...) :: 引数で指定したn要素を含む配列を生成する． -rb_ary_new4(long n, VALUE *elts) -rb_ary_new_from_values(long n, VALUE *elts) +rb_ary_new4(long n, VALUE *elts) :: +rb_ary_new_from_values(long n, VALUE *elts) :: 配列で与えたn要素の配列を生成する． -rb_ary_to_ary(VALUE obj) +rb_ary_to_ary(VALUE obj) :: オブジェクトを配列に変換する. Object#to_aryと同等である. @@ -327,28 +326,30 @@ rb_ary_to_ary(VALUE obj) 引数aryに配列を渡さなければならない. さもないと コアを吐く. -rb_ary_aref(argc, VALUE *argv, VALUE ary) +rb_ary_aref(argc, VALUE *argv, VALUE ary) :: Array#[]と同等. -rb_ary_entry(VALUE ary, long offset) +rb_ary_entry(VALUE ary, long offset) :: - ary[offset] + \ary[offset] rb_ary_store(VALUE ary, long offset, VALUE obj) :: - ary[offset] = obj + \ary[offset] = obj -rb_ary_subseq(VALUE ary, long beg, long len) +rb_ary_subseq(VALUE ary, long beg, long len) :: ary[beg, len] -rb_ary_push(VALUE ary, VALUE val) -rb_ary_pop(VALUE ary) -rb_ary_shift(VALUE ary) -rb_ary_unshift(VALUE ary, VALUE val) +rb_ary_push(VALUE ary, VALUE val) :: +rb_ary_pop(VALUE ary) :: +rb_ary_shift(VALUE ary) :: +rb_ary_unshift(VALUE ary, VALUE val) :: -rb_ary_cat(VALUE ary, const VALUE *ptr, long len) + ary.push, ary.pop, ary.shift, ary.unshift + +rb_ary_cat(VALUE ary, const VALUE *ptr, long len) :: 配列aryにptrからlen個のオブジェクトを追加する． @@ -365,9 +366,9 @@ Rubyで提供されている関数を使えばRubyインタプリタに新しい を追加することができます．Rubyでは以下の機能を追加する関数が 提供されています． -* クラス，モジュール -* メソッド，特異メソッドなど -* 定数 +- クラス，モジュール +- メソッド，特異メソッドなど +- 定数 では順に紹介します． @@ -398,7 +399,6 @@ Rubyで提供されている関数を使えばRubyインタプリタに新しい void rb_define_singleton_method(VALUE object, const char *name, VALUE (*func)(), int argc) - 念のため説明すると「特異メソッド」とは，その特定のオブジェク トに対してだけ有効なメソッドです．RubyではよくSmalltalkにお けるクラスメソッドとして，クラスに対する特異メソッドが使われ @@ -453,7 +453,6 @@ privateメソッドでもあるものです．例をあげるとMathモジュー void rb_define_global_function(const char *name, VALUE (*func)(), int argc) - メソッドの別名を定義するための関数は以下の通りです． void rb_define_alias(VALUE module, const char* new, const char* old); @@ -612,14 +611,14 @@ C言語とRubyの間で情報を共有する方法について解説します． 以下のRubyの定数はCのレベルから参照できます． - Qtrue - Qfalse +Qtrue :: +Qfalse :: -真偽値．QfalseはC言語でも偽とみなされます(つまり0)． + 真偽値．QfalseはC言語でも偽とみなされます(つまり0)． - Qnil +Qnil :: -C言語から見た「nil」． + C言語から見た「nil」． == CとRubyで共有される大域変数 @@ -649,14 +648,15 @@ CとRubyで大域変数を使って情報を共有できます．共有できる す．変数が参照された時には関数getterが，変数に値がセットされ た時には関数setterが呼ばれる．hookを指定しない場合はgetterや setterに0を指定します． -# getterもsetterも0ならばrb_define_variable()と同じになる． +-- +getterもsetterも0ならばrb_define_variable()と同じになる． +++ getterとsetterの仕様は次の通りです． VALUE (*getter)(ID id, VALUE *var); void (*setter)(VALUE val, ID id, VALUE *var); - それから，対応するCの変数を持たないRubyの大域変数を定義する こともできます. その変数の値はフック関数のみによって取得・設定 されます. @@ -679,11 +679,14 @@ Cの世界で定義されたデータ(構造体)をRubyのオブジェクトと マクロ群を用いて構造体へのポインタとRubyのオブジェクトとを互 いに変換できます． -# 古い(非Typedな)Data_XXXマクロ群は非推奨になりました． -# 将来のバージョンのRubyでは古いマクロは動作しなくなる可能性 -# があります． +-- +古い(非Typedな)Data_XXXマクロ群は非推奨になりました． +将来のバージョンのRubyでは古いマクロは動作しなくなる可能性 +があります． +++ === 構造体からオブジェクトへ + 構造体へのポインタsvalをRubyオブジェクトに変換するには次のマ クロを使います。 @@ -730,7 +733,9 @@ dmarkはガーベージコレクタがオブジェクトへの参照をマーク のすべての参照をマークしなければなりません． そのような参照を含まない時には0を指定します． -# そのような参照は勧められません． +-- +そのような参照は勧められません． +++ dfreeはこの構造体がもう不要になった時に呼ばれる関数です．こ の関数がガーベージコレクタから呼ばれます．これが-1の場合は， @@ -933,7 +938,6 @@ fdbm_delete()はこのようになっています． い，第4変数以降に指定したVALUEへの参照に値を代入してくれま す． - 引数をRubyの配列として受け取るメソッドの例には Thread#initializeがあります．実装はこうです． @@ -1063,12 +1067,13 @@ variable.c :: 変数と定数 == Rubyの構文解析器 - parse.y : 字句解析器と構文定義 - -> parse.c : 自動生成 - keywords : 予約語 - -> lex.c : 自動生成 +parse.y :: 字句解析器と構文定義 +parse.c :: 自動生成 +keywords :: 予約語 +lex.c :: 自動生成 == Rubyの評価器 (通称YARV) + compile.c eval.c eval_error.c @@ -1153,6 +1158,7 @@ sprintf.c :: String#sprintf string.c :: String struct.c :: Struct time.c :: Time + defs/known_errors.def :: 例外クラス Errno::* -> known_errors.inc :: 自動生成 @@ -1301,7 +1307,7 @@ void rb_define_hooked_variable(const char *name, VALUE *var, VALUE (*getter)(), setterが呼ばれる．getterやsetterに0を指定した時にはhookを 指定しないのと同じ事になる． -void rb_global_variable(VALUE *var) +void rb_global_variable(VALUE *var) :: GCのため，Rubyプログラムからはアクセスされないが, Rubyオブ ジェクトを含む大域変数をマークする． @@ -1384,7 +1390,7 @@ rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) :: 返り値は与えられた引数の数です．オプションハッシュおよびイ テレータブロックは数えません． -int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values) +int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values) :: キーワードで指定された値をtableにしたがって取り出します． tableの最初のrequired個のIDは必須キーワードを表し，続く @@ -1396,7 +1402,7 @@ int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optiona 新しいHashとして省略可能引数の次に保存されますが，そうでなけ れば"unknown keyword"ArgumentErrorが発生します． -VALUE rb_extract_keywords(VALUE *original_hash) +VALUE rb_extract_keywords(VALUE *original_hash) :: original_hashで参照されるHashオブジェクトから，Symbolである キーとその値を新しいHashに取り出します．original_hashの指す @@ -1422,7 +1428,7 @@ VALUE rb_funcallv_public(VALUE recv, ID mid, int argc, VALUE *argv) :: メソッド呼び出し． publicなメソッドしか呼べない． -VALUE rb_eval_string(const char *str) +VALUE rb_eval_string(const char *str) :: 文字列をRubyスクリプトとしてコンパイル・実行する． @@ -1467,7 +1473,7 @@ VALUE rb_block_call(VALUE obj, ID mid, int argc, VALUE * argv, VALUE (*func) (AN data2はArrayとしてパックされている．第三, 第四引数のargcと argvによってyieldされた値を取り出すことができる． -[OBSOLETE] VALUE rb_iterate(VALUE (*func1)(), VALUE arg1, VALUE (*func2)(), VALUE arg2) :: +\[OBSOLETE] VALUE rb_iterate(VALUE (*func1)(), VALUE arg1, VALUE (*func2)(), VALUE arg2) :: func2をブロックとして設定し, func1をイテレータとして呼ぶ． func1には arg1が引数として渡され, func2には第1引数にイテレー @@ -1576,34 +1582,33 @@ void ruby_script(char *name) :: == インタプリタのイベントのフック - void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, - VALUE data) +void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data) :: -指定されたインタプリタのイベントに対するフック関数を追加します． -eventsは以下の値のorでなければなりません: + 指定されたインタプリタのイベントに対するフック関数を追加します． + eventsは以下の値のorでなければなりません: - RUBY_EVENT_LINE - RUBY_EVENT_CLASS - RUBY_EVENT_END - RUBY_EVENT_CALL - RUBY_EVENT_RETURN - RUBY_EVENT_C_CALL - RUBY_EVENT_C_RETURN - RUBY_EVENT_RAISE - RUBY_EVENT_ALL + RUBY_EVENT_LINE + RUBY_EVENT_CLASS + RUBY_EVENT_END + RUBY_EVENT_CALL + RUBY_EVENT_RETURN + RUBY_EVENT_C_CALL + RUBY_EVENT_C_RETURN + RUBY_EVENT_RAISE + RUBY_EVENT_ALL -rb_event_hook_func_tの定義は以下の通りです: + rb_event_hook_func_tの定義は以下の通りです: - typedef void (*rb_event_hook_func_t)(rb_event_t event, VALUE data, - VALUE self, ID id, VALUE klass) + typedef void (*rb_event_hook_func_t)(rb_event_t event, VALUE data, + VALUE self, ID id, VALUE klass) -rb_add_event_hook() の第3引数 data は，フック関数の第2引数と -して渡されます．これは1.8では現在のNODEへのポインタでした．以 -下の RB_EVENT_HOOKS_HAVE_CALLBACK_DATA も参照してください． + rb_add_event_hook() の第3引数 data は，フック関数の第2引数と + して渡されます．これは1.8では現在のNODEへのポインタでした．以 + 下の RB_EVENT_HOOKS_HAVE_CALLBACK_DATA も参照してください． - int rb_remove_event_hook(rb_event_hook_func_t func) +int rb_remove_event_hook(rb_event_hook_func_t func) :: -指定されたフック関数を削除します． + 指定されたフック関数を削除します． == 互換性のためのマクロ @@ -1633,7 +1638,7 @@ HAVE_RB_IO_T :: USE_SYMBOL_AS_METHOD_NAME :: - メソッド名を返すメソッド，Module#methods, #singleton_methods + メソッド名を返すメソッド，Module#methods, \#singleton_methods などがSymbolを返すことを意味する． HAVE_RUBY_*_H :: @@ -1745,7 +1750,7 @@ disable_config(config, *defaults) :: --disable-が指定されていた場合はfalseを返す． どちらも指定されていない場合は，ブロックつきで呼び出されて いる場合は*defaultsをyieldした結果，ブロックなしなら - *defaultsを返す． + \*defaultsを返す． dir_config(target[, default_dir]) :: dir_config(target[, default_include, default_lib]) :: diff --git a/doc/extension.rdoc b/doc/extension.rdoc index 54612adae9..ff1bc9664a 100644 --- a/doc/extension.rdoc +++ b/doc/extension.rdoc @@ -147,7 +147,7 @@ FIXNUM :: left shift 1 bit, and turn on LSB. -Other pointer values:: +Other pointer values :: cast to VALUE. @@ -309,11 +309,11 @@ rb_ary_aref(argc, VALUE *argv, VALUE ary) :: rb_ary_entry(VALUE ary, long offset) :: - ary[offset] + \ary[offset] rb_ary_store(VALUE ary, long offset, VALUE obj) :: - ary[offset] = obj + \ary[offset] = obj rb_ary_subseq(VALUE ary, long beg, long len) :: @@ -324,6 +324,8 @@ rb_ary_pop(VALUE ary) :: rb_ary_shift(VALUE ary) :: rb_ary_unshift(VALUE ary, VALUE val) :: + ary.push, ary.pop, ary.shift, ary.unshift + rb_ary_cat(VALUE ary, const VALUE *ptr, long len) :: Appends len elements of objects from ptr to the array. @@ -335,9 +337,9 @@ rb_ary_cat(VALUE ary, const VALUE *ptr, long len) :: You can add new features (classes, methods, etc.) to the Ruby interpreter. Ruby provides APIs for defining the following things: -* Classes, Modules -* Methods, Singleton Methods -* Constants +- Classes, Modules +- Methods, Singleton Methods +- Constants === Class and Module Definition @@ -565,14 +567,14 @@ See also Constant Definition above. As stated in section 1.3, the following Ruby constants can be referred from C. - Qtrue - Qfalse +Qtrue :: +Qfalse :: -Boolean values. Qfalse is false in C also (i.e. 0). + Boolean values. Qfalse is false in C also (i.e. 0). - Qnil +Qnil :: -Ruby nil in C scope. + Ruby nil in C scope. == Global Variables Shared Between C and Ruby @@ -605,7 +607,6 @@ The prototypes of the getter and setter functions are as follows: VALUE (*getter)(ID id, VALUE *var); void (*setter)(VALUE val, ID id, VALUE *var); - Also you can define a Ruby global variable without a corresponding C variable. The value of the variable will be set/get only by hooks. @@ -617,7 +618,6 @@ The prototypes of the getter and setter functions are as follows: VALUE (*getter)(ID id); void (*setter)(VALUE val, ID id); - == Encapsulate C Data into a Ruby Object Sometimes you need to expose your struct in the C world as a Ruby @@ -626,11 +626,14 @@ In a situation like this, making use of the TypedData_XXX macro family, the pointer to the struct and the Ruby object can be mutually converted. -# The old (non-Typed) Data_XXX macro family has been deprecated. -# In the future version of Ruby, it is possible old macros will not -# work. +-- +The old (non-Typed) Data_XXX macro family has been deprecated. +In the future version of Ruby, it is possible old macros will not +work. +++ === C struct to Ruby object + You can convert sval, a pointer to your struct, into a Ruby object with the next macro. @@ -675,7 +678,9 @@ dmark is a function to mark Ruby objects referred from your struct. It must mark all references from your struct with rb_gc_mark or its family if your struct keeps such references. -# Note that it is recommended to avoid such a reference. +-- +Note that it is recommended to avoid such a reference. +++ dfree is a function to free the pointer allocation. If this is -1, the pointer will be just freed. @@ -717,7 +722,6 @@ RUBY_TYPED_WB_PROTECTED :: More about write barriers can be found in "Generational GC" in Appendix D. - You can allocate and wrap the structure in one step. TypedData_Make_Struct(klass, type, data_type, sval) @@ -731,7 +735,6 @@ Arguments klass and data_type work like their counterparts in TypedData_Wrap_Struct(). A pointer to the allocated structure will be assigned to sval, which should be a pointer of the type specified. - === Ruby object to C struct To retrieve the C pointer from the Data object, use the macro @@ -864,7 +867,6 @@ arguments. The third argument is a string that specifies how to capture method arguments and assign them to the following VALUE references. - The following is an example of a method that takes arguments by Ruby's array: @@ -877,7 +879,7 @@ array: The first argument is the receiver, the second one is the Ruby array which contains the arguments to the method. -*Notice*: GC should know about global variables which refer to Ruby's objects, +Notice: GC should know about global variables which refer to Ruby's objects, but are not exported to the Ruby world. You need to protect them by void rb_global_variable(VALUE *var) @@ -1097,7 +1099,6 @@ enc/trans/* :: codepoint mapping tables golf_prelude.rb : goruby specific libraries. -> golf_prelude.c : automatically generated - = Appendix B. Ruby Extension API Reference == Types @@ -1110,13 +1111,16 @@ VALUE :: == Variables and Constants -Qnil:: +Qnil :: + nil object -Qtrue:: +Qtrue :: + true object (default true value) -Qfalse:: +Qfalse :: + false object == C Pointer Wrapping @@ -1230,15 +1234,15 @@ RSTRING_PTR(str) :: StringValue(value) :: - Object with #to_str -> String + Object with \#to_str -> String StringValuePtr(value) :: - Object with #to_str -> pointer to String data + Object with \#to_str -> pointer to String data StringValueCStr(value) :: - Object with #to_str -> pointer to String data without NUL bytes + Object with \#to_str -> pointer to String data without NUL bytes It is guaranteed that the result data is NUL-terminated rb_str_new2(s) :: @@ -1308,11 +1312,10 @@ void rb_define_hooked_variable(const char *name, VALUE *var, VALUE (*getter)(), void setter(VALUE val, ID id, VALUE *var) +void rb_global_variable(VALUE *var) :: + GC requires C global variables which hold Ruby values to be marked. - -void rb_global_variable(VALUE *var) - - Tells GC to protect these variables. + rb_global_variable tells GC to protect these variables. == Constant Definition @@ -1398,7 +1401,7 @@ rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) :: The number of given arguments, excluding an option hash or iterator block, is returned. -int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values) +int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values) :: Retrieves argument VALUEs bound to keywords, which directed by +table+ into +values+, deleting retrieved entries from +keyword_hash+ along @@ -1417,7 +1420,7 @@ int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optiona around a non-keyword C function. ref: https://bugs.ruby-lang.org/issues/11339 -VALUE rb_extract_keywords(VALUE *original_hash) +VALUE rb_extract_keywords(VALUE *original_hash) :: Extracts pairs whose key is a symbol into a new hash from a hash object referred by +original_hash+. If the original hash contains @@ -1486,7 +1489,7 @@ VALUE rb_block_call(VALUE recv, ID mid, int argc, VALUE * argv, VALUE (*func) (A whereas yielded values can be gotten via argc/argv of the third/fourth arguments. -[OBSOLETE] VALUE rb_iterate(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2) :: +\[OBSOLETE] VALUE rb_iterate(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2) :: Calls the function func1, supplying func2 as the block. func1 will be called with the argument arg1. func2 receives the value from yield as @@ -1600,34 +1603,33 @@ void ruby_script(char *name) :: == Hooks for the Interpreter Events - void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, - VALUE data) +void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data) :: -Adds a hook function for the specified interpreter events. -events should be OR'ed value of: + Adds a hook function for the specified interpreter events. + events should be OR'ed value of: - RUBY_EVENT_LINE - RUBY_EVENT_CLASS - RUBY_EVENT_END - RUBY_EVENT_CALL - RUBY_EVENT_RETURN - RUBY_EVENT_C_CALL - RUBY_EVENT_C_RETURN - RUBY_EVENT_RAISE - RUBY_EVENT_ALL + RUBY_EVENT_LINE + RUBY_EVENT_CLASS + RUBY_EVENT_END + RUBY_EVENT_CALL + RUBY_EVENT_RETURN + RUBY_EVENT_C_CALL + RUBY_EVENT_C_RETURN + RUBY_EVENT_RAISE + RUBY_EVENT_ALL -The definition of rb_event_hook_func_t is below: + The definition of rb_event_hook_func_t is below: - typedef void (*rb_event_hook_func_t)(rb_event_t event, VALUE data, - VALUE self, ID id, VALUE klass) + typedef void (*rb_event_hook_func_t)(rb_event_t event, VALUE data, + VALUE self, ID id, VALUE klass) -The third argument `data' to rb_add_event_hook() is passed to the hook -function as the second argument, which was the pointer to the current -NODE in 1.8. See RB_EVENT_HOOKS_HAVE_CALLBACK_DATA below. + The third argument `data' to rb_add_event_hook() is passed to the hook + function as the second argument, which was the pointer to the current + NODE in 1.8. See RB_EVENT_HOOKS_HAVE_CALLBACK_DATA below. - int rb_remove_event_hook(rb_event_hook_func_t func) +int rb_remove_event_hook(rb_event_hook_func_t func) :: -Removes the specified hook function. + Removes the specified hook function. == Macros for Compatibility @@ -1656,7 +1658,7 @@ HAVE_RB_IO_T :: USE_SYMBOL_AS_METHOD_NAME :: Means that Symbols will be returned as method names, e.g., - Module#methods, #singleton_methods and so on. + Module#methods, \#singleton_methods and so on. HAVE_RUBY_*_H :: @@ -1730,13 +1732,13 @@ If you support T_DATA objects, you may consider using write barriers. Inserting write barriers into T_DATA objects only works with the following type objects: (a) long-lived objects, (b) when a huge number -of objects are generated and (c) container-type objects that have +of objects are generated and \(c) container-type objects that have references to other objects. If your extension provides such a type of T_DATA objects, consider inserting write barriers. (a): short-lived objects don't become old generation objects. (b): only a few oldgen objects don't have performance impact. -(c): only a few references don't have performance impact. +\(c): only a few references don't have performance impact. Inserting write barriers is a very difficult hack, it is easy to introduce critical bugs. And inserting write barriers has several areas @@ -1760,7 +1762,7 @@ anymore. === Insert write barriers -[AGAIN] Inserting write barriers is a very difficult hack, and it is +\[AGAIN] Inserting write barriers is a very difficult hack, and it is easy to introduce critical bugs. And inserting write barriers has several areas of overhead. Basically we don't recommend you insert write barriers. Please carefully consider the risks. @@ -1812,12 +1814,12 @@ GC invocation from prematurely freeing it. Using the RB_GC_GUARD macro is preferable to using the "volatile" keyword in C. RB_GC_GUARD has the following advantages: -1) the intent of the macro use is clear +1. the intent of the macro use is clear -2) RB_GC_GUARD only affects its call site, "volatile" generates some +2. RB_GC_GUARD only affects its call site, "volatile" generates some extra code every time the variable is used, hurting optimization. -3) "volatile" implementations may be buggy/inconsistent in some +3. "volatile" implementations may be buggy/inconsistent in some compilers and architectures. RB_GC_GUARD is customizable for broken systems/compilers without those without negatively affecting other systems.