jiralicious 0.2.0 → 0.2.1

data/lib/jiralicious.rb

@@ -22,15 +22,26 @@ require 'jiralicious/basic_session'
 require 'jiralicious/cookie_session'
 require 'jiralicious/configuration'
 
+##
+# The Jiralicious module standard options and methods
+#
 module Jiralicious
+  # Adds Configuration functionality
   extend Configuration
+  # Adds self functionality
   extend self
 
+  ##
+  # Processes the session information and returns the current session object
+  #
   def session
     session_type = "#{self.auth_type.to_s.capitalize}Session"
     @session ||= Jiralicious.const_get(session_type).new
   end
 
+  ##
+  # Returns the currently defined Rest API path
+  #
   def rest_path
     "#{self.uri}/rest/api/#{self.api_version}"
   end

data/lib/jiralicious/base.rb

@@ -1,13 +1,27 @@
-# To change this template, choose Tools | Templates
-# and open the template in the editor.
+# encoding: utf-8
 require "uri"
 module Jiralicious
+  ##
+  # The Base class encapsulates all of the default functionality necessary in order
+  # to properly manage the Hashie::Trash object within the Jiralicious framework.
+  #
   class Base < Hashie::Trash
+
+    ##
+    # Includes functionality from FieldParser
+    #
     include Jiralicious::Parsers::FieldParser
 
+    ##
+    # Used to identify if the class has been loaded
+    #
     attr_accessor :loaded
 
-    ### Trash Extention Methods ###
+    ##
+    # Trash Extention properties_from_hash
+    # Adds an underscore (_) before a numeric field.
+    # This ensures that numeric fields will be treated as strings.
+    #
     def properties_from_hash(hash)
       hash.inject({}) do |newhash, (k, v)|
         k = k.gsub("-", "_")
@@ -18,8 +32,11 @@ module Jiralicious
       end
     end
 
-    ### Class Methods ###
     class << self
+      ##
+      # Finds the specified key in relation to the current class. This is based on the
+      # inheritance and will create an error if called from the Base Class directly.
+      #
       def find(key, options = {})
         response = fetch({:key => key})
         if options[:reload] == true
@@ -29,20 +46,36 @@ module Jiralicious
         end
       end
 
+      ##
+      # Searches for all objects of the inheritance class. This method can create very large
+      # datasets and is not recommended for any request that could slow down either Jira or
+      # the Ruby application.
+      #
       def find_all
         response = fetch()
         new(response)
       end
 
+      ##
+      # Generates the endpoint_name based on the current inheritance class.
+      #
       def endpoint_name
         self.name.split('::').last.downcase
       end
 
+      ##
+      # Generates the parent_name based on the current inheritance class.
+      #
       def parent_name
         arr = self.name.split('::')
         arr[arr.length-2].downcase
       end
 
+      ##
+      # uses the options to build the URI options necessary to handle the request.
+      # Some options are defaulted if not explicit while others are only necessary
+      # under specific conditions.
+      #
       def fetch(options = {})
         options[:method] = :get unless [:get, :post, :put, :delete].include?(options[:method])
         options[:parent_uri] = "#{parent_name}/#{options[:parent_key]}/" unless options[:parent].nil?
@@ -59,6 +92,10 @@ module Jiralicious
         Jiralicious.session.request(options[:method], options[:url_uri], :handler => handler, :body => options[:body_uri].to_json)
       end
 
+      ##
+      # Configures the default handler. This can be overridden in
+      # the child class to provide additional error handling.
+      #
       def handler
         Proc.new do |response|
           case response.code
@@ -77,26 +114,48 @@ module Jiralicious
       alias :all :find_all
     end
 
-    ### Instance Methods ###
+    ##
+    # Generates the endpoint_name based on the current inheritance class.
+    #
     def endpoint_name
       self.class.endpoint_name
     end
 
+    ##
+    # Generates the parent_name based on the current inheritance class.
+    #
     def parent_name
       self.class.parent_name
     end
 
+    ##
+    # Searches for all objects of the inheritance class. This method can create very large
+    # datasets and is not recommended for any request that could slow down either Jira or
+    # the Ruby application.
+    #
     def all
       self.class.all
     end
 
+    ##
+    # Returns the the logical form of the loaded member. This used
+    # to determine if the object is loaded and ready for usage.
+    #
     def loaded?
-      self.loaded
+      !!self.loaded
     end
 
+    ##
+    # Default reload method is blank. For classes that implement lazy loading
+    # this method will be overridden with the necessary functionality.
+    #
     def reload
     end
 
+    ##
+    # Overrides the default method_missing check. This override is used in lazy
+    # loading to ensure that the requested field or method is truly unavailable.
+    #
     def method_missing(meth, *args, &block)
       if !loaded?
         self.loaded = true
