update ActiveModel::Name documentation [ci skip]

1 files changed, 133 insertions, 1 deletions

diff --git a/activemodel/lib/active_model/naming.rb b/activemodel/lib/active_model/naming.rb
index 9326c2aebf..ea4f9341c6 100644
--- a/activemodel/lib/active_model/naming.rb
+++ b/activemodel/lib/active_model/naming.rb
@@ -14,9 +14,137 @@ module ActiveModel
 
     alias_method :cache_key, :collection
 
+    ##
+    # :method: ==
+    #
+    # :call-seq:
+    #   ==(other)
+    #
+    # Equivalent to <tt>String#==</tt>. Returns +true+ if the class name and
+    # +other+ are equal, otherwise +false+.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name == 'BlogPost'  # => true
+    #   BlogPost.model_name == 'Blog Post' # => false
+
+    ##
+    # :method: ===
+    #
+    # :call-seq:
+    #   ===(other)
+    #
+    # Equivalent to <tt>#==</tt>.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name === 'BlogPost'  # => true
+    #   BlogPost.model_name === 'Blog Post' # => false
+
+    ##
+    # :method: <=>
+    #
+    # :call-seq:
+    #   ==(other)
+    #
+    # Equivalent to <tt>String#<=></tt>.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name <=> 'BlogPost'  # => 0
+    #   BlogPost.model_name <=> 'Blog'      # => 1
+    #   BlogPost.model_name <=> 'BlogPosts' # => -1
+
+    ##
+    # :method: =~
+    #
+    # :call-seq:
+    #   =~(regexp)
+    #
+    # Equivalent to <tt>String#=~</tt>. Match the class name against the given
+    # regexp. Returns the position where the match starts or +nil+ if there is
+    # no match.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name =~ /Post/ # => 4
+    #   BlogPost.model_name =~ /\d/   # => nil
+
+    ##
+    # :method: !~
+    #
+    # :call-seq:
+    #   !~(regexp)
+    #
+    # Equivalent to <tt>String#!~</tt>. Match the class name against the given
+    # regexp. Returns +true+ if there is no match, otherwise +false+.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name !~ /Post/ # => false
+    #   BlogPost.model_name !~ /\d/   # => true
+
+    ##
+    # :method: eql?
+    #
+    # :call-seq:
+    #   eql?(other)
+    #
+    # Equivalent to <tt>String#eql?</tt>. Returns +true+ if the class name and
+    # +other+ have the same length and content, otherwise +false+.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name.eql?('BlogPost')  # => true
+    #   BlogPost.model_name.eql?('Blog Post') # => false
+
+    ##
+    # :method: to_s
+    #
+    # :call-seq:
+    #   to_s()
+    #
+    # Returns the class name.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
+    #
+    #   BlogPost.model_name.to_s # => "BlogPost"
+
+    ##
+    # :method: to_str
+    #
+    # :call-seq:
+    #   to_str()
+    #
+    # Equivalent to +to_s+.
     delegate :==, :===, :<=>, :=~, :"!~", :eql?, :to_s,
              :to_str, :to => :name
 
+    # Returns a new ActiveModel::Name instance. By default, the +namespace+
+    # and +name+ option will take the namespace and name of the given class
+    # respectively.
+    #
+    #   module Foo
+    #     class Bar
+    #     end
+    #   end
+    #
+    #   ActiveModel::Name.new(Foo::Bar).to_s
+    #   # => "Foo::Bar"
     def initialize(klass, namespace = nil, name = nil)
       @name = name || klass.name
 
@@ -38,7 +166,11 @@ module ActiveModel
     end
 
     # Transform the model name into a more humane format, using I18n. By default,
-    # it will underscore then humanize the class name
+    # it will underscore then humanize the class name.
+    #
+    #   class BlogPost
+    #     extend ActiveModel::Naming
+    #   end
     #
     #   BlogPost.model_name.human # => "Blog post"
     #