client and issue documentation

lib/jira/client.rb

@@ -112,6 +112,23 @@ class Client
       default_headers: {}
     }.freeze
 
+    # Creates a new JIRA::Client instance
+    # @param [Hash] options The configuration options for the client
+    # @option options [Symbol] :auth_type The authentication type to use, :basic, :oauth, :oauth_2legged, or :cookie.
+    # @option options [String] :site The base URL for the JIRA instance
+    # @option options [Boolean] :use_ssl Whether to use HTTPS for requests
+    # @option options [Integer] :ssl_verify_mode The SSL verification mode OpenSSL::SSL::VERIFY_PEER or OpenSSL::SSL::VERIFY_NONE
+    # @option options [Hash] :default_headers Additional headers to send with each request
+    # @option options [String] :cert_path The path to the SSL certificate file to verify the server with
+    # @option options [String] :use_client_cert Whether to use a client certificate for authentication
+    # @option options [String] :ssl_client_cert The client certificate to use
+    # @option options [String] :ssl_client_key The client certificate key to use
+    # @option options [String] :proxy_address The address of the proxy server to use
+    # @option options [Integer] :proxy_port The port of the proxy server to use
+    # @option options [String] :proxy_username The username for the proxy server
+    # @option options [String] :proxy_password The password for the proxy server
+    # @return [JIRA::Client] The client instance
+    # @raise [ArgumentError] If an unknown option is given
     def initialize(options = {})
       options = DEFAULT_OPTIONS.merge(options)
       @options = options

lib/jira/http_client.rb

@@ -7,6 +7,27 @@
 
 module JIRA
   # Client using HTTP Basic Authentication
