* README.EXT, README.EXT.ja (2.2.2), parse.y (rb_check_id): add

  documents for rb_check_id().

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

4 files changed, 32 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 530ee3ce54..1af136336a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Mon Sep 12 13:38:12 2011  Nobuyoshi Nakada  <nobu@ruby-lang.org>
+
+	* README.EXT, README.EXT.ja (2.2.2), parse.y (rb_check_id): add
+	  documents for rb_check_id().
+
 Mon Sep 12 12:53:39 2011  NAKAMURA Usaku  <usa@ruby-lang.org>
 
 	* lib/rake/file_list.rb (Rake::FileList#egrep): there is no need to
diff --git a/README.EXT b/README.EXT
index 9a6eeb0d04..a0e7a38904 100644
--- a/README.EXT
+++ b/README.EXT
@@ -442,11 +442,19 @@ or
 You can get the ID value from a string within C code by using
 
   rb_intern(const char *name)
+  rb_intern_str(VALUE name)
 
 You can retrieve ID from Ruby object (Symbol or String) given as an
 argument by using
 
   rb_to_id(VALUE symbol)
+  rb_check_id(volatile VALUE *name)
+
+These functions try to convert the argument to a String if it was not
+a Symbol nor a String.  The latter function stores the converted
+result into *name, and returns 0 if the string is not a known symbol.
+After this function returned a non-zero value, *name is always a
+Symbol or a String, otherwise it is a String if the result is 0.
 
 You can convert C ID to Ruby Symbol by using
 
diff --git a/README.EXT.ja b/README.EXT.ja
index 44ea819ebb..94a56d9ecf 100644
--- a/README.EXT.ja
+++ b/README.EXT.ja
@@ -489,11 +489,19 @@ IDとは変数名，メソッド名を表す整数です．Rubyの中では
 でアクセスできます．Cからこの整数を得るためには関数
 
   rb_intern(const char *name)
+  rb_intern_str(VALUE name)
 
 を使います．Rubyから引数として与えられたシンボル(または文字
 列)をIDに変換するには以下の関数を使います．
 
   rb_to_id(VALUE symbol)
+  rb_check_id(volatile VALUE *name)
+
+もし引数がシンボルでも文字列でもなければ、to_strメソッドで文
+字列に変換しようとします．後者の関数はその変換結果を*nameに保
+存し,その名前が既知のシンボルでない場合は0を返します．この関
+数が0以外を返した場合は*nameは常にシンボルか文字列であり、0を
+返した場合は常に文字列です．
 
 2.2.3 CからRubyのメソッドを呼び出す
 
diff --git a/parse.y b/parse.y
index ada62e70a6..73aaaabf33 100644
--- a/parse.y
+++ b/parse.y
@@ -10112,6 +10112,17 @@ rb_is_junk_id(ID id)
     return is_junk_id(id);
 }
 
+/**
+ * Returns ID for the given name if it is interned already, or 0.
+ *
+ * \param namep   the pointer to the name object
+ * \return        the ID for *namep
+ * \pre           the object referred by \p namep must be a Symbol or
+ *                a String, or possible to convert with to_str method.
+ * \post          the object referred by \p namep is a Symbol or a
+ *                String if non-zero value is returned, or is a String
+ *                if 0 is returned.
+ */
 ID
 rb_check_id(volatile VALUE *namep)
 {