Improve documentation.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@9093 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

4 files changed, 61 insertions, 6 deletions

diff --git a/activesupport/lib/active_support/core_ext/module/attr_internal.rb b/activesupport/lib/active_support/core_ext/module/attr_internal.rb
index 7f2fb9641b..e0be31090c 100644
--- a/activesupport/lib/active_support/core_ext/module/attr_internal.rb
+++ b/activesupport/lib/active_support/core_ext/module/attr_internal.rb
@@ -13,7 +13,8 @@ class Module
     end
   end
 
-  # Declare attributes backed by 'internal' instance variables names.
+  # Declare an attribute reader and writer backed by an internally-named instance
+  # variable.
   def attr_internal_accessor(*attrs)
     attr_internal_reader(*attrs)
     attr_internal_writer(*attrs)
diff --git a/activesupport/lib/active_support/core_ext/module/inclusion.rb b/activesupport/lib/active_support/core_ext/module/inclusion.rb
index efc00d6f28..4f23841645 100644
--- a/activesupport/lib/active_support/core_ext/module/inclusion.rb
+++ b/activesupport/lib/active_support/core_ext/module/inclusion.rb
@@ -1,4 +1,23 @@
 class Module
+  # Returns the classes in the current ObjectSpace where this module has been
+  # mixed in according to Module#included_modules.
+  #
+  #   module M
+  #   end
+  #   
+  #   module N
+  #     include M
+  #   end
+  #   
+  #   class C
+  #     include M
+  #   end
+  #   
+  #   class D < C
+  #   end
+  #
+  #   p M.included_in_classes # => [C, D]
+  #
   def included_in_classes
     classes = []
     ObjectSpace.each_object(Class) { |k| classes << k if k.included_modules.include?(self) }
diff --git a/activesupport/lib/active_support/core_ext/module/introspection.rb b/activesupport/lib/active_support/core_ext/module/introspection.rb
index ddc9297b95..40bbebb7c4 100644
--- a/activesupport/lib/active_support/core_ext/module/introspection.rb
+++ b/activesupport/lib/active_support/core_ext/module/introspection.rb
@@ -1,13 +1,38 @@
 class Module
-  # Return the module which contains this one; if this is a root module, such as
-  # +::MyModule+, then Object is returned.
+  # Returns the module which contains this one according to its name.
+  #
+  #   module M
+  #     module N
+  #     end
+  #   end
+  #   X = M::N
+  #   
+  #   p M::N.parent # => M
+  #   p X.parent    # => M
+  #
+  # The parent of top-level and anonymous modules is Object.
+  #
+  #   p M.parent          # => Object
+  #   p Module.new.parent # => Object
+  #
   def parent
     parent_name = name.split('::')[0..-2] * '::'
     parent_name.empty? ? Object : parent_name.constantize
   end
 
-  # Return all the parents of this module, ordered from nested outwards. The
-  # receiver is not contained within the result.
+  # Returns all the parents of this module according to its name, ordered from
+  # nested outwards. The receiver is not contained within the result.
+  #
+  #   module M
+  #     module N
+  #     end
+  #   end
+  #   X = M::N
+  #   
+  #   p M.parents    # => [Object]
+  #   p M::N.parents # => [M, Object]
+  #   p X.parents    # => [M, Object]
+  #
   def parents
     parents = []
     parts = name.split('::')[0..-2]
@@ -20,7 +45,7 @@ class Module
   end
 
   if RUBY_VERSION < '1.9'
-    # Return the constants that have been defined locally by this object and
+    # Returns the constants that have been defined locally by this object and
     # not in an ancestor. This method is exact if running under Ruby 1.9. In
     # previous versions it may miss some constants if their definition in some
     # ancestor is identical to their definition in the receiver.
diff --git a/activesupport/lib/active_support/core_ext/module/loading.rb b/activesupport/lib/active_support/core_ext/module/loading.rb
index 36c0c61405..4b4b110b25 100644
--- a/activesupport/lib/active_support/core_ext/module/loading.rb
+++ b/activesupport/lib/active_support/core_ext/module/loading.rb
@@ -1,4 +1,14 @@
 class Module
+  # Returns String#underscore applied to the module name minus trailing classes.
+  #
+  #   ActiveRecord.as_load_path               # => "active_record"
+  #   ActiveRecord::Associations.as_load_path # => "active_record/associations"
+  #   ActiveRecord::Base.as_load_path         # => "active_record" (Base is a class)
+  #
+  # The Kernel module gives an empty string by definition.
+  #
+  #   Kernel.as_load_path # => ""
+  #   Math.as_load_path   # => "math"
   def as_load_path
     if self == Object || self == Kernel
       ''