+  # @example Basic authentication
+  #   options = {
+  #     auth_type:        :basic,
+  #     site:             "https://jira.example.com",
+  #     use_ssl:          true,
+  #     ssl_verify_mode:  OpenSSL::SSL::VERIFY_PEER,
+  #     cert_path:        '/usr/local/etc/trusted-certificates.pem',
+  #     username:         'jamie',
+  #     password:         'password'
+  #   }
+  #   client = JIRA::Client.new(options)
+  # @example Bearer token authentication
+  #   options = {
+  #     auth_type:        :basic,
+  #     site:             "https://jira.example.com",
+  #     default_headers:  { 'authorization' => "Bearer #{bearer_token_str}" },
+  #     use_ssl:          true,
+  #     ssl_verify_mode:  OpenSSL::SSL::VERIFY_PEER
+  #     cert_path:        '/usr/local/etc/trusted-certificates.pem',
+  #   }
+  #   client = JIRA::Client.new(options)
   class HttpClient < RequestClient
     # @private
     DEFAULT_OPTIONS = {
@@ -18,6 +39,8 @@ class HttpClient < RequestClient
     #   @return [Hash] The client options
     attr_reader :options
 
+    # Generally not used directly, but through JIRA::Client.
+    # See JIRA::Client for documentation.
     # @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

lib/jira/oauth_client.rb

@@ -40,6 +40,7 @@ def message
 
     def_instance_delegators :@consumer, :key, :secret, :get_request_token
 
+    # Generally not used directly, but through JIRA::Client.
     # @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')

lib/jira/resource/issue.rb

@@ -8,6 +8,35 @@ module Resource
     class IssueFactory < JIRA::BaseFactory # :nodoc:
     end
 
+    # This class provides the Issue object <-> REST mapping for JIRA::Resource::Issue derived class,
+    # i.e. the Create, Retrieve, Update, Delete lifecycle methods.
+    #
+    # == Lifecycle methods
+    #
+    # === Retrieving all issues
+    #
+    #   client.Issue.all
+    #
+    # === Retrieving a single issue
+    #
+    #   options = { expand: 'editmeta' }
+    #   issue = client.Issue.find("SUP-3000", options)
+    #
+    # === Creating a new issue
+    #
+    #   issue = client.Issue.build(fields: { summary: 'New issue', project: { key: 'SUP' }, issuetype: { name: 'Bug' } })
+    #   issue.save
+    #
+    # === Updating an issue
+    #
+    #   issue = client.Issue.find("SUP-3000")
+    #   issue.save(fields: { summary: 'Updated issue' })
+    #
+    # === Deleting an issue
+    #
+    #   issue = client.Issue.find("SUP-3000")
+    #   issue.delete
+    #
     class Issue < JIRA::Base
       has_one :reporter, class: JIRA::Resource::User, nested_under: 'fields'
       has_one :assignee, class: JIRA::Resource::User, nested_under: 'fields'
@@ -29,6 +58,9 @@ class Issue < JIRA::Base
       has_many :remotelink, class: JIRA::Resource::Remotelink
       has_many :watchers, attribute_key: 'watches', nested_under: %w[fields watches]
 
+      # Get collection of issues.
+      # @param client [JIRA::Client]
+      # @return [Array<JIRA::Resource::Issue>]
       def self.all(client)
         start_at = 0
         max_results = 1000
@@ -48,8 +80,7 @@ def self.all(client)
         result
       end
 
-      def self.jql(client, jql, options = { fields: nil, start_at: nil, max_results: nil, expand: nil,
-validate_query: true })
+      def self.jql(client, jql, options = { fields: nil, start_at: nil, max_results: nil, expand: nil, validate_query: true })
         url = client.options[:rest_base_path] + "/search?jql=#{CGI.escape(jql)}"
 
         if options[:fields]
@@ -78,6 +109,13 @@ def self.jql(client, jql, options = { fields: nil, start_at: nil, max_results: n
       # Fetches the attributes for the specified resource from JIRA unless
       # the resource is already expanded and the optional force reload flag
       # is not set
+      # @param [Boolean] reload
+      # @param [Hash] query_params
+      # @option query_params [String] :fields
+      # @option query_params [String] :expand
+      # @option query_params [Integer] :startAt
+      # @option query_params [Integer] :maxResults
+      # @return [void]
       def fetch(reload = false, query_params = {})
         return if expanded? && !reload
 
@@ -101,6 +139,7 @@ def editmeta
         json['fields']
       end
 
+      # @private
       def respond_to?(method_name, _include_all = false)
         if attrs.key?('fields') && [method_name.to_s, client.Field.name_to_id(method_name)].any? do |k|
              attrs['fields'].key?(k)
@@ -111,6 +150,7 @@ def respond_to?(method_name, _include_all = false)
         end
       end
 
+      # @private
       def method_missing(method_name, *args, &)
         if attrs.key?('fields')
           if attrs['fields'].key?(method_name.to_s)
@@ -127,6 +167,26 @@ def method_missing(method_name, *args, &)
           super
         end
       end
+
+      # @!method self.find(client, key, options = {})
+      #   Gets/fetches an issue from JIRA.
+      #
+      #   Note: attachments are not fetched by default.
+      #
+      #   @param [JIRA::Client] client
+      #   @param [String] key the key of the issue to find
+      #   @param [Hash] options the options to find the issue with
+      #   @option options [String] :fields the fields to include in the response
+      #   @return [JIRA::Resource::Issue] the found issue
+      #   @example Find an issue
+      #   JIRA::Resource::Issue.find(client, "SUP-3000", { fields: %w[summary description attachment created ] } )
+      #
+      # @!method self.build(attrs = {})
+      #   Constructs a new issue object.
+      #   @param [Hash] attrs the attributes to initialize the issue with
+      #   @return [JIRA::Resource::Issue] the new issue
+      #
+      # .
     end
   end
 end

lib/jira/resource/issuelink.rb

@@ -5,9 +5,10 @@ module Resource
     class IssuelinkFactory < JIRA::BaseFactory # :nodoc:
     end
 
-    # Because of circular dependency Issue->IssueLink->Issue
-    # we have to declare JIRA::Resource::Issue class.
-    class Issue < JIRA::Base; end
+    class Issue < JIRA::Base
+      # Because of circular dependency Issue->IssueLink->Issue
+      # we have to declare JIRA::Resource::Issue class.
+    end
 
     class Issuelink < JIRA::Base
       has_one :type, class: JIRA::Resource::Issuelinktype