Added client documentation.

Author: marlinpierce

lib/jira/client.rb

@@ -286,41 +286,82 @@ def Agile
     end
 
     # HTTP methods without a body
+
+    # Make an HTTP DELETE request
+    # @param [String] path The path to request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def delete(path, headers = {})
       request(:delete, path, nil, merge_default_headers(headers))
     end
 
+    # Make an HTTP GET request
+    # @param [String] path The path to request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def get(path, headers = {})
       request(:get, path, nil, merge_default_headers(headers))
     end
 
+    # Make an HTTP HEAD request
+    # @param [String] path The path to request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def head(path, headers = {})
       request(:head, path, nil, merge_default_headers(headers))
     end
 
     # HTTP methods with a body
+
+    # Make an HTTP POST request
+    # @param [String] path The path to request
+    # @param [String] body The body of the request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
     def post(path, body = '', headers = {})
       headers = { 'Content-Type' => 'application/json' }.merge(headers)
       request(:post, path, body, merge_default_headers(headers))
     end
 
+    # Make an HTTP POST request with a file upload
+    # @param [String] path The path to request
+    # @param [String] file The file to upload
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def post_multipart(path, file, headers = {})
       puts "post multipart: #{path} - [#{file}]" if @http_debug
       @request_client.request_multipart(path, file, merge_default_headers(headers))
     end
 
+    # Make an HTTP PUT request
+    # @param [String] path The path to request
+    # @param [String] body The body of the request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def put(path, body = '', headers = {})
       headers = { 'Content-Type' => 'application/json' }.merge(headers)
       request(:put, path, body, merge_default_headers(headers))
     end
 
     # Sends the specified HTTP request to the REST API through the
     # appropriate method (oauth, basic).
+    # @param [Symbol] http_method The HTTP method to use
+    # @param [String] path The path to request
+    # @param [String] body The body of the request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def request(http_method, path, body = '', headers = {})
       puts "#{http_method}: #{path} - [#{body}]" if @http_debug
       @request_client.request(http_method, path, body, headers)
     end
 
+    # @private
     # Stops sensitive client information from being displayed in logs
     def inspect
       "#<JIRA::Client:#{object_id}>"

lib/jira/http_client.rb

@@ -6,14 +6,25 @@
 require 'uri'
 
 module JIRA
+  # Client using HTTP Basic Authentication
   class HttpClient < RequestClient
+    # @private
     DEFAULT_OPTIONS = {
       username: nil,
       password: nil
     }.freeze
 
+    # @!attribute [r] options
+    #   @return [Hash] The client options
     attr_reader :options
 
+    # @param [Hash] options Options as passed from JIRA::Client constructor.
+    # @option options [String] :username The username to authenticate with
+    # @option options [String] :password The password to authenticate with
+    # @option options [Hash] :default_headers Additional headers for requests
+    # @option options [String] :proxy_uri Proxy URI
+    # @option options [String] :proxy_user Proxy user
+    # @option options [String] :proxy_password Proxy Password
     def initialize(options)
       @options = DEFAULT_OPTIONS.merge(options)
       @cookies = {}
@@ -26,6 +37,18 @@ def make_cookie_auth_request
       make_request(:post, "#{@options[:context_path]}/rest/auth/1/session", body, 'Content-Type' => 'application/json')
     end
 
+    # Makes a request to the JIRA server.
+    #
+    # Generally you should not call this method directly, but use the helper methods in JIRA::Client.
+    #
+    # File uploads are not supported with this method.  Use make_multipart_request instead.
+    #
+    # @param [Symbol] http_method The HTTP method to use
+    # @param [String] url The JIRA REST URL to call
+    # @param [String] body The request body
+    # @param [Hash] headers Additional headers to send with the request
+    # @return [Net::HTTPResponse] The response from the server
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def make_request(http_method, url, body = '', headers = {})
       # When a proxy is enabled, Net::HTTP expects that the request path omits the domain name
       path = request_path(url)
@@ -35,17 +58,30 @@ def make_request(http_method, url, body = '', headers = {})
       execute_request(request)
     end
 
