* object.c: Document methods receiving string and convert to symbol

  Patch by Stefan Rusterholz
* vm_eval.c: ditto
* vm_method.c: ditto


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

4 files changed, 77 insertions, 5 deletions

diff --git a/ChangeLog b/ChangeLog
index 6a3ff4625d..b71067c8a4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+Wed Feb 20 13:23:00 2013  Zachary Scott  <zachary@zacharyscott.net>
+
+	* object.c: Document methods receiving string and convert to symbol
+	  Patch by Stefan Rusterholz
+	* vm_eval.c: ditto
+	* vm_method.c: ditto
+
 Wed Feb 20 07:20:56 2013  KOSAKI Motohiro  <kosaki.motohiro@gmail.com>
 
 	* signal.c (sigsegv): suppress unused result warning. Because
diff --git a/object.c b/object.c
index 3da19cdf3d..eceab5c198 100644
--- a/object.c
+++ b/object.c
@@ -1806,12 +1806,15 @@ rb_class_get_superclass(VALUE klass)
 
 /*
  *  call-seq:
- *     attr_reader(symbol, ...)    -> nil
- *     attr(symbol, ...)             -> nil
+ *     attr_reader(symbol, ...)  -> nil
+ *     attr(symbol, ...)         -> nil
+ *     attr_reader(string, ...)  -> nil
+ *     attr(string, ...)         -> nil
  *
  *  Creates instance variables and corresponding methods that return the
  *  value of each instance variable. Equivalent to calling
  *  ``<code>attr</code><i>:name</i>'' on each name in turn.
+ *  String arguments are converted to symbols.
  */
 
 static VALUE
@@ -1839,9 +1842,11 @@ rb_mod_attr(int argc, VALUE *argv, VALUE klass)
 /*
  *  call-seq:
  *      attr_writer(symbol, ...)    -> nil
+ *      attr_writer(string, ...)    -> nil
  *
  *  Creates an accessor method to allow assignment to the attribute
  *  <i>symbol</i><code>.id2name</code>.
+ *  String arguments are converted to symbols.
  */
 
 static VALUE
