Improve documentation coverage and markup

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

3 files changed, 14 insertions, 13 deletions

diff --git a/actionpack/lib/action_controller/routing/builder.rb b/actionpack/lib/action_controller/routing/builder.rb
index 50064055f4..b1a98d1a51 100644
--- a/actionpack/lib/action_controller/routing/builder.rb
+++ b/actionpack/lib/action_controller/routing/builder.rb
@@ -124,7 +124,7 @@ module ActionController
         route_requirements
       end
 
-      # Assign default options, such as 'index' as a default for :action. This
+      # Assign default options, such as 'index' as a default for <tt>:action</tt>. This
       # method must be run *after* user supplied requirements and defaults have
       # been applied to the segments.
       def assign_default_route_options(segments)
@@ -187,7 +187,7 @@ module ActionController
         end
 
         # Routes cannot use the current string interpolation method
-        # if there are user-supplied :requirements as the interpolation
+        # if there are user-supplied <tt>:requirements</tt> as the interpolation
         # code won't raise RoutingErrors when generating
         if options.key?(:requirements) || route.requirements.keys.to_set != Routing::ALLOWED_REQUIREMENTS_FOR_OPTIMISATION
           route.optimise = false
diff --git a/actionpack/lib/action_controller/routing/optimisations.rb b/actionpack/lib/action_controller/routing/optimisations.rb
index ba4aeb4e82..534cf10315 100644
--- a/actionpack/lib/action_controller/routing/optimisations.rb
+++ b/actionpack/lib/action_controller/routing/optimisations.rb
@@ -1,11 +1,11 @@
 module ActionController
   module Routing
     # Much of the slow performance from routes comes from the 
-    # complexity of expiry, :requirements matching, defaults providing
+    # complexity of expiry, <tt>:requirements</tt> matching, defaults providing
     # and figuring out which url pattern to use.  With named routes 
     # we can avoid the expense of finding the right route.  So if 
     # they've provided the right number of arguments, and have no
-    # :requirements, we can just build up a string and return it.
+    # <tt>:requirements</tt>, we can just build up a string and return it.
     # 
     # To support building optimisations for other common cases, the 
     # generation code is separated into several classes 
@@ -41,19 +41,20 @@ module ActionController
           end
         end
 
-        # Temporarily disabled :url optimisation pending proper solution to 
+        # Temporarily disabled <tt>:url</tt> optimisation pending proper solution to
         # Issues around request.host etc.
         def applicable?
           true
         end
       end
 
-      # Given a route:
-      # map.person '/people/:id'
+      # Given a route
       #
-      # If the user calls person_url(@person), we can simply
+      #   map.person '/people/:id'
+      #
+      # If the user calls <tt>person_url(@person)</tt>, we can simply
       # return a string like "/people/#{@person.to_param}" 
-      # rather than triggering the expensive logic in url_for
+      # rather than triggering the expensive logic in +url_for+.
       class PositionalArguments < Optimiser
         def guard_condition
           number_of_arguments = route.segment_keys.size
@@ -77,7 +78,7 @@ module ActionController
 
           elements << '#{request.relative_url_root if request.relative_url_root}'
 
-          # The last entry in route.segments appears to # *always* be a
+          # The last entry in <tt>route.segments</tt> appears to *always* be a
           # 'divider segment' for '/' but we have assertions to ensure that
           # we don't include the trailing slashes, so skip them.
           (route.segments.size == 1 ? route.segments : route.segments[0..-2]).each do |segment|
@@ -106,7 +107,7 @@ module ActionController
           super.insert(-2, '?#{args.last.to_query}')
         end
 
-        # To avoid generating http://localhost/?host=foo.example.com we
+        # To avoid generating "http://localhost/?host=foo.example.com" we
         # can't use this optimisation on routes without any segments
         def applicable?
           super && route.segment_keys.size > 0 
diff --git a/actionpack/lib/action_controller/routing/route.rb b/actionpack/lib/action_controller/routing/route.rb
index a83a599e35..a0d108ba03 100644
--- a/actionpack/lib/action_controller/routing/route.rb
+++ b/actionpack/lib/action_controller/routing/route.rb
@@ -139,8 +139,8 @@ module ActionController
       # those that were not used to generate a particular route. The extra
       # keys also do not include those recalled from the prior request, nor
       # do they include any keys that were implied in the route (like a
-      # :controller that is required, but not explicitly used in the text of
-      # the route.)
+      # <tt>:controller</tt> that is required, but not explicitly used in the
+      # text of the route.)
       def extra_keys(hash, recall={})
         (hash || {}).keys.map { |k| k.to_sym } - (recall || {}).keys - significant_keys
       end