Improve documentation coverage and markup

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

2 files changed, 8 insertions, 7 deletions

diff --git a/activeresource/lib/active_resource/base.rb b/activeresource/lib/active_resource/base.rb
index 4072b9494d..eff92c91de 100644
--- a/activeresource/lib/active_resource/base.rb
+++ b/activeresource/lib/active_resource/base.rb
@@ -457,13 +457,14 @@ module ActiveResource
       # The first argument is considered to be the scope of the query.  That is, how many 
       # resources are returned from the request.  It can be one of the following.
       #
-      # +:one+:: Returns a single resource.
-      # +:first+:: Returns the first resource found.
-      # +:all+:: Returns every resource that matches the request.
+      # * <tt>:one</tt>: Returns a single resource.
+      # * <tt>:first</tt>: Returns the first resource found.
+      # * <tt>:all</tt>: Returns every resource that matches the request.
       # 
       # ==== Options
-      # +from+:: Sets the path or custom method that resources will be fetched from.
-      # +params+:: Sets query and prefix (nested URL) parameters.
+      #
+      # * +from+: Sets the path or custom method that resources will be fetched from.
+      # * +params+: Sets query and prefix (nested URL) parameters.
       #
       # ==== Examples
       #   Person.find(1)                                         
diff --git a/activeresource/lib/active_resource/connection.rb b/activeresource/lib/active_resource/connection.rb
index 46e3d1f4e3..0c4ea432d7 100644
--- a/activeresource/lib/active_resource/connection.rb
+++ b/activeresource/lib/active_resource/connection.rb
@@ -128,8 +128,8 @@ module ActiveResource
     end
 
     # Execute a HEAD request.
-    # Used to ...
-    def head(path, headers= {})
+    # Used to obtain meta-information about resources, such as whether they exist and their size (via response headers).
+    def head(path, headers = {})
       request(:head, path, build_request_headers(headers))
     end