1 files changed, 25 insertions, 8 deletions
diff --git a/activesupport/lib/active_support/core_ext/class/removal.rb b/activesupport/lib/active_support/core_ext/class/removal.rb
index f768313abe..10660edb2c 100644
--- a/activesupport/lib/active_support/core_ext/class/removal.rb
+++ b/activesupport/lib/active_support/core_ext/class/removal.rb
@@ -1,21 +1,38 @@
 class Class #:nodoc:
   
-  # Will unassociate the class with its subclasses as well as uninitializing the subclasses themselves.
-  # >> Integer.remove_subclasses
-  # => [Bignum, Fixnum]
-  # >> Fixnum
-  # NameError: uninitialized constant Fixnum
+  # Unassociates the class with its subclasses and removes the subclasses
+  # themselves.
+  #
+  #   Integer.remove_subclasses # => [Bignum, Fixnum]
+  #   Fixnum                    # => NameError: uninitialized constant Fixnum
   def remove_subclasses
     Object.remove_subclasses_of(self)
   end
 
-  # Returns a list of classes that inherit from this class in an array.
-  # Example: Integer.subclasses => ["Bignum", "Fixnum"]
+  # Returns an array with the names of the subclasses of +self+ as strings.
+  #
+  #   Integer.subclasses # => ["Bignum", "Fixnum"]
   def subclasses
     Object.subclasses_of(self).map { |o| o.to_s }
   end
 
-  # Allows you to remove individual subclasses or a selection of subclasses from a class without removing all of them.
+  # Removes the classes in +klasses+ from their parent module.
+  #
+  # Ordinary classes belong to some module via a constant. This method computes
+  # that constant name from the class name and removes it from the module it
+  # belongs to.
+  #
+  #   Object.remove_class(Integer) # => [Integer]
+  #   Integer                      # => NameError: uninitialized constant Integer
+  #
+  # Take into account that in general the class object could be still stored
+  # somewhere else.
+  #
+  #   i = Integer                  # => Integer
+  #   Object.remove_class(Integer) # => [Integer]
+  #   Integer                      # => NameError: uninitialized constant Integer
+  #   i.subclasses                 # => ["Bignum", "Fixnum"]
+  #   Fixnum.superclass            # => Integer
   def remove_class(*klasses)
     klasses.flatten.each do |klass|
       # Skip this class if there is nothing bound to this name