@@ -1858,11 +1863,13 @@ rb_mod_attr_writer(int argc, VALUE *argv, VALUE klass)
 /*
  *  call-seq:
  *     attr_accessor(symbol, ...)    -> nil
+ *     attr_accessor(string, ...)    -> nil
  *
  *  Defines a named attribute for this module, where the name is
  *  <i>symbol.</i><code>id2name</code>, creating an instance variable
  *  (<code>@name</code>) and a corresponding access method to read it.
  *  Also creates a method called <code>name=</code> to set the attribute.
+ *  String arguments are converted to symbols.
  *
  *     module Mod
  *       attr_accessor(:one, :two)
@@ -2084,12 +2091,14 @@ rb_mod_const_defined(int argc, VALUE *argv, VALUE mod)
 /*
  *  call-seq:
  *     obj.instance_variable_get(symbol)    -> obj
+ *     obj.instance_variable_get(string)    -> obj
  *
  *  Returns the value of the given instance variable, or nil if the
  *  instance variable is not set. The <code>@</code> part of the
  *  variable name should be included for regular instance
  *  variables. Throws a <code>NameError</code> exception if the
  *  supplied symbol is not valid as an instance variable name.
+ *  String arguments are converted to symbols.
  *
  *     class Fred
  *       def initialize(p1, p2)
@@ -2125,11 +2134,14 @@ rb_obj_ivar_get(VALUE obj, VALUE iv)
 /*
  *  call-seq:
  *     obj.instance_variable_set(symbol, obj)    -> obj
+ *     obj.instance_variable_set(string, obj)    -> obj
  *
  *  Sets the instance variable names by <i>symbol</i> to
  *  <i>object</i>, thereby frustrating the efforts of the class's
  *  author to attempt to provide proper encapsulation. The variable
  *  did not have to exist prior to this call.
+ *  If the instance variable name is passed as a string, that string
+ *  is converted to a symbol.
  *
  *     class Fred
  *       def initialize(p1, p2)
@@ -2157,9 +2169,11 @@ rb_obj_ivar_set(VALUE obj, VALUE iv, VALUE val)
 /*
  *  call-seq:
  *     obj.instance_variable_defined?(symbol)    -> true or false
+ *     obj.instance_variable_defined?(string)    -> true or false
  *
  *  Returns <code>true</code> if the given instance variable is
  *  defined in <i>obj</i>.
+ *  String arguments are converted to symbols.
  *
  *     class Fred
  *       def initialize(p1, p2)
@@ -2196,10 +2210,12 @@ rb_obj_ivar_defined(VALUE obj, VALUE iv)
 /*
  *  call-seq:
  *     mod.class_variable_get(symbol)    -> obj
+ *     mod.class_variable_get(string)    -> obj
  *
  *  Returns the value of the given class variable (or throws a
  *  <code>NameError</code> exception). The <code>@@</code> part of the
  *  variable name should be included for regular class variables
+ *  String arguments are converted to symbols.
  *
  *     class Fred
  *       @@foo = 99
@@ -2232,9 +2248,12 @@ rb_mod_cvar_get(VALUE obj, VALUE iv)
 /*
  *  call-seq:
  *     obj.class_variable_set(symbol, obj)    -> obj
+ *     obj.class_variable_set(string, obj)    -> obj
  *
  *  Sets the class variable names by <i>symbol</i> to
  *  <i>object</i>.
+ *  If the class variable name is passed as a string, that string
+ *  is converted to a symbol.
  *
  *     class Fred
  *       @@foo = 99
@@ -2262,9 +2281,11 @@ rb_mod_cvar_set(VALUE obj, VALUE iv, VALUE val)
 /*
  *  call-seq:
  *     obj.class_variable_defined?(symbol)    -> true or false
+ *     obj.class_variable_defined?(string)    -> true or false
  *
  *  Returns <code>true</code> if the given class variable is defined
  *  in <i>obj</i>.
+ *  String arguments are converted to symbols.
  *
  *     class Fred
  *       @@foo = 99
diff --git a/vm_eval.c b/vm_eval.c
index 296af8cfe7..53025a489c 100644
--- a/vm_eval.c
+++ b/vm_eval.c
@@ -862,13 +862,17 @@ send_internal(int argc, const VALUE *argv, VALUE recv, call_type scope)
 }
 
 /*
- *  call-seq:
- *     foo.send(symbol [, args...])        -> obj
- *     foo.__send__(symbol [, args...])      -> obj
+ * call-seq:
+ *    foo.send(symbol [, args...])       -> obj
+ *    foo.__send__(symbol [, args...])   -> obj
+ *    foo.send(string [, args...])       -> obj
+ *    foo.__send__(string [, args...])   -> obj
  *
  *  Invokes the method identified by _symbol_, passing it any
  *  arguments specified. You can use <code>__send__</code> if the name
  *  +send+ clashes with an existing method in _obj_.
+ *  When the method is identified by a string, the string is converted
+ *  to a symbol.
  *
  *     class Klass
  *       def hello(*args)
@@ -888,10 +892,13 @@ rb_f_send(int argc, VALUE *argv, VALUE recv)
 /*
  *  call-seq:
  *     obj.public_send(symbol [, args...])  -> obj
+ *     obj.public_send(string [, args...])  -> obj
  *
  *  Invokes the method identified by _symbol_, passing it any
  *  arguments specified. Unlike send, public_send calls public
  *  methods only.
+ *  When the method is identified by a string, the string is converted
+ *  to a symbol.
  *
  *     1.public_send(:puts, "hello")  # causes NoMethodError
  */