@@ -107,6 +166,9 @@ module Jiralicious
       end
     end
 
+    ##
+    # Validates if the provided object is a numeric value
+    #
     def numeric?(object)
       true if Float(object) rescue false
     end

data/lib/jiralicious/basic_session.rb

@@ -1,5 +1,12 @@
 module Jiralicious
+  ##
+  # The BasicSesion class extends the default Session class by forcing
+  # basic_auth to be fired prior to any other action.
+  #
   class BasicSession < Session
+    ##
+    # Fires off the basic_auth with the local username and password.
+    #
     def before_request
       self.class.basic_auth(Jiralicious.username, Jiralicious.password)
     end

data/lib/jiralicious/configuration.rb

@@ -2,17 +2,25 @@
 require 'ostruct'
 module Jiralicious
   module Configuration
+    # Array of available attributes
     VALID_OPTIONS = [:username, :password, :uri, :api_version, :auth_type]
+    # Default user name set prior to login attempt
     DEFAULT_USERNAME = nil
+    # Default password set prior to login attempt
     DEFAULT_PASSWORD = nil
+    # Authentication is either :basic or :cookie (depricated)
     DEFAULT_AUTH_TYPE = :basic
+    # Default URI set prior to login attempt
     DEFAULT_URI = nil
+    # Default API Version can be set any valid version or "latest"
     DEFAULT_API_VERSION = "latest"
 
+    # Enables block configuration mode
     def configure
       yield self
     end
 
+    # Provides access to the array of attributes
     attr_accessor *VALID_OPTIONS
 
     # Reset when extended into class
@@ -20,12 +28,14 @@ module Jiralicious
       base.reset
     end
 
+    # Pass options to set the values
     def options
       VALID_OPTIONS.inject({}) do |option, key|
         option.merge!(key => send(key))
       end
     end
 
+    # Resets all attributes to default values
     def reset
       self.username = DEFAULT_USERNAME
       self.password = DEFAULT_PASSWORD
@@ -34,6 +44,18 @@ module Jiralicious
       self.auth_type = DEFAULT_AUTH_TYPE
     end
 
+    ##
+    # Loads the provided YML file.
+    #
+    # Can provide either direct or relational path to the file. It is recommended to send a direct path
+    # due to dynamic loading and/or different file locations due to different deployment methods.
+    #
+    # [Direct Path] /usr/project/somepath_to_file/jira.yml
+    #
+    # [Relational Path] Rails.root.to_s + "/config/jira.yml"
+    #
+    #                   "./config/jira.yml"
+    #
     def load_yml(yml_file)
       if File.exist?(yml_file)
         yml_cfg = OpenStruct.new(YAML.load_file(yml_file))

data/lib/jiralicious/cookie_session.rb

@@ -1,17 +1,26 @@
 # encoding: utf-8
-
 module Jiralicious
+  ##
+  # The CookieSesssion class extends the Session class with the
+  # functionality of utilizing cookies for authorization management.
+  # 
+  # Deprecated:: CookieSession is deprecated as of version 0.2.0
+  #
   class CookieSession < Session
+    # Adds attributes to the CookieSession
     attr_accessor :authenticating, :session, :login_info
 
+    # Checks to see if session is active
     def alive?
       @session && @login_info
     end
 
+    # Provides login information on every request
     def before_request
       self.login if require_login? && !@authenticating
     end
 
+    # Handles the response from the request
     def after_request(response)
       unless @authenticating
         if captcha_required(response)
@@ -26,6 +35,7 @@ module Jiralicious
       @authenticating = false
     end
 
+    # Authenticates the login
     def login
       @authenticating = true
       handler = Proc.new do |response|
@@ -54,6 +64,7 @@ module Jiralicious
 
     end
 
+    # Logs out of the API
     def logout
       handler = Proc.new do |request|
         if response.code == 204
@@ -74,6 +85,7 @@ module Jiralicious
 
     private
 
+    # Handles Captcha if necessary
     def captcha_required(response)
       response.code == 401 &&
         # Fakeweb lowercases headers automatically. :(
@@ -81,14 +93,17 @@ module Jiralicious
           response.headers["x-seraph-loginreason"] == "AUTHENTICATION_DENIED")
     end
 
+    # Throws if cookie is invalid
     def cookie_invalid(response)
       response.code == 401 && response.body =~ /cookie/i
     end
 
+    # Checks to see if login is required
     def require_login?
       !(Jiralicious.username.empty? && Jiralicious.password.empty?) && !alive?
     end
 
+    # Resets the current Session
     def clear_session
       @session = @login_info = nil
     end

