Thoroughly document inflections. Closes #5700.

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

activesupport/CHANGELOG

 *SVN*
 
+* Thoroughly document inflections.  #5700 [petermichaux@gmail.com]
+
 * Added Module#alias_attribute [Jamis/DHH]. Example:
 
     class Content < ActiveRecord::Base

activesupport/lib/active_support/core_ext/string/inflections.rb

@@ -11,8 +11,11 @@ module Inflections
         #
         # Examples
         #   "post".pluralize #=> "posts"
+        #   "octopus".pluralize #=> "octopi"
         #   "sheep".pluralize #=> "sheep"
+        #   "words".pluralize #=> "words"
         #   "the blue mailman".pluralize #=> "the blue mailmen"
+        #   "CamelOctopus".pluralize #=> "CamelOctopi"
         def pluralize
           Inflector.pluralize(self)
         end
@@ -20,17 +23,26 @@ def pluralize
         # The reverse of pluralize, returns the singular form of a word in a string.
         #
         # Examples
-        #   "posts".singularize => "post"
-        #   "the blue mailmen".pluralize #=> "the blue mailman"
+        #   "posts".singularize #=> "post"
+        #   "octopi".singularize #=> "octopus"
+        #   "sheep".singluarize #=> "sheep"
+        #   "word".singluarize #=> "word"
+        #   "the blue mailmen".singularize #=> "the blue mailman"
+        #   "CamelOctopi".singularize #=> "CamelOctopus"
         def singularize
           Inflector.singularize(self)
         end
 
-        # Creates a camelcased name from an underscored name. CamelCased names LookLikeThis and under_scored_names look_like_this.
+        # By default, camelize converts strings to UpperCamelCase. If the argument to camelize
+        # is set to ":lower" then camelize produces lowerCamelCase.
+        #
+        # camelize will also convert '/' to '::' which is useful for converting paths to namespaces 
         #
         # Examples
         #   "active_record".camelize #=> "ActiveRecord"
-        #   "raw_scaled_scorer".camelize #=> "RawScaledScorer"
+        #   "active_record".camelize(:lower) #=> "activeRecord"
+        #   "active_record/errors".camelize #=> "ActiveRecord::Errors"
+        #   "active_record/errors".camelize(:lower) #=> "activeRecord::Errors"
         def camelize(first_letter = :upper)
           case first_letter
             when :upper then Inflector.camelize(self, true)
@@ -39,7 +51,11 @@ def camelize(first_letter = :upper)
         end
         alias_method :camelcase, :camelize
 
-        # Capitalizes all the words and replaces some characters in the string to create a nicer looking title.
+        # Capitalizes all the words and replaces some characters in the string to create
+        # a nicer looking title. Titleize is meant for creating pretty output. It is not
+        # used in the Rails internals.
+        #
+        # titleize is also aliased as as titlecase
         #
         # Examples
         #   "man from the boondocks".titleize #=> "Man From The Boondocks"
@@ -50,15 +66,17 @@ def titleize
         alias_method :titlecase, :titleize
 
         # The reverse of +camelize+. Makes an underscored form from the expression in the string.
+        # 
+        # Changes '::' to '/' to convert namespaces to paths.
         #
         # Examples
         #   "ActiveRecord".underscore #=> "active_record"
-        #   "RawScaledScore".underscore #=> "raw_scaled_score"
+        #   "ActiveRecord::Errors".underscore #=> active_record/errors
         def underscore
           Inflector.underscore(self)
         end
 
-        # Replaces underscores with dashes in the string
+        # Replaces underscores with dashes in the string.
         #
         # Example
         #   "puni_puni" #=> "puni-puni"
@@ -75,16 +93,20 @@ def demodulize
           Inflector.demodulize(self)
         end
 
-        # Create the name of a table like Rails does for models to table names.
+        # Create the name of a table like Rails does for models to table names. This method
+        # uses the pluralize method on the last word in the string.
         #
         # Examples
         #   "RawScaledScorer".tableize #=> "raw_scaled_scorers"
         #   "egg_and_ham".tableize #=> "egg_and_hams"
+        #   "fancyCategory".tableize #=> "fancy_categories"
         def tableize
           Inflector.tableize(self)
         end
 
-        # Create a class name from a table name like Rails does for table names to models. Note that this returns a string and not a Class.
+        # Create a class name from a table name like Rails does for table names to models.
+        # Note that this returns a string and not a Class. (To convert to an actual class
+        # follow classify with constantize.)
         #
         # Examples
         #   "egg_and_hams".classify #=> "EggAndHam"
@@ -94,6 +116,7 @@ def classify
         end
         
         # Capitalizes the first word and turns underscores into spaces and strips _id.
+        # Like titleize, this is meant for creating pretty output.
         #
         # Examples
         #   "employee_salary" #=> "Employee salary" 
@@ -102,7 +125,9 @@ def humanize
           Inflector.humanize(self)
         end
 
-        # Creates a foreign key name from a class name. +separate_class_name_and_id_with_underscore+ sets whether the method should put '_' between the name and 'id'.
+        # Creates a foreign key name from a class name.
+        # +separate_class_name_and_id_with_underscore+ sets whether
+        # the method should put '_' between the name and 'id'.
         #
         # Examples
         #   "Message".foreign_key #=> "message_id"
@@ -112,7 +137,9 @@ def foreign_key(separate_class_name_and_id_with_underscore = true)
           Inflector.foreign_key(self, separate_class_name_and_id_with_underscore)
         end
 
-        # Constantize tries to find a declared constant with the name specified in the string. It raises a NameError when the name is not in CamelCase or is not initialized.
+        # Constantize tries to find a declared constant with the name specified
+        # in the string. It raises a NameError when the name is not in CamelCase
+        # or is not initialized.
         #
         # Examples
         #   "Module".constantize #=> Module