1 files changed, 23 insertions, 18 deletions
diff --git a/variable.c b/variable.c
index de3a3561f8..1a4f919c4c 100644
--- a/variable.c
+++ b/variable.c
@@ -162,21 +162,21 @@ is_constant_path(VALUE name)
  *     mod.set_temporary_name(string) -> self
  *     mod.set_temporary_name(nil) -> self
  *
- *  Sets the temporary name of the module +mod+. This name is used as a prefix
- *  for the names of constants declared in +mod+. If the module is assigned a
- *  permanent name, the temporary name is discarded.
+ *  Sets the temporary name of the module. This name is reflected in
+ *  introspection of the module and the values that are related to it, such
+ *  as instances, constants, and methods.
  *
- *  After a permanent name is assigned, a temporary name can no longer be set,
- *  and this method raises a RuntimeError.
+ *  The name should be +nil+ or non-empty string that is not a valid constant
+ *  name (to avoid confusing between permanent and temporary names).
  *
- *  If the name given is not a string or is a zero length string, this method
- *  raises an ArgumentError.
+ *  The method can be useful to distinguish dynamically generated classes and
+ *  modules without assigning them to constants.
  *
- *  The temporary name must not be a valid constant name, to avoid confusion
- *  with actual constants. If you attempt to set a temporary name that is a
- *  a valid constant name, this method raises an ArgumentError.
+ *  If the module is given a permanent name by assigning it to a constant,
+ *  the temporary name is discarded. A temporary name can't be assigned to
+ *  modules that have a permanent name.
  *
- *  If the given name is +nil+, the module becomes anonymous.
+ *  If the given name is +nil+, the module becomes anonymous again.
  *
  *  Example:
  *
@@ -189,15 +189,20 @@ is_constant_path(VALUE name)
  *    m.set_temporary_name(nil) # => #<Module:0x0000000102c68f38>
  *    m.name #=> nil
  *
- *    n = Module.new
- *    n.set_temporary_name("fake_name")
+ *    c = Class.new
+ *    c.set_temporary_name("MyClass(with description)")
  *
- *    n::M = m
- *    n::M.name #=> "fake_name::M"
- *    N = n
+ *    c.new # => #<MyClass(with description):0x0....>
  *
- *    N.name #=> "N"
- *    N::M.name #=> "N::M"
+ *    c::M = m
+ *    c::M.name #=> "MyClass(with description)::M"
+ *
+ *    # Assigning to a constant replaces the name with a permanent one
+ *    C = c
+ *
+ *    C.name #=> "C"
+ *    C::M.name #=> "C::M"
+ *    c.new # => #<C:0x0....>
  */
 
 VALUE