Adding ActiveModel::Naming documentation

2 files changed, 35 insertions, 1 deletions

diff --git a/activemodel/README b/activemodel/README
index d4b4489a2c..710f502aa3 100644
--- a/activemodel/README
+++ b/activemodel/README
@@ -113,7 +113,24 @@ functionality from the following modules:
 
 * Testing the compliance of your object
 
-    User ActiveModel::Lint to test the compliance of your object to the
+    Use ActiveModel::Lint to test the compliance of your object to the
     basic ActiveModel API...
     
   {Learn more}[link:classes/ActiveModel/Lint/Tests.html]
+
+* Providing a human face to your object
+
+    ActiveModel::Naming provides your model with the model_name convention
+    and a human_name attribute...
+    
+    class NamedPerson
+      extend ActiveModel::Naming
+    end
+    
+    ...gives you...
+    
+    NamedPerson.model_name        #=> "NamedPerson"
+    NamedPerson.model_name.human  #=> "Named person"
+
+  {Learn more}[link:classes/ActiveModel/Naming.html]
+
diff --git a/activemodel/lib/active_model/naming.rb b/activemodel/lib/active_model/naming.rb
index 4cd68a0c89..b9fb5fe0c8 100644
--- a/activemodel/lib/active_model/naming.rb
+++ b/activemodel/lib/active_model/naming.rb
@@ -1,6 +1,7 @@
 require 'active_support/inflector'
 
 module ActiveModel
+
   class Name < String
     attr_reader :singular, :plural, :element, :collection, :partial_path
     alias_method :cache_key, :collection
@@ -35,6 +36,21 @@ module ActiveModel
     end
   end
 
+  # ActiveModel::Naming is a module that creates a +model_name+ method on your
+  # object.
+  # 
+  # To implement, just extend ActiveModel::Naming in your object:
+  # 
+  #   class BookCover
+  #     exten ActiveModel::Naming
+  #   end
+  # 
+  #   BookCover.model_name        #=> "BookCover"
+  #   BookCover.model_name.human  #=> "Book cover"
+  # 
+  # Providing the functionality that ActiveModel::Naming provides in your object
+  # is required to pass the ActiveModel Lint test.  So either extending the provided
+  # method below, or rolling your own is required..
   module Naming
     # Returns an ActiveModel::Name object for module. It can be
     # used to retrieve all kinds of naming-related information.
@@ -42,4 +58,5 @@ module ActiveModel
       @_model_name ||= ActiveModel::Name.new(self)
     end
   end
+  
 end