Improve documentation coverage and markup

Signed-off-by: Pratik Naik <pratiknaik@gmail.com>

1 files changed, 19 insertions, 8 deletions

diff --git a/activesupport/lib/active_support/inflector.rb b/activesupport/lib/active_support/inflector.rb
index 9f724619e9..c8736549f4 100644
--- a/activesupport/lib/active_support/inflector.rb
+++ b/activesupport/lib/active_support/inflector.rb
@@ -68,8 +68,9 @@ module Inflector
       (@uncountables << words).flatten!
     end
 
-    # Clears the loaded inflections within a given scope (default is :all). Give the scope as a symbol of the inflection type,
-    # the options are: :plurals, :singulars, :uncountables
+    # Clears the loaded inflections within a given scope (default is <tt>:all</tt>).
+    # Give the scope as a symbol of the inflection type, the options are: <tt>:plurals</tt>,
+    # <tt>:singulars</tt>, <tt>:uncountables</tt>.
     #
     # Examples:
     #   clear :all
@@ -245,13 +246,23 @@ module Inflector
     underscore(demodulize(class_name)) + (separate_class_name_and_id_with_underscore ? "_id" : "id")
   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.
+  # Tries to find a constant with the name specified in the argument string:
   #
-  # Examples
-  #   "Module".constantize #=> Module
-  #   "Class".constantize #=> Class
+  #   "Module".constantize     # => Module
+  #   "Test::Unit".constantize # => Test::Unit
+  #
+  # The name is assumed to be the one of a top-level constant, no matter whether
+  # it starts with "::" or not. No lexical context is taken into account:
+  #
+  #   C = 'outside'
+  #   module M
+  #     C = 'inside'
+  #     C               # => 'inside'
+  #     "C".constantize # => 'outside', same as ::C
+  #   end
+  #
+  # NameError is raised when the name is not in CamelCase or the constant is
+  # unknown.
   def constantize(camel_cased_word)
     unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ camel_cased_word
       raise NameError, "#{camel_cased_word.inspect} is not a valid constant name!"