data/lib/jiralicious/custom_field_option.rb

@@ -1,7 +1,14 @@
-# To change this template, choose Tools | Templates
-# and open the template in the editor.
+# encoding: utf-8
 module Jiralicious
+  ##
+  # The CustomFieldOption provides a list of available custom field options. This method is
+  # used in lazy loading and can be used to validate options prior to updating the issue.
+  #
   class CustomFieldOption < Jiralicious::Base
+
+    ##
+    # Initialization Method
+    #
     def initialize(decoded_json, default = nil, &blk)
       @loaded = false
       if decoded_json.is_a? Hash
@@ -13,10 +20,17 @@ module Jiralicious
     end
 
     class << self
+      ##
+      # Overrides the auto-generated endpoint_name from Base.
+      # This is necessary due to lower camel case naming convention.
+      #
       def endpoint_name
         "customFieldOption"
       end
 
+      ##
+      # Retrieves the options based on the ID
+      #
       def find(id, options = {})
         response = fetch({:key => id})
         response.parsed_response['id'] = id

data/lib/jiralicious/field.rb

@@ -1,8 +1,16 @@
-# To change this template, choose Tools | Templates
-# and open the template in the editor.
+# encoding: utf-8
 module Jiralicious
+  ##
+  # The Field class is used in multiple classes as a support object. This class
+  # is designed as a Object Oriented Method of viewing the Jira JSON/Hash.
+  #
   class Field < Jiralicious::Base
-
+    ##
+    # Initialization Method
+    # 
+    # Builds the dynamic Field object from either a Hash or Array. The decoded JSON object can be nested
+    # as deep as necessary but it is recommended that JSON objects are no deeper then 5 levels maximum.
+    #
     def initialize(decoded_json, default = nil, &blk)
       @loaded = false
       if decoded_json.is_a? Hash

data/lib/jiralicious/issue.rb

@@ -1,20 +1,36 @@
 # encoding: utf-8
 module Jiralicious
+  ##
+  # The Issue class rolls up all functionality of issues from jira. This class contains methods to manage
+  # Issues from Ruby via the API. Several child classes are added in order to facilitate several different
+  # aspects of managing the issues.
+  #
   class Issue < Jiralicious::Base
 
+    # Provides access to the Jira Key field
     property :jira_key, :from  => :key
+    # Provides access to the expand fields
     property :expand
+    # Provides access to the self string
     property :jira_self, :from => :self
+    # Provides access to the field list
     property :fields
+    # Provides access to transitions
     property :transitions
+    # Provides access to the Jira id
     property :id
+    # Contains the Fields Class
     attr_accessor :fields
+    # Contains the Comments Class
     attr_accessor :comments
+    # Contains the Watchers Class
     attr_accessor :watchers
+    # Contains the createmeta
     attr_accessor :createmeta
+    # Contains the editmeta
     attr_accessor :editmeta
 
-    ### Initialization ###
+    # Initialization Method
     def initialize(decoded_json = nil, default = nil, &blk)
       @loaded = false
       if (!decoded_json.nil?)
@@ -24,16 +40,22 @@ module Jiralicious
           @fields = Fields.new(self['fields']) if self['fields']
           @comments = Comment.find_by_key(self.jira_key)
           @watchers = Watchers.find_by_key(self.jira_key)
+          @transitions = Transitions.new(self.jira_key)
           @loaded = true
         end
       end
       @fields = Fields.new if @fields.nil?
       @comments = Comment.new if @comments.nil?
       @watchers = Watchers.new if @watchers.nil?
+      @transitions = Transitions.new if @transitions.nil?
       @createmeta = nil
       @editmeta = nil
     end
 
+    ##
+    # Imports all data from a decoded hash. This function is used when a blank
+    # issue is created but needs to be loaded from a JSON string at a later time.
+    #
     def load(decoded_hash, default = nil)
       decoded_hash.each do |k,v|
         self[:"#{k}"] = v
@@ -49,45 +71,77 @@ module Jiralicious
       end
     end
 
+    ##
+    # Forces the Jira Issue to reload with current or updated
+    # information. This method is used in lazy loading methods.
+    #
     def reload
       load(self.class.find(self.jira_key, {:reload => true}).parsed_response)
     end
 
-
-    ### Class Methods ###
     class << self
+      ##
+      # Adds specified assignee to the Jira Issue.
+      #
       def assignee(name, key)
         name = {"name" => name} if name.is_a? String
         fetch({:method => :put, :key => "#{key}/assignee", :body => name})
       end
 
+      ##
+      # Creates a new issue. This method is not recommended
+      # for direct access but is provided for advanced users.
+      #
       def create(issue)
         fetch({:method => :post, :body => issue})
       end
 