+    # Makes a multipart request to the JIRA server.
+    #
+    # This is used for file uploads.
+    #
+    # Generally you should not call this method directly, but use the helper methods in JIRA::Client.
+    #
+    # @param [String] url The JIRA REST URL to call
+    # @param [Hash] body The Net::HTTP::Post::Multipart data to send with the request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def make_multipart_request(url, body, headers = {})
       path = request_path(url)
       request = Net::HTTP::Post::Multipart.new(path, body, headers)
 
       execute_request(request)
     end
 
+    # @private
     def basic_auth_http_conn
       http_conn(uri)
     end
 
+    # @private
     def http_conn(uri)
       http_conn =
         if @options[:proxy_address]
@@ -67,10 +103,14 @@ def http_conn(uri)
       http_conn
     end
 
+    # The URI of the JIRA REST API call
+    # @return [URI] The URI of the JIRA REST API call
     def uri
       URI.parse(@options[:site])
     end
 
+    # Returns true if the client is authenticated.
+    # @return [Boolean] True if the client is authenticated
     def authenticated?
       @authenticated
     end

lib/jira/oauth_client.rb

@@ -5,7 +5,16 @@
 require 'forwardable'
 
 module JIRA
+  # Client using OAuth 1.0
+  #
+  # @!attribute [rw] consumer
+  #   @return [OAuth::Consumer] The oauth consumer object
+  # @!attribute [r] options
+  #   @return [Hash] The oauth connection options
+  # @!attribute [r] access_token
+  #   @return [OAuth::AccessToken] The oauth access token
   class OauthClient < RequestClient
