* README.EXT, README.EXT.ja: Improve the document about

rb_scan_args().


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@22421 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,8 @@
+Thu Feb 19 03:00:49 2009  Akinori MUSHA  <knu@iDaemons.org>
+
+	* README.EXT, README.EXT.ja: Improve the document about
+	  rb_scan_args().
+
 Wed Feb 18 22:47:01 2009  Tanaka Akira  <akr@fsij.org>
 
 	* ext/socket/ancdata.c (discard_cmsg_resource): new function to close

README.EXT

@@ -690,18 +690,27 @@ pre-arg-spec   := num-of-leading-mandatory-args [num-of-optional-args]
 post-arg-spec  := sym-for-variable-length-args [num-of-trailing-mandatory-args]
 block-arg-spec := sym-for-block-arg
 
-num-of-leading-mandatory-args  := DIGIT  ; -- the number of the leading mandatory arguments
-num-of-optional-args           := DIGIT  ; -- the number of the following optional arguments
-sym-for-variable-length-args   := "*"    ; -- indicates that the following variable length
-                                         ;    arguments are captured as a Ruby array
-num-of-trailing-mandatory-args := DIGIT  ; -- the number of the trailing mandatory arguments
-sym-for-block-arg              := "&"    ; -- indicates that the iterator block should be
-                                         ;    captured if given
+num-of-leading-mandatory-args  := DIGIT ; The number of leading
+                                        ; mandatory arguments
+num-of-optional-args           := DIGIT ; The number of optional
+                                        ; arguments
+sym-for-variable-length-args   := "*"   ; Indicates that variable
+                                        ; length arguments are
+                                        ; captured as a ruby array
+num-of-trailing-mandatory-args := DIGIT ; The number of trailing
+                                        ; mandatory arguments
+sym-for-block-arg              := "&"   ; Indicates that an iterator
+                                        ; block should be captured if
+                                        ; given
 --
 
 For example, "11" means that the method requires at least one
-argument, and at most receives two arguments.  For omitted arguments,
-variables are set to Qnil.
+argument, and at most receives two (1+1) arguments.  So, the format
+string must be followed by two variable references, which are to be
+set to captured arguments.  For omitted arguments, variables are set
+to Qnil.  NULL can be put in place of a variable reference, which
+means the corresponding captured argument(s) does not need to be set.
+
 
 Methods with an arbitrary number of arguments can receive arguments
 by Ruby's array, like this:

README.EXT.ja

@@ -778,20 +778,26 @@ pre-arg-spec   := num-of-leading-mandatory-args [num-of-optional-args]
 post-arg-spec  := sym-for-variable-length-args [num-of-trailing-mandatory-args]
 block-arg-spec := sym-for-block-arg
 
-num-of-leading-mandatory-args  := DIGIT  ; -- 先頭に置かれる省略不可能な引数の数
-num-of-optional-args           := DIGIT  ; -- 続いて置かれる省略可能な引数の数
-sym-for-variable-length-args   := "*"    ; -- 続いて置かれる可変長引数をRubyの配列で
-                                         ;    取得するための指定
-num-of-trailing-mandatory-args := DIGIT  ; -- 終端に置かれる省略不可能な引数の数
-sym-for-block-arg              := "&"    ; -- イテレータブロックを取得するための指定
+num-of-leading-mandatory-args  := DIGIT ; 先頭に置かれる省略不可能な引数の数
+num-of-optional-args           := DIGIT ; 続いて置かれる省略可能な引数の数
+sym-for-variable-length-args   := "*"   ; 続いて置かれる可変長引数を
+                                        ; Rubyの配列で取得するための指定
+num-of-trailing-mandatory-args := DIGIT ; 終端に置かれる省略不可能な引数の数
+sym-for-block-arg              := "&"   ; イテレータブロックを取得するための
+                                        ; 指定
 --
 
-dbm.cの例では，フォーマットは"11"ですから，引数は最低1つ
-で，2つまで許されるという意味になります．省略されている時の
-変数の値はnil(C言語のレベルではQnil)になります．
+dbm.cの例では，フォーマットは"11"ですから，引数は最低1つで，2つ
+(1+1)まで許されるという意味になります．従って，フォーマット文
+字列に続いて2つの変数への参照を置く必要があります．それらには
+取得した変数がセットされます．変数への参照の代わりにNULLを指
+定することもでき，その場合は取得した引数の値は捨てられます．
+なお、省略可能引数が省略された時の変数の値はnil(C言語のレベル
+ではQnil)になります．
 
-最後に、引数をRubyの配列として受け取るものにはThread#initializeがあります．
-実装はこうです．
+
+最後に，引数をRubyの配列として受け取るものには
+Thread#initializeがあります．実装はこうです．
 
 --
 static VALUE