+      ##
+      # Removes/Deletes the Issue from the Jira Project. It is not recommended to delete issues however the
+      # functionality is provided. It is recommended to override this function to throw an error or warning
+      # to maintain data integrity in systems that do not allow deleting from a remote location.
+      #
       def remove(key, options = {})
         fetch({:method => :delete, :body_to_params => true, :key => key, :body => options})
       end
 
+      ##
+      # Updates the specified issue based on the provided HASH. It is not recommended
+      # to access this method directly but is provided for advanced users.
+      #
       def update(issue, key)
         fetch({:method => :put, :key => key, :body => issue})
       end
 
+      ##
+      # Retrieves the create meta for the Jira Project based on Issue Types.
+      # Can be used to validate or filter create requests to minimize errors.
+      #
       def createmeta(projectkeys, issuetypeids = nil)
         response = fetch({:body_to_params => true, :key => "createmeta", :body => {:expand => "projects.issuetypes.fields.", :projectKeys => projectkeys, :issuetypeIds => issuetypeids}})
         return Field.new(response.parsed_response)
       end
 
+      ##
+      # Retrieves the edit meta for the Jira Issue. Can be used
+      # to validate or filter create requests to minimize errors.
+      #
       def editmeta(key)
         response = fetch({:key => "#{key}/editmeta"})
         response.parsed_response["key"] = key
         Field.new(response.parsed_response)
       end
 
+      ##
+      # Legacy method to retrieve transitions manually.
+      #
       def get_transitions(transitions_url)
         Jiralicious.session.request(:get, transitions_url, :handler => handler)
       end
 