+    # @private
     DEFAULT_OPTIONS = {
       signature_method: 'RSA-SHA1',
       request_token_path: '/plugins/servlet/oauth/request-token',
@@ -31,11 +40,28 @@ def message
 
     def_instance_delegators :@consumer, :key, :secret, :get_request_token
 
+    # @param [Hash] options Options as passed from JIRA::Client constructor.
+    # @option options [String] :signature_method The signature method to use (defaults to 'RSA-SHA1')
+    # @option options [String] :request_token_path The path to request a token (defaults to '/plugins/servlet/oauth/request-token')
+    # @option options [String] :authorize_path The path to authorize a token (defaults to '/plugins/servlet/oauth/authorize')
+    # @option options [String] :access_token_path The path to access a token (defaults to '/plugins/servlet/oauth/access-token')
+    # @option options [String] :private_key_file The path to the private key file
+    # @option options [String] :consumer_key The OAuth 1.0 consumer key
+    # @option options [String] :consumer_secret The OAuth 1.0 consumer secret
+    # @option options [Hash] :default_headers Additional headers for requests
+    # @option options [String] :proxy_uri Proxy URI
+    # @option options [String] :proxy_user Proxy user
+    # @option options [String] :proxy_password Proxy Password
     def initialize(options)
       @options = DEFAULT_OPTIONS.merge(options)
       @consumer = init_oauth_consumer(@options)
     end
 
+    # @private
+    # Initialises the OAuth consumer object.
+    # Generally you should not call this method directly, it is called by the constructor.
+    # @param [Hash] _options The options hash
+    # @return [OAuth::Consumer] The OAuth consumer object
     def init_oauth_consumer(_options)
       @options[:request_token_path] = @options[:context_path] + @options[:request_token_path]
       @options[:authorize_path] = @options[:context_path] + @options[:authorize_path]
@@ -47,22 +73,31 @@ def init_oauth_consumer(_options)
 
     # Returns the current request token if it is set, else it creates
     # and sets a new token.
+    # @param [Hash] options
     def request_token(options = {}, ...)
       @request_token ||= get_request_token(options, ...)
     end
 
     # Sets the request token from a given token and secret.
+    # @param [String] token The request token
+    # @param [String] secret The request token secret
+    # @return [OAuth::RequestToken] The request token object
     def set_request_token(token, secret)
       @request_token = OAuth::RequestToken.new(@consumer, token, secret)
     end
 
     # Initialises and returns a new access token from the params hash
     # returned by the OAuth transaction.
+    # @param [Hash] params The params hash returned by the OAuth transaction
+    # @return [OAuth::AccessToken] The access token object
     def init_access_token(params)
       @access_token = request_token.get_access_token(params)
     end
 
     # Sets the access token from a preexisting token and secret.
+    # @param [String] token The access token
+    # @param [String] secret The access token secret
+    # @return [OAuth::AccessToken] The access token object
     def set_access_token(token, secret)
       @access_token = OAuth::AccessToken.new(@consumer, token, secret)
       @authenticated = true
@@ -71,12 +106,25 @@ def set_access_token(token, secret)
 
     # Returns the current access token. Raises an
     # JIRA::Client::UninitializedAccessTokenError exception if it is not set.
+    # @return [OAuth::AccessToken] The access token object
     def access_token
       raise UninitializedAccessTokenError unless @access_token
 
       @access_token
     end
 
+    # Makes a request to the JIRA server using the oauth gem.
+    #
+    # Generally you should not call this method directly, but use the helper methods in JIRA::Client.
+    #
+    # File uploads are not supported with this method.  Use make_multipart_request instead.
+    #
+    # @param [Symbol] http_method The HTTP method to use
+    # @param [String] url The JIRA REST URL to call
+    # @param [String] body The body of the request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def make_request(http_method, url, body = '', headers = {})
       # When using oauth_2legged we need to add an empty oauth_token parameter to every request.
       if @options[:auth_type] == :oauth_2legged
@@ -100,6 +148,17 @@ def make_request(http_method, url, body = '', headers = {})
       response
     end
 
+    # Makes a multipart request to the JIRA server using the oauth gem.
+    #
+    # This is used for file uploads.
+    #
+    # Generally you should not call this method directly, but use the helper methods in JIRA::Client.
+    #
+    # @param [String] url The JIRA REST URL to call
+    # @param [Hash] data The Net::HTTP::Post::Multipart data to send with the request
+    # @param [Hash] headers The headers to send with the request
+    # @return [Net::HTTPResponse] The response object
+    # @raise [JIRA::HTTPError] If the response is not an HTTP success code
     def make_multipart_request(url, data, headers = {})
       request = Net::HTTP::Post::Multipart.new url, data, headers
 
@@ -110,6 +169,8 @@ def make_multipart_request(url, data, headers = {})
       response
     end
 
+    # Returns true if the client is authenticated.
+    # @return [Boolean] True if the client is authenticated
     def authenticated?
       @authenticated
     end

lib/jira/request_client.rb

@@ -5,29 +5,54 @@
 require 'net/https'
 
 module JIRA
+  # Base class for request clients specific to a particular authentication method.
   class RequestClient
+    # Makes the JIRA REST API call.
+    #
     # Returns the response if the request was successful (HTTP::2xx) and
     # raises a JIRA::HTTPError if it was not successful, with the response
     # attached.
-
+    #
+    # Generally you should not call this method directly, but use derived classes.
+    #
+    # File uploads are not supported with this method.  Use request_multipart instead.
+    #
+    # @param [Array] args Arguments to pass to the request method
+    # @return [Net::HTTPResponse] The response from the server
+    # @raise [JIRA::HTTPError] if it was not successful
     def request(*args)
       response = make_request(*args)
       raise HTTPError, response unless response.is_a?(Net::HTTPSuccess)
 
       response
     end
 
+    # Makes a multipart request to the JIRA server.
+    #
+    # This is used for file uploads.
+    #
+    # Generally you should not call this method directly, but use derived classes.
+    #
+    # @param [Array] args Arguments to pass to the request method
+    # @return [Net::HTTPResponse] The response from the server
+    # @raise [JIRA::HTTPError] if it was not successful
     def request_multipart(*args)
       response = make_multipart_request(*args)
       raise HTTPError, response unless response.is_a?(Net::HTTPSuccess)
 
       response
     end
 
+    # Abstract method to make a request to the JIRA server.
+    # @abstract
+    # @param [Array] args Arguments to pass to the request method
     def make_request(*args)
       raise NotImplementedError
     end
 
+    # Abstract method to make a request to the JIRA server with a file upload.
+    # @abstract
+    # @param [Array] args Arguments to pass to the request method
     def make_multipart_request(*args)
       raise NotImplementedError
     end