More documentation cleanup

lib/google/api_client/batch.rb

@@ -24,9 +24,13 @@ module Google
     #
     # @api private
     class BatchedCallResponse
+      # @return [String] UUID of the call
       attr_reader :call_id
-      attr_accessor :status 
+      # @return [Integer] HTTP status code
+      attr_accessor :status
+      # @return [Hash] HTTP response headers
       attr_accessor :headers
+      # @return [String] HTTP response body
       attr_accessor :body
 
       ##
@@ -64,7 +68,9 @@ module Google
     class BatchRequest < Request
       BATCH_BOUNDARY = "-----------RubyApiBatchRequest".freeze
 
-      attr_reader :calls, :callbacks
+      # @api private
+      # @return [Array<(String,Google::APIClient::Request,Proc)] List of API calls in the batch
+      attr_reader :calls
 
       ##
       # Creates a new batch request.

lib/google/api_client/media.rb

@@ -36,6 +36,7 @@ module Google
     # Resumable uploader.
     #
     class ResumableUpload < Request
+      # @return [Fixnum] Max bytes to send in a single request
       attr_accessor :chunk_size
   
       ##
@@ -162,6 +163,10 @@ module Google
         return Google::APIClient::Result.new(self, response)
       end
       
+      ##
+      # Hashified verison of the API request
+      #
+      # @return [Hash]
       def to_hash
         super.merge(:offset => @offset)
       end

lib/google/api_client/reference.rb

@@ -28,8 +28,20 @@ module Google
     class Request
       MULTIPART_BOUNDARY = "-----------RubyApiMultipartPost".freeze
       
-      attr_reader :parameters, :headers, :api_method
-      attr_accessor :connection, :media, :authorization, :authenticated, :body
+      # @return [Hash] Request parameters
+      attr_reader :parameters
+      # @return [Hash] Additional HTTP headers
+      attr_reader :headers
+      # @return [Google::APIClient::Method] API method to invoke
+      attr_reader :api_method
+      # @return [Google::APIClient::UploadIO] File to upload
+      attr_accessor :media
+      # @return [#generated_authenticated_request] User credentials
+      attr_accessor :authorization
+      # @return [TrueClass,FalseClass] True if request should include credentials
+      attr_accessor :authenticated
+      # @return [#read, #to_str] Request body
+      attr_accessor :body
       
       ##
       # Build a request
@@ -84,11 +96,15 @@ module Google
           self.uri = options[:uri]
         end
       end
-
+      
+      # @!attribute [r] upload_type
+      # @return [String] protocol used for upload
       def upload_type
         return self.parameters['uploadType'] || self.parameters['upload_type']
       end
 
+      # @!attribute http_method
+      # @return [Symbol] HTTP method if invoking a URI
       def http_method
         return @http_method ||= self.api_method.http_method.to_s.downcase.to_sym
       end
@@ -113,6 +129,8 @@ module Google
         end
       end
       
+      # @!attribute uri
+      # @return [Addressable::URI] URI to send request
       def uri
         return @uri ||= self.api_method.generate_uri(self.parameters)
       end
@@ -122,6 +140,7 @@ module Google
         @parameters.update(@uri.query_values) unless @uri.query_values.nil?
       end
 
+
       # Transmits the request with the given connection
       #
       # @api private
@@ -313,7 +332,12 @@ module Google
       end
 
     end
-  
+    
+    ##
+    # Subclass of Request for backwards compatibility with pre-0.5.0 versions of the library
+    # 
+    # @deprecated
+    #   use {Google::APIClient::Request} instead
     class Reference < Request
     end
   end

lib/google/api_client/result.rb

@@ -33,8 +33,13 @@ module Google
         @media_upload = reference if reference.kind_of?(ResumableUpload)
       end
 
+      # @return [Google::APIClient::Request] Original request object
       attr_reader :request
+      # @return [Faraday::Response] HTTP response
       attr_reader :response