+      ##
+      # Legacy method to process transitions manually.
+      #
       def transition(transitions_url, data)
         Jiralicious.session.request(:post, transitions_url,
           :handler => handler,
@@ -95,16 +149,24 @@ module Jiralicious
       end
     end
 
-    ### Public Classes ###
-
+    ##
+    # Method to assign an assignee by name in a current issue.
+    #
     def set_assignee(name)
       self.class.assignee(name, self.jira_key)
     end
 
+    ##
+    # Method to remove or delete the current issue.
+    #
     def remove(options = {})
       self.class.remove(self.jira_key, options)
     end
 
+    ##
+    # Retrieves the create meta for the Jira Project based on Issue Types.
+    # Can be used to validate or filter create requests to minimize errors.
+    #
     def createmeta
       if @createmeta.nil?
         @createmeta = self.class.createmeta(self.jira_key.split("-")[0])
@@ -112,6 +174,10 @@ module Jiralicious
       @createmeta
     end
 
+    ##
+    # Retrieves the edit meta for the Jira Issue. Can be used
+    # to validate or filter create requests to minimize errors.
+    #
     def editmeta
       if @editmeta.nil?
         @editmeta = self.class.editmeta(self.jira_key)
@@ -119,6 +185,9 @@ module Jiralicious
       @editmeta
     end
 
+    ##
+    # Saves the current Issue but does not update itself.
+    #
     def save
       if loaded?
         self.class.update(@fields.format_for_update, self.jira_key)
@@ -127,7 +196,14 @@ module Jiralicious
         response = self.class.create(@fields.format_for_create)
         key = response.parsed_response['key']
       end
-      load(self.class.find(key, {:reload => true}).parsed_response)
+      return key
+    end
+
+    ##
+    # Saves the current Issue and reloads to ensure it is upto date.
+    #
+    def save!
+      load(self.class.find(save, {:reload => true}).parsed_response)
     end
   end
 end

data/lib/jiralicious/issue/comment.rb

@@ -1,19 +1,38 @@
 # encoding: utf-8
 module Jiralicious
   class Issue
+    ##
+    # The Comment class retrieves and controls the functionality
+    # of Comments associated with an Issue.
+    #
     class Comment < Jiralicious::Base
-
+      # Related Issue Key
       attr_accessor :jira_key
 
+      ##
+      # Initialization Method
+      #
       def initialize(decoded_json = nil, default = nil, &blk)
         if (decoded_json != nil)
           properties_from_hash(decoded_json)
           super(decoded_json)
           parse!(decoded_json)
+          if self.respond_to?("comments")
+            if self.comments.is_a? Array
+              a = {}
+              self.comments.each do |comment|
+                a["_#{comment['id']}"] = Comment.new(comment)
+              end
+              self.comments = a
+            end
+          end
         end
       end
 
       class << self
+        ##
+        # Retrieves the Comments based on the Issue Key
+        #
         def find_by_key(key, options = {})
           response = fetch({:parent => parent_name, :parent_key => key})
           a = new(response)
@@ -21,6 +40,9 @@ module Jiralicious
           return a
         end
 
+        ##
+        # Retrieves the Comment based on the Issue Key and Comment ID
+        #
         def find_by_key_and_id(key, id, options = {})
           response = fetch({:parent => parent_name, :parent_key => key, :key => id})
           a = new(response)
@@ -28,32 +50,58 @@ module Jiralicious
           return a
         end
 
+        ##
+        # Adds a new Comment to the Issue
+        #
         def add(comment, key)
           fetch({:method => :post, :body => comment, :parent => parent_name, :parent_key => key})
         end
 
+        ##
+        # Updates a Comment based on Issue Key and Comment ID
+        #
         def edit(comment, key, id)
           fetch({:method => :put, :key => id, :body => comment, :parent => parent_name, :parent_key => key})
         end
 
+        ##
+        # Removes/Deletes the Comment from the Jira Issue. It is not recommended  to delete comments however the functionality is provided.
+        # it is recommended to override this function to throw an error or warning
+        # to maintain data integrity in systems that do not allow deleting from a
+        # remote location.
+        #
         def remove(key, id)
           fetch({:method => :delete, :body_to_params => true, :key => id, :parent => parent_name, :parent_key => key})
 
         end
       end
 
+      ##
+      # Retrieves the Comment based on the loaded Issue and Comment ID
+      #
       def find_by_id(id, options = {})
         self.class.find_by_key_and_id(@jira_key, id)
       end
 
+      ##
+      # Adds a new Comment to the loaded Issue
+      #
       def add(comment)
         self.class.add(comment, @jira_key)
       end
 
+      ##
+      # Updates a Comment based on loaded Issue and Comment 
+      #
       def edit(comment)
         self.class.edit(comment, @jira_key, self.id)
       end
 
+      ##
+      # Removes/Deletes the Comment from the Jira Issue. It is not recommended to delete comments;
+      # However, the functionality is provided. It is recommended to override this function to throw an error or
+      # warning to maintain data integrity in systems that do not allow deleting from a remote location.
+      #
       def remove(id = self.id)
         self.class.remove(@jira_key, id)
       end

data/lib/jiralicious/issue/fields.rb

@@ -1,30 +1,52 @@
 # encoding: utf-8
 module Jiralicious
   class Issue
+    ##
+    # The Fields class provides functionality to the Issue class that allows it to easily
+    # update or create issues. The class retains the original  and the proposed information
+    # which could be used for cross validation prior to posting an update.
+    #
     class Fields
+      # The fields that will be updated or created
       attr_accessor :fields_update
+      # The current fields when a ticket was loaded
       attr_accessor :fields_current
 
+      ##
+      # Initialization Method
+      #
       def initialize(fc = nil)
         @fields_current = (fc == nil) ? Hash.new : fc
         @fields_update = Hash.new
       end
 
+      ##
+      # Returns the count of fields being updated.
+      #
       def count
         return @fields_update.count
       end
 
+      ##
+      # Returns the length of fields being updated.
+      #
       def length
         return @fields_update.length
       end
 
+      ##
+      # Adds a comment to the field list
+      #
       def add_comment(comment)
-        if !(@fields_update['comment'].type == Array)
+        if !(@fields_update['comment'].is_a? Array)
           @fields_update['comment'] = Array.new
         end
         @fields_update['comment'].push({"add" => {"body" => comment}})
       end
 
+      ##
+      # Appends the current String with the provided value
+      #
       def append_s(field, value)
         if (@fields_update[field] == nil)
           @fields_update[field] = @fields_current[field] unless @fields_current.nil?
@@ -33,46 +55,75 @@ module Jiralicious
         @fields_update[field] += " " + value.to_s
       end
 
+      ##
+      # Appends the current Array with the provided value
+      #
       def append_a(field, value)
         @fields_update[field] = @fields_current[field] if (@fields_update[field] == nil)
         @fields_update[field] = Array.new if !(@fields_update[field].is_a? Array)
         if value.is_a? String
-          @fields_update[field].push(value)
+          @fields_update[field].push(value) unless @fields_update[field].include? value
         else
-          @fields_update[field] = @fields_update[field].concat(value)
+          @fields_update[field] |= value
         end
       end
 
+      ##
+      # Appends the current Hash with the provided value
+      #
       def append_h(field, hash)
         @fields_update[field] = @fields_current[field] if (@fields_update[field] == nil)
         @fields_update[field] = Hash.new if !(@fields_update[field].is_a? Hash)
         @fields_update[field].merge!(hash)
       end
 
+      ##
+      # Sets the field key with the provided value.
+      #
       def set(field, value)
         @fields_update[field] = value
       end
 
+      ##
+      # Sets the field with a name hash.
+      # This is necessary for some objects in Jira.
+      #
       def set_name(field, value)
         @fields_update[field] = {"name" => value}
       end
 
+      ##
+      # Sets the field with a id hash.
+      # This is necessary for some objects in Jira.
+      #
       def set_id(field, value)
         @fields_update[field] = {"id" => value}
       end
-
+      ##
+      # Fills the fields_current object with the provided Hash.
+      #
       def set_current(fc)
         @fields_current = fc if fc.type == Hash
       end
 
+      ##
+      # Returns the current fields object
+      #
       def current
         return @fields_current
       end
 
+      ##
+      # Returns the updated fields object
+      #
       def updated
         return @fields_update
       end
 
+      ##
+      # Formats the fields_update object correctly
+      # for Jira to perform an update request.
+      #
       def format_for_update
         up = Hash.new
         @fields_update.each do |k, v|
@@ -85,6 +136,10 @@ module Jiralicious
         return {"update" => up}
       end
 
+      ##
+      # Formats the fields_update object correctly
+      # for Jira to perform an create request.
+      #
       def format_for_create
         return {"fields" => @fields_update}
       end

data/lib/jiralicious/issue/transitions.rb

@@ -1,31 +1,50 @@
-# To change this template, choose Tools | Templates
-# and open the template in the editor.
+# encoding: utf-8
 module Jiralicious
   class Issue
+    ##
+    # The Transitions Class provides all of the functionality to retrieve,
+    # and use a transition associated with an Issue.
+    #
     class Transitions < Jiralicious::Base
 
+      # Contains the meta data to process a Transaction
       attr_accessor :meta
 
-      def initialize(decoded_json, default = nil, &blk)
+      ##
+      # Initialization Method
+      #
+      def initialize(decoded_json = nil, default = nil, &blk)
         @loaded = false
         @meta = nil
-        if decoded_json.is_a? Hash
-          properties_from_hash(decoded_json)
-          super(decoded_json)
-          parse!(decoded_json)
-          @loaded = true
-        else
-          self.class.property :jira_key
-          self.jira_key = default
-          decoded_json.each do |list|
-            self.class.property :"id_#{list['id']}"
-            self.merge!({"id_#{list['id']}" => self.class.new(list)})
+        if decoded_json.is_a? Array
+          if decoded_json.length == 1
+            decoded_json = decoded_json[0]
+          end
+        end
+        unless decoded_json.nil?
+          if decoded_json.is_a? String
+            self.class.property :jira_key
+            self.jira_key = decoded_json
+          elsif decoded_json.is_a? Hash
+            properties_from_hash(decoded_json)
+            super(decoded_json)
+            parse!(decoded_json)
+            @loaded = true
+          else
+            self.class.property :jira_key
+            self.jira_key = default
+            decoded_json.each do |list|
+              self.class.property :"id_#{list['id']}"
+              self.merge!({"id_#{list['id']}" => self.class.new(list)})
+            end
           end
         end
       end
 
       class << self
-
+        ##
+        # Retrieves the associated Transitions based on the Issue Key
+        #
         def find(key, options = {})
           response = fetch({:parent => parent_name, :parent_key => key})
           response.parsed_response['transitions'].each do |t|
@@ -35,13 +54,21 @@ module Jiralicious
           return a
         end
 
+        ##
+        # Retrieves the Transition based on the Issue Key and Transition ID
+        #
         def find_by_key_and_id(key, id, options = {})
-          response = fetch({:key => id, :parent => parent_name, :parent_key => key})
-          response.parsed_response['jira_key'] = key
+          response = fetch({:parent => parent_name, :parent_key => key, :body => {"transitionId" => id}, :body_to_params => true })
+          response.parsed_response['transitions'].each do |t|
+            t['jira_key'] = key
+          end
           a = new(response.parsed_response['transitions'])
           return a
         end
 
+        ##
+        # Processes the Transition based on the provided options
+        #
         def go(key, id, options = {})
           transition = {"transition" => {"id" => id}}
           if options[:comment].is_a? String
@@ -59,6 +86,10 @@ module Jiralicious
           fetch({:method => :post, :parent => parent_name, :parent_key => key, :body => transition})
         end
 
+        ##
+        # Retrieves the meta data for the Transition based on the
+        # options, Issue Key and Transition ID provided.
+        #
         def meta(key, id, options = {})
           response = fetch({:method => :get, :parent => parent_name, :parent_key => key, :body_to_params => true,
               :body => {"transitionId" => id, "expand" => "transitions.fields"}})
@@ -72,14 +103,24 @@ module Jiralicious
         alias :find_all :find
       end
 
+      ##
+      # Retrieves the associated Transitions based on the Issue Key
+      #
       def all
         self.class.all(self.jira_key) if self.jira_key
       end
 
+      ##
+      # Processes the Transition based on the provided options
+      #
       def go(options = {})
         self.class.go(self.jira_key, self.id, options)
       end
 
+      ##
+      # Retrieves the meta data for the Transition based on the
+      # options, Issue Key and Transition ID provided.
+      #
       def meta
         if @meta.nil?
           l = self.class.meta(self.jira_key, self.id, {:return => true})

data/lib/jiralicious/issue/watchers.rb

@@ -1,11 +1,18 @@
-# To change this template, choose Tools | Templates
-# and open the template in the editor.
+# encoding: utf-8
 module Jiralicious
   class Issue
+    ##
+    # The Watchers class is used to manage the watchers on an issue.
+    #
     class Watchers < Jiralicious::Base
-
+      ##
+      # Holds the Issue Key
+      #
       attr_accessor :jira_key
 
+      ##
+      # Initialization Method
+      #
       def initialize(decoded_json = nil, default = nil, &blk)
         if (decoded_json != nil)
           properties_from_hash(decoded_json)
@@ -15,6 +22,9 @@ module Jiralicious
       end
 
       class << self
+        ##
+        # Finds all watchers based on the provided Issue Key
+        #
         def find_by_key(key)
           response = fetch({:parent => parent_name, :parent_key => key})
           a = new(response)
@@ -22,23 +32,38 @@ module Jiralicious
           return a
         end
 
+        ##
+        # Adds a new Watcher to the Issue
+        #
         def add(name, key)
           fetch({:method => :post, :body => name, :body_override => true, :parent => parent_name, :parent_key => key})
         end
 
+        ##
+        # Removes/Deletes a Watcher from the Issue
+        #
         def remove(name, key)
           fetch({:method => :delete, :body_to_params => true, :body => {:username => name}, :parent => parent_name, :parent_key => key})
         end
       end
 
+      ##
+      # Finds all watchers based on the provided Issue Key
+      #
       def find
         self.class.find_by_key(@jira_key)
       end
 
+      ##
+      # Adds a new Watcher to the Issue
+      #
       def add(name)
         self.class.add(name, @jira_key)
       end
 
+      ##
+      # Removes/Deletes a Watcher from the Issue
+      #
       def remove(name)
         self.class.remove(name, @jira_key)
       end

data/lib/jiralicious/parsers/field_parser.rb

@@ -1,7 +1,14 @@
 # encoding: utf-8
 module Jiralicious
   module Parsers
+    ##
+    # The FieldParser module is an extention that assists in
+    # managing hash parsing and implementation.
+    #
     module FieldParser
+      ##
+      # Parses an Array or Hash into the current class object.
+      #
       def parse!(fields)
         unless fields.is_a?(Hash)
           raise ArgumentError
@@ -32,12 +39,18 @@ module Jiralicious
 
       private
 
+      ##
+      # Normalizes key names
+      #
       def normalize(name)
         name.gsub(/(\w+)([A-Z].*)/, '\1_\2').
           gsub(/\W/, "_").
           downcase
       end
 
+      ##
+      # Converts Array or Hash to a Mash object
+      #
       def mashify(data)
         if data.is_a?(Array)
           data.map { |d| mashify(d) }

data/lib/jiralicious/project.rb

@@ -1,11 +1,14 @@
-# To change this template, choose Tools | Templates
-# and open the template in the editor.
+# encoding: utf-8
 module Jiralicious
+  ##
+  # The Project class rolls up the basic functionality for
+  # managing Projects within Jira through the Rest API.
+  #
   class Project < Jiralicious::Base
-    
-    attr_accessor :issues
 
-    ### Initialization ###
+    ##
+    # Initialization Method
+    #
     def initialize(decoded_json, default = nil, &blk)
       @loaded = false
       if decoded_json.is_a? Hash
@@ -22,6 +25,11 @@ module Jiralicious
     end
 
     class << self
+      ##
+      # Returns a list of issues within the project. The issue list is limited
+      # to only return the issue ID and KEY values to minimize the amount of
+      # data being returned This is used in lazy loading methodology.
+      #
       def issue_list(key)
         response = Jiralicious.search("project=#{key}", {:fields => ["id", "key"]})
         i_out = Issue.new
@@ -34,6 +42,11 @@ module Jiralicious
       end
     end
 
+    ##
+    # Issues loads the issue list into the current Project.
+    # It also acts as a reference for lazy loading of issues.
+    #
+    attr_accessor :issues
     def issues
       if @issues == nil
         @issues = self.class.issue_list(self.key)

data/lib/jiralicious/search.rb

@@ -1,5 +1,9 @@
 # encoding: utf-8
 module Jiralicious
+  ##
+  # Provides the interface to access the JQL search functionality.
+  # Uses the same syntax as Rest interface for JQL criteria.
+  #
   def search(jql, options = {})
     options[:start_at] ||= 0
     options[:max_results] ||= 50

data/lib/jiralicious/search_result.rb

@@ -1,19 +1,36 @@
 module Jiralicious
+  ##
+  # The SearchResult class organizes the response from the Jira API
+  # In a way that is easily parsable into Issues.
+  #
   class SearchResult
+    # Attributes available for usage regarding the current position in the list
     attr_reader :offset, :num_results
 
+    ##
+    # Initialization Method
+    #
+    # Parses the hash into attributes.
+    #
     def initialize(search_data)
       @issues      = search_data["issues"]
       @offset      = search_data["startAt"]
       @num_results = search_data["total"]
     end
 
+  ##
+  # Loads the different issues through the map. This is not recommended for large objects
+  # as it can be troublesome to load multiple Issues to locate the desired one. If the user needs to have all of the information available on each issue this method works perfectly for that process.
+  #
     def issues
       @issues.map do |issue|
         Jiralicious::Issue.find(issue["key"])
       end
     end
 
+  ##
+  # Returns the Issues attribute without loading the extra information. Ideal for a quick scan of the Hash prior to selecting the correct Issue. This method is also used in the lazy loading methodology.
+  #
     def issues_raw
       @issues
     end

data/lib/jiralicious/session.rb

@@ -2,12 +2,21 @@
 require 'jiralicious/configuration'
 
 module Jiralicious
+  ##
+  # The Session class handles the interactions with the Jira Rest API
+  # Through the HTTParty gem.
+  #
   class Session
     include HTTParty
 
+    # Sets the default format to JSON for send and return
     format        :json
+    # Sets the default headers to application/json for send and return
     headers       'Content-Type' => 'application/json'
 
+    ##
+    # Main access method to request data from the Jira API
+    #
     def request(method, *options)
       if options.last.is_a?(Hash) && options.last[:handler]
         response_handler = options.last.delete(:handler)
@@ -25,6 +34,10 @@ module Jiralicious
 
     private
 
+    ##
+    # Configures the default handler. This can be overridden in
+    # the child class to provide additional error handling.
+    #
     def handler
       Proc.new do |response|
         case response

data/lib/jiralicious/version.rb

@@ -1,3 +1,4 @@
 module Jiralicious
-  VERSION = "0.2.0"
+  # Current Jiralicious Version
+  VERSION = "0.2.1"
 end

data/spec/comment_spec.rb

@@ -33,14 +33,14 @@ describe Jiralicious, "search" do
       :status => "204")
   end
 
