From 4d441b043749c5eb09619533a52054561c7b98fb Mon Sep 17 00:00:00 2001 From: Steven Bazyl Date: Fri, 28 Sep 2012 16:11:17 -0700 Subject: [PATCH] More documentation cleanup --- lib/google/api_client/batch.rb | 10 ++++++-- lib/google/api_client/media.rb | 5 ++++ lib/google/api_client/reference.rb | 32 +++++++++++++++++++++--- lib/google/api_client/result.rb | 28 ++++++++++++++++++++- lib/google/api_client/service_account.rb | 11 ++++++-- 5 files changed, 77 insertions(+), 9 deletions(-) diff --git a/lib/google/api_client/batch.rb b/lib/google/api_client/batch.rb index 03804821f..603554a28 100644 --- a/lib/google/api_client/batch.rb +++ b/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. diff --git a/lib/google/api_client/media.rb b/lib/google/api_client/media.rb index 312429ea0..07629c6e7 100644 --- a/lib/google/api_client/media.rb +++ b/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 diff --git a/lib/google/api_client/reference.rb b/lib/google/api_client/reference.rb index db2e10724..143ef664b 100644 --- a/lib/google/api_client/reference.rb +++ b/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 diff --git a/lib/google/api_client/result.rb b/lib/google/api_client/result.rb index 97d5bcec5..8ba0492de 100644 --- a/lib/google/api_client/result.rb +++ b/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 diff --git a/lib/google/api_client/service_account.rb b/lib/google/api_client/service_account.rb index 2b0e39008..3f1a69fe2 100644 --- a/lib/google/api_client/service_account.rb +++ b/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