* object.c (Module#const_defined?): [DOC] Revise the documentation.

  Patch by Xavier Noria.
  [Fixes GH-754] https://github.com/ruby/ruby/pull/754

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

1 files changed, 29 insertions, 10 deletions

diff --git a/object.c b/object.c
index 5834c81e74..f2f6460f4d 100644
--- a/object.c
+++ b/object.c
@@ -2221,20 +2221,39 @@ rb_mod_const_set(VALUE mod, VALUE name, VALUE value)
  *     mod.const_defined?(sym, inherit=true)   -> true or false
  *     mod.const_defined?(str, inherit=true)   -> true or false
  *
- *  Checks for a constant with the given name in <i>mod</i>
- *  If +inherit+ is set, the lookup will also search
- *  the ancestors (and +Object+ if <i>mod</i> is a +Module+.)
+ *  Says whether _mod_ or its ancestors have a constant with the given name:
  *
- *  Returns whether or not a definition is found:
+ *    Float.const_defined?(:EPSILON)      #=> true, found in Float itself
+ *    Float.const_defined?("String")      #=> true, found in Object (ancestor)
+ *    BasicObject.const_defined?(:Hash)   #=> false
  *
- *     Math.const_defined? "PI"   #=> true
- *     IO.const_defined? :SYNC   #=> true
- *     IO.const_defined? :SYNC, false   #=> false
+ *  If _mod_ is a +Module+, additionally +Object+ and its ancestors are checked:
  *
- *  If neither +sym+ nor +str+ is not a valid constant name a NameError will be
- *  raised with a warning "wrong constant name".
+ *    Math.const_defined?(:String)   #=> true, found in Object
+ *
+ *  In each of the checked classes or modules, if the constant is not present
+ *  but there is an autoload for it, +true+ is returned directly without
+ *  autoloading:
+ *
+ *    module Admin
+ *      autoload :User, 'admin/user'
+ *    end
+ *    Admin.const_defined?(:User)   #=> true
+ *
+ *  If the constant is not found the callback +const_missing+ is *not* called
+ *  and the method returns +false+.
+ *
+ *  If +inherit+ is false, the lookup only checks the constants in the receiver:
+ *
+ *    IO.const_defined?(:SYNC)          #=> true, found in File::Constants (ancestor)
+ *    IO.const_defined?(:SYNC, false)   #=> false, not found in IO itself
+ *
+ *  In this case, the same logic for autoloading applies.
+ *
+ *  If the argument is not a valid constant name +NameError+ is raised with the
+ *  message "wrong constant name _name_":
  *
- *	Hash.const_defined? 'foobar' #=> NameError: wrong constant name foobar
+ *    Hash.const_defined? 'foobar'   #=> NameError: wrong constant name foobar
  *
  */