-  it "finds by isusse key" do
+  it "finds by issue key" do
     comments = Jiralicious::Issue::Comment.find_by_key("EX-1")
     comments.should be_instance_of(Jiralicious::Issue::Comment)
     comments.comments.count.should == 1
-    comments.comments[0]['id'].should == "10000"
+    comments.comments.first[1].id.should == "10000"
   end
 
-  it "finds by isusse key and comment id" do
+  it "finds by issue key and comment id" do
     comments = Jiralicious::Issue::Comment.find_by_key_and_id("EX-1", "10000")
     comments.should be_instance_of(Jiralicious::Issue::Comment)
     comments.id.should == "10000"

data/spec/issue_spec.rb

@@ -134,7 +134,7 @@ describe Jiralicious::Issue, "Managing Issues" do
     issue.fields.set("labels", ["new_label_p"])
     issue.fields.set("environment", "example of environment")
     issue.fields.set("description", "example of the description extending")
-    issue.save
+    issue.save!
     issue.jira_key.should == 'EX-2'
     issue.comments.comments.count.should == 0
     issue.watchers.watchers.count.should == 1
@@ -142,7 +142,7 @@ describe Jiralicious::Issue, "Managing Issues" do
 
   it "updates a new issue" do
     issue = Jiralicious::Issue.find("EX-3")
-    issue.fields.append_a("labels", "test_label")
+    issue.fields.append_a("labels", ["test_label"])
     issue.fields.append_s("description", " updated description ")
     issue.save
     issue.jira_key.should == 'EX-3'

data/spec/watchers_spec.rb

@@ -24,7 +24,7 @@ describe Jiralicious, "search" do
       :status => "204")
   end
 
-  it "finds by isusse key" do
+  it "finds by issue key" do
     watchers = Jiralicious::Issue::Watchers.find_by_key("EX-1")
     watchers.should be_instance_of(Jiralicious::Issue::Watchers)
     watchers.watchers.count.should == 1

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jiralicious
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-29 00:00:00.000000000 Z
+date: 2013-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: crack