diff --git a/lib/fog/aws/requests/storage/head_object.rb b/lib/fog/aws/requests/storage/head_object.rb
index 342225a46..a67194017 100644
--- a/lib/fog/aws/requests/storage/head_object.rb
+++ b/lib/fog/aws/requests/storage/head_object.rb
@@ -3,30 +3,30 @@ module Fog
     class AWS
       class Real
 
+        #
         # Get headers for an object from S3
         #
-        # ==== Parameters
-        # * bucket_name<~String> - Name of bucket to read from
-        # * object_name<~String> - Name of object to read
-        # * options<~Hash>:
-        #   * 'If-Match'<~String> - Returns object only if its etag matches this value, otherwise returns 412 (Precondition Failed).
-        #   * 'If-Modified-Since'<~Time> - Returns object only if it has been modified since this time, otherwise returns 304 (Not Modified).
-        #   * 'If-None-Match'<~String> - Returns object only if its etag differs from this value, otherwise returns 304 (Not Modified)
-        #   * 'If-Unmodified-Since'<~Time> - Returns object only if it has not been modified since this time, otherwise returns 412 (Precodition Failed).
-        #   * 'Range'<~String> - Range of object to download
-        #   * 'versionId'<~String> - specify a particular version to retrieve
+        # @param bucket_name [String] Name of bucket to read from
+        # @param object_name [String] Name of object to read
+        # @param options [Hash]: 
+        # @option options [String] If-Match Returns object only if its etag matches this value, otherwise returns 412 (Precondition Failed).
+        # @option options [Time]   If-Modified-Since Returns object only if it has been modified since this time, otherwise returns 304 (Not Modified).
+        # @option options [String] If-None-Match Returns object only if its etag differs from this value, otherwise returns 304 (Not Modified)
+        # @option options [Time]   If-Unmodified-Since Returns object only if it has not been modified since this time, otherwise returns 412 (Precodition Failed).
+        # @option options [String] Range Range of object to download
+        # @option options [String] versionId specify a particular version to retrieve
+        # 
+        # @return [Excon::Response] response: 
+        #   * body [String] Contents of object
+        #   * headers [Hash]: 
+        #     * Content-Length [String] - Size of object contents
+        #     * Content-Type [String] - MIME type of object
+        #     * ETag [String] - Etag of object
+        #     * Last-Modified - [String] Last modified timestamp for object
+        # 
+        # @see http://docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectHEAD.html
         #
-        # ==== Returns
-        # * response<~Excon::Response>:
-        #   * body<~String> - Contents of object
-        #   * headers<~Hash>:
-        #     * 'Content-Length'<~String> - Size of object contents
-        #     * 'Content-Type'<~String> - MIME type of object
-        #     * 'ETag'<~String> - Etag of object
-        #     * 'Last-Modified'<~String> - Last modified timestamp for object
-        #
-        # ==== See Also
-        # http://docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectHEAD.html
+
 
         def head_object(bucket_name, object_name, options={})
           unless bucket_name
diff --git a/lib/fog/aws/requests/storage/initiate_multipart_upload.rb b/lib/fog/aws/requests/storage/initiate_multipart_upload.rb
index 57e926d6e..a570ef95a 100644
--- a/lib/fog/aws/requests/storage/initiate_multipart_upload.rb
+++ b/lib/fog/aws/requests/storage/initiate_multipart_upload.rb
@@ -5,30 +5,29 @@ module Fog
 
         require 'fog/aws/parsers/storage/initiate_multipart_upload'
 
+        #
         # Initiate a multipart upload to an S3 bucket
         #
-        # ==== Parameters
-        # * bucket_name<~String> - Name of bucket to create object in
-        # * object_name<~String> - Name of object to create
-        # * options<~Hash>:
-        #   * 'Cache-Control'<~String> - Caching behaviour
-        #   * 'Content-Disposition'<~String> - Presentational information for the object
-        #   * 'Content-Encoding'<~String> - Encoding of object data
-        #   * 'Content-MD5'<~String> - Base64 encoded 128-bit MD5 digest of message (defaults to Base64 encoded MD5 of object.read)
-        #   * 'Content-Type'<~String> - Standard MIME type describing contents (defaults to MIME::Types.of.first)
-        #   * 'x-amz-acl'<~String> - Permissions, must be in ['private', 'public-read', 'public-read-write', 'authenticated-read']
-        #   * "x-amz-meta-#{name}" - Headers to be returned with object, note total size of request without body must be less than 8 KB.
+        # @param bucket_name [String] Name of bucket to create object in
+        # @param object_name [String] Name of object to create
+        # @param options [Hash]: 
+        # @option options [String] Cache-Control Caching behaviour
+        # @option options [String] Content-Disposition Presentational information for the object
+        # @option options [String] Content-Encoding Encoding of object data
+        # @option options [String] Content-MD5 Base64 encoded 128-bit MD5 digest of message (defaults to Base64 encoded MD5 of object.read)
+        # @option options [String] Content-Type Standard MIME type describing contents (defaults to MIME::Types.of.first)
+        # @option options [String] x-amz-acl Permissions, must be in ['private', 'public-read', 'public-read-write', 'authenticated-read']
+        # @option options [String] x-amz-meta-#{name} Headers to be returned with object, note total size of request without body must be less than 8 KB.
         #
-        # ==== Returns
-        # * response<~Excon::Response>:
-        #   * body<~Hash>:
-        #     * 'Bucket'<~String> - Bucket where upload was initiated
-        #     * 'Key'<~String> - Object key where the upload was initiated
-        #     * 'UploadId'<~String> - Id for initiated multipart upload
+        # @return [Excon::Response] response: 
+        #   * body [Hash]: 
+        #     * Bucket [String] - Bucket where upload was initiated
+        #     * Key [String] - Object key where the upload was initiated
+        #     * UploadId [String] - Id for initiated multipart upload
         #
-        # ==== See Also
-        # http://docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadInitiate.html
+        # @see http://docs.amazonwebservices.com/AmazonS3/latest/API/mpUploadInitiate.html
         #
+        
         def initiate_multipart_upload(bucket_name, object_name, options = {})
           request({
             :expects    => 200,