diff --git a/vm_method.c b/vm_method.c
index 1dbbdd511b..effc4a453a 100644
--- a/vm_method.c
+++ b/vm_method.c
@@ -693,9 +693,11 @@ rb_remove_method(VALUE klass, const char *name)
 /*
  *  call-seq:
  *     remove_method(symbol)   -> self
+ *     remove_method(string)   -> self
  *
  *  Removes the method identified by _symbol_ from the current
  *  class. For an example, see <code>Module.undef_method</code>.
+ *  String arguments are converted to symbols.
  */
 
 static VALUE
@@ -878,11 +880,13 @@ rb_undef(VALUE klass, ID id)
 /*
  *  call-seq:
  *     undef_method(symbol)    -> self
+ *     undef_method(string)    -> self
  *
  *  Prevents the current class from responding to calls to the named
  *  method. Contrast this with <code>remove_method</code>, which deletes
  *  the method from the particular class; Ruby will still search
  *  superclasses and mixed-in modules for a possible receiver.
+ *  String arguments are converted to symbols.
  *
  *     class Parent
  *       def hello
@@ -936,10 +940,12 @@ rb_mod_undef_method(int argc, VALUE *argv, VALUE mod)
 /*
  *  call-seq:
  *     mod.method_defined?(symbol)    -> true or false
+ *     mod.method_defined?(string)    -> true or false
  *
  *  Returns +true+ if the named method is defined by
  *  _mod_ (or its included modules and, if _mod_ is a class,
  *  its ancestors). Public and protected methods are matched.
+ *  String arguments are converted to symbols.
  *
  *     module A
  *       def method1()  end
@@ -989,10 +995,12 @@ check_definition(VALUE mod, VALUE mid, rb_method_flag_t noex)
 /*
  *  call-seq:
  *     mod.public_method_defined?(symbol)   -> true or false
+ *     mod.public_method_defined?(string)   -> true or false
  *
  *  Returns +true+ if the named public method is defined by
  *  _mod_ (or its included modules and, if _mod_ is a class,
  *  its ancestors).
+ *  String arguments are converted to symbols.
  *
  *     module A
  *       def method1()  end
@@ -1021,10 +1029,12 @@ rb_mod_public_method_defined(VALUE mod, VALUE mid)
 /*
  *  call-seq:
  *     mod.private_method_defined?(symbol)    -> true or false
+ *     mod.private_method_defined?(string)    -> true or false
  *
  *  Returns +true+ if the named private method is defined by
  *  _ mod_ (or its included modules and, if _mod_ is a class,
  *  its ancestors).
+ *  String arguments are converted to symbols.
  *
  *     module A
  *       def method1()  end
@@ -1053,10 +1063,12 @@ rb_mod_private_method_defined(VALUE mod, VALUE mid)
 /*
  *  call-seq:
  *     mod.protected_method_defined?(symbol)   -> true or false
+ *     mod.protected_method_defined?(string)   -> true or false
  *
  *  Returns +true+ if the named protected method is defined
  *  by _mod_ (or its included modules and, if _mod_ is a
  *  class, its ancestors).
+ *  String arguments are converted to symbols.
  *
  *     module A
  *       def method1()  end
@@ -1274,10 +1286,12 @@ set_method_visibility(VALUE self, int argc, VALUE *argv, rb_method_flag_t ex)
  *  call-seq:
  *     public                 -> self
  *     public(symbol, ...)    -> self
+ *     public(string, ...)    -> self
  *
  *  With no arguments, sets the default visibility for subsequently
  *  defined methods to public. With arguments, sets the named methods to
  *  have public visibility.
+ *  String arguments are converted to symbols.
  */
 
 static VALUE
@@ -1297,10 +1311,12 @@ rb_mod_public(int argc, VALUE *argv, VALUE module)
  *  call-seq:
  *     protected                -> self
  *     protected(symbol, ...)   -> self
+ *     protected(string, ...)   -> self
  *
  *  With no arguments, sets the default visibility for subsequently
  *  defined methods to protected. With arguments, sets the named methods
  *  to have protected visibility.