+      # @!attribute [r] reference
+      #   @return [Google::APIClient::Request] Original request object
+      #   @deprecated See {#request}
       alias_method :reference, :request # For compatibility with pre-beta clients
 
       # @!attribute [r] status
@@ -45,6 +50,8 @@ module Google
       #   @return [String] HTTP response body
       def_delegators :@response, :status, :headers, :body
 
+      # @!attribute [r] resumable_upload
+      # @return [Google::APIClient::ResumableUpload] For resuming media uploads
       def resumable_upload        
         @media_upload ||= (
           options = self.reference.to_hash.merge(
@@ -57,7 +64,7 @@ module Google
       
       ##
       # Get the content type of the response
-      #
+      # @!attribute [r] media_type
       # @return [String]
       #  Value of content-type header
       def media_type
@@ -70,6 +77,7 @@ module Google
       ##
       # Check if request failed
       #
+      # @!attribute [r] error?
       # @return [TrueClass, FalseClass]
       #   true if result of operation is an error
       def error?
@@ -79,6 +87,7 @@ module Google
       ##
       # Check if request was successful
       #
+      # @!attribute [r] success?
       # @return [TrueClass, FalseClass]
       #   true if result of operation was successful
       def success?
@@ -88,6 +97,7 @@ module Google
       ##
       # Extracts error messages from the response body
       #
+      # @!attribute [r] error_message
       # @return [String]
       #   error message, if available
       def error_message
@@ -107,6 +117,7 @@ module Google
       ##
       # Check for parsable data in response
       #
+      # @!attribute [r] data?
       # @return [TrueClass, FalseClass]
       #   true if body can be parsed
       def data?
@@ -116,6 +127,7 @@ module Google
       ##
       # Return parsed version of the response body.
       #
+      # @!attribute [r] data
       # @return [Object, Hash, String]
       #   Object if body parsable from API schema, Hash if JSON, raw body if unable to parse
       def data
@@ -147,6 +159,7 @@ module Google
       ##
       # Get the token used for requesting the next page of data
       #
+      # @!attribute [r] next_page_token
       # @return [String]
       #   next page token
       def next_page_token
@@ -179,6 +192,7 @@ module Google
       ##
       # Get the token used for requesting the previous page of data
       #
+      # @!attribute [r] prev_page_token
       # @return [String]
       #   previous page token
       def prev_page_token
@@ -208,10 +222,22 @@ module Google
         )
       end
       
+      ##
+      # Pagination scheme used by this request/response
+      #
+      # @!attribute [r] pagination_type
+      # @return [Symbol]
+      #  currently always :token
       def pagination_type
         return :token
       end
 
+      ##
+      # Name of the field that contains the pagination token
+      #
+      # @!attribute [r] page_token_param
+      # @return [String]
+      #  currently always 'pageToken'
       def page_token_param
         return "pageToken"
       end

lib/google/api_client/service_account.rb

@@ -65,8 +65,15 @@ module Google
     #    client.authorization = service_account.authorize
     #    client.execute(...)
     class JWTAsserter
-      attr_accessor :issuer, :expiry, :skew
+      # @return [String] ID/email of the issuing party
+      attr_accessor :issuer
+      # @return [Fixnum] How long, in seconds, the assertion is valid for
+      attr_accessor :expiry
+      # @return [Fixnum] Seconds to expand the issued at/expiry window to account for clock skew
+      attr_accessor :skew
+      # @return [String] Scopes to authorize
       attr_reader :scope
+      # @return [OpenSSL::PKey] key for signing assertions
       attr_writer :key
 
       ##
@@ -74,7 +81,7 @@ module Google
       #
       # @param [String] issuer
       #    Name/ID of the client issuing the assertion
-      # @param [String or Array] scope
+      # @param [String, Array] scope
       #   Scopes to authorize. May be a space delimited string or array of strings
       # @param [OpenSSL::PKey] key
       #   RSA private key for signing assertions