+ *  String arguments are converted to symbols.
  */
 
 static VALUE
@@ -1320,10 +1336,12 @@ rb_mod_protected(int argc, VALUE *argv, VALUE module)
  *  call-seq:
  *     private                 -> self
  *     private(symbol, ...)    -> self
+ *     private(string, ...)    -> self
  *
  *  With no arguments, sets the default visibility for subsequently
  *  defined methods to private. With arguments, sets the named methods
  *  to have private visibility.
+ *  String arguments are converted to symbols.
  *
  *     module Mod
  *       def a()  end
@@ -1351,8 +1369,11 @@ rb_mod_private(int argc, VALUE *argv, VALUE module)
 /*
  *  call-seq:
  *     mod.public_class_method(symbol, ...)    -> mod
+ *     mod.public_class_method(string, ...)    -> mod
  *
  *  Makes a list of existing class methods public.
+ *
+ *  String arguments are converted to symbols.
  */
 
 static VALUE
@@ -1365,10 +1386,13 @@ rb_mod_public_method(int argc, VALUE *argv, VALUE obj)
 /*
  *  call-seq:
  *     mod.private_class_method(symbol, ...)   -> mod
+ *     mod.private_class_method(string, ...)   -> mod
  *
  *  Makes existing class methods private. Often used to hide the default
  *  constructor <code>new</code>.
  *
+ *  String arguments are converted to symbols.
+ *
  *     class SimpleSingleton  # Not thread safe
  *       private_class_method :new
  *       def SimpleSingleton.create(*args, &block)
@@ -1389,10 +1413,13 @@ rb_mod_private_method(int argc, VALUE *argv, VALUE obj)
  *  call-seq:
  *     public
  *     public(symbol, ...)
+ *     public(string, ...)
  *
  *  With no arguments, sets the default visibility for subsequently
  *  defined methods to public. With arguments, sets the named methods to
  *  have public visibility.
+ *
+ *  String arguments are converted to symbols.
  */
 
 static VALUE
@@ -1410,6 +1437,7 @@ top_private(int argc, VALUE *argv)
 /*
  *  call-seq:
  *     module_function(symbol, ...)    -> self
+ *     module_function(string, ...)    -> self
  *
  *  Creates module functions for the named methods. These functions may
  *  be called with the module as a receiver, and also become available
@@ -1418,6 +1446,7 @@ top_private(int argc, VALUE *argv)
  *  independently. The instance-method versions are made private. If
  *  used with no arguments, subsequently defined methods become module
  *  functions.
+ *  String arguments are converted to symbols.
  *
  *     module Mod
  *       def one
@@ -1562,6 +1591,7 @@ rb_respond_to(VALUE obj, ID id)
 /*
  *  call-seq:
  *     obj.respond_to?(symbol, include_all=false) -> true or false
+ *     obj.respond_to?(string, include_all=false) -> true or false
  *
  *  Returns +true+ if _obj_ responds to the given method.  Private and
  *  protected methods are included in the search only if the optional
@@ -1573,6 +1603,9 @@ rb_respond_to(VALUE obj, ID id)
  *
  *  If the method is not defined, <code>respond_to_missing?</code>
  *  method is called and the result is returned.
+ *
+ *  When the method name parameter is given as a string, the string is
+ *  converted to a symbol.
  */
 
 static VALUE
@@ -1599,12 +1632,16 @@ obj_respond_to(int argc, VALUE *argv, VALUE obj)
 /*
  *  call-seq:
  *     obj.respond_to_missing?(symbol, include_all) -> true or false
+ *     obj.respond_to_missing?(string, include_all) -> true or false
  *
  *  DO NOT USE THIS DIRECTLY.
  *
  *  Hook method to return whether the _obj_ can respond to _id_ method
  *  or not.
  *
+ *  When the method name parameter is given as a string, the string is
+ *  converted to a symbol.
+ *
  *  See #respond_to?.
  */
 static VALUE