jiralicious 0.3.0 → 0.4.0

data/lib/jiralicious/issue.rb

@@ -1,9 +1,10 @@
 # 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.
+  # 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
 
@@ -30,8 +31,15 @@ module Jiralicious
     # Contains the editmeta
     attr_accessor :editmeta
 
+    ##
     # Initialization Method
-    def initialize(decoded_json = nil, default = nil, &blk)
+    #
+    # [Arguments]
+    # :decoded_json    (optional)    rubyized json object
+    #
+    # :default         (optional)    set to not load subclasses
+    #
+    def initialize(decoded_json = nil, default = nil)
       @loaded = false
       if (!decoded_json.nil?)
         super(decoded_json)
@@ -53,8 +61,14 @@ module Jiralicious
     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.
+    # 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.
+    #
+    # [Arguments]
+    # :decoded_hash    (optional)    rubyized json object
+    #
+    # :default         (optional)    set to not load subclasses
     #
     def load(decoded_hash, default = nil)
       decoded_hash.each do |k,v|
@@ -83,6 +97,11 @@ module Jiralicious
       ##
       # Adds specified assignee to the Jira Issue.
       #
+      # [Arguments]
+      # :name    (required)    name of assignee
+      #
+      # :key     (required)    issue key
+      #
       def assignee(name, key)
         name = {"name" => name} if name.is_a? String
         fetch({:method => :put, :key => "#{key}/assignee", :body => name})
@@ -92,22 +111,39 @@ module Jiralicious
       # Creates a new issue. This method is not recommended
       # for direct access but is provided for advanced users.
       #
+      # [Arguments]
+      # :issue    (required)    issue fields in hash format
+      #
       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.
+      # 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.
+      #
+      # [Arguments]
+      # :key               (required)    issue key
+      #
+      # :deleteSubtasks    (optional)    boolean flag to remove subtasks
+      #
       #
       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.
+      # Updates the specified issue based on the provided HASH. It
+      # is not recommended to access this method directly but is
+      # provided for advanced users.
+      #
+      # [Arguments]
+      # :issue    (required)    hash of fields to update
+      #
+      # :key      (required)    issue key to update
       #
       def update(issue, key)
         fetch({:method => :put, :key => key, :body => issue})
@@ -117,6 +153,11 @@ module Jiralicious
       # Retrieves the create meta for the Jira Project based on Issue Types.
       # Can be used to validate or filter create requests to minimize errors.
       #
+      # [Arguments]
+      # :projectkeys    (required)    project key to generate create meta
+      #
+      # :issuetypeids   (opitonal)    list of issues types for create meta
+      #
       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)
@@ -126,6 +167,9 @@ module Jiralicious
       # Retrieves the edit meta for the Jira Issue. Can be used
       # to validate or filter create requests to minimize errors.
       #
+      # [Arguments]
+      # :key    (required)    issue key
+      #
       def editmeta(key)
         response = fetch({:key => "#{key}/editmeta"})
         response.parsed_response["key"] = key
@@ -135,6 +179,9 @@ module Jiralicious
       ##
       # Legacy method to retrieve transitions manually.
       #
+      # [Arguments]
+      # :transitions_url    (required)    full URL
+      #
       def get_transitions(transitions_url)
         Jiralicious.session.request(:get, transitions_url, :handler => handler)
       end
@@ -142,6 +189,11 @@ module Jiralicious
       ##
       # Legacy method to process transitions manually.
       #
+      # [Arguments]
+      # :transitions_url    (required)    full URL and params to be processed
+      #
+      # :data               (required)    data for the transition
+      #
       def transition(transitions_url, data)
         Jiralicious.session.request(:post, transitions_url,
           :handler => handler,
@@ -152,6 +204,9 @@ module Jiralicious
     ##
     # Method to assign an assignee by name in a current issue.
     #
+    # [Arguments]
+    # :name    (required)    name of assignee
+    #
     def set_assignee(name)
       self.class.assignee(name, self.jira_key)
     end
@@ -159,6 +214,9 @@ module Jiralicious
     ##
     # Method to remove or delete the current issue.
     #
+    # [Arguments]
+    # :options    (optional)    passed on
+    #
     def remove(options = {})
       self.class.remove(self.jira_key, options)
     end

data/lib/jiralicious/issue/comment.rb

@@ -12,7 +12,10 @@ module Jiralicious
       ##
       # Initialization Method
       #
-      def initialize(decoded_json = nil, default = nil, &blk)
+      # [Arguments]
+      # :decoded_json    (optional)    rubyized json object
+      #
+      def initialize(decoded_json = nil)
         if (decoded_json != nil)
           properties_from_hash(decoded_json)
           super(decoded_json)
@@ -33,7 +36,10 @@ module Jiralicious
         ##
         # Retrieves the Comments based on the Issue Key
         #
-        def find_by_key(key, options = {})
+        # [Arguments]
+        # :key    (required)    issue key
+        #
+        def find_by_key(key)
           response = fetch({:parent => parent_name, :parent_key => key})
           a = new(response)
           a.jira_key = key
@@ -43,7 +49,12 @@ module Jiralicious
         ##
         # Retrieves the Comment based on the Issue Key and Comment ID
         #
-        def find_by_key_and_id(key, id, options = {})
+        # [Arguments]
+        # :key    (required)    issue key
+        #
+        # :id     (required)    comment id
+        #
+        def find_by_key_and_id(key, id)
           response = fetch({:parent => parent_name, :parent_key => key, :key => id})
           a = new(response)
           a.jira_key = key
@@ -53,6 +64,11 @@ module Jiralicious
         ##
         # Adds a new Comment to the Issue
         #
+        # [Arguments]
+        # :comment    (required)    comment to post
+        #
+        # :key        (required)    issue key
+        #
         def add(comment, key)
           fetch({:method => :post, :body => comment, :parent => parent_name, :parent_key => key})
         end
@@ -60,32 +76,50 @@ module Jiralicious
         ##
         # Updates a Comment based on Issue Key and Comment ID
         #
+        # [Arguments]
+        # :comment    (required)    comment to post
+        #
+        # :key        (required)    issue key
+        #
+        # :id         (required)    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.
+        # 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.
+        #
+        # [Arguments]
+        # :key        (required)    issue key
+        #
+        # :id         (required)    comment id
         #
         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 = {})
+      # [Arguments]
+      # :id         (required)    comment id
+      #
+      def find_by_id(id)
         self.class.find_by_key_and_id(@jira_key, id)
       end
 
       ##
       # Adds a new Comment to the loaded Issue
       #
+      # [Arguments]
+      # :comment    (required)    comment text
+      #
       def add(comment)
         self.class.add(comment, @jira_key)
       end
@@ -93,14 +127,22 @@ module Jiralicious
       ##
       # Updates a Comment based on loaded Issue and Comment 
       #
+      # [Arguments]
+      # :comment    (required)    comment text
+      #
       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.
+      # 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.
+      #
+      # [Arguments]
+      # :id    (optional)    comment id
       #
       def remove(id = self.id)
         self.class.remove(@jira_key, id)

data/lib/jiralicious/issue/fields.rb

@@ -2,9 +2,11 @@
 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.
+    # 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
@@ -15,6 +17,9 @@ module Jiralicious
       ##
       # Initialization Method
       #
+      # [Arguments]
+      # :fc    (optional) fields to load
+      #
       def initialize(fc = nil)
         @fields_current = (fc == nil) ? Hash.new : fc
         @fields_update = Hash.new
@@ -37,6 +42,9 @@ module Jiralicious
       ##
       # Adds a comment to the field list
       #
+      # [Arguments]
+      # :comment   (required)    comment text
+      #
       def add_comment(comment)
         if !(@fields_update['comment'].is_a? Array)
           @fields_update['comment'] = Array.new
@@ -47,6 +55,11 @@ module Jiralicious
       ##
       # Appends the current String with the provided value
       #
+      # [Arguments]
+      # :field   (required)    field to update
+      #
+      # :value   (required)    value text
+      #
       def append_s(field, value)
         if (@fields_update[field] == nil)
           @fields_update[field] = @fields_current[field] unless @fields_current.nil?
@@ -58,6 +71,11 @@ module Jiralicious
       ##
       # Appends the current Array with the provided value
       #
+      # [Arguments]
+      # :field   (required)    field to update
+      #
+      # :value   (required)    value array
+      #
       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)
@@ -71,6 +89,11 @@ module Jiralicious
       ##
       # Appends the current Hash with the provided value
       #
+      # [Arguments]
+      # :field   (required)    field to update
+      #
+      # :value   (required)    value hash
+      #
       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)
@@ -80,6 +103,11 @@ module Jiralicious
       ##
       # Sets the field key with the provided value.
       #
+      # [Arguments]
+      # :field   (required)    field to update
+      #
+      # :value   (required)    value to add
+      #
       def set(field, value)
         @fields_update[field] = value
       end
@@ -88,6 +116,11 @@ module Jiralicious
       # Sets the field with a name hash.
       # This is necessary for some objects in Jira.
       #
+      # [Arguments]
+      # :field   (required)    field to update
+      #
+      # :value   (required)    value text
+      #
       def set_name(field, value)
         @fields_update[field] = {"name" => value}
       end
@@ -96,12 +129,20 @@ module Jiralicious
       # Sets the field with a id hash.
       # This is necessary for some objects in Jira.
       #
+      # [Arguments]
+      # :field   (required)    field to update
+      #
+      # :value   (required)    value text/int
+      #
       def set_id(field, value)
         @fields_update[field] = {"id" => value}
       end
       ##
       # Fills the fields_current object with the provided Hash.
       #
+      # [Arguments]
+      # :fc    (optional) fields to load
+      #
       def set_current(fc)
         @fields_current = fc if fc.type == Hash
       end

data/lib/jiralicious/issue/transitions.rb

@@ -2,8 +2,9 @@
 module Jiralicious
   class Issue
     ##
-    # The Transitions Class provides all of the functionality to retrieve,
-    # and use a transition associated with an Issue.
+    # The Transitions Class provides all of the
+    # functionality to retrieve, and use a transition
+    # associated with an Issue.
     #
     class Transitions < Jiralicious::Base
 
@@ -13,7 +14,12 @@ module Jiralicious
       ##
       # Initialization Method
       #
-      def initialize(decoded_json = nil, default = nil, &blk)
+      # [Arguments]
+      # :decoded_json    (optional)    rubyized json object
+      #
+      # :default         (optional)    default issue key
+      #
+      def initialize(decoded_json = nil, default = nil)
         @loaded = false
         @meta = nil
         if decoded_json.is_a? Array
@@ -45,30 +51,46 @@ module Jiralicious
         ##
         # Retrieves the associated Transitions based on the Issue Key
         #
-        def find(key, options = {})
+        # [Arguments]
+        # :key    (required)    issue key
+        #
+        def find(key)
           response = fetch({:parent => parent_name, :parent_key => key})
           response.parsed_response['transitions'].each do |t|
             t['jira_key'] = key
           end
-          a = new(response.parsed_response['transitions'], key)
-          return a
+          return new(response.parsed_response['transitions'], key)
         end
 
         ##
         # Retrieves the Transition based on the Issue Key and Transition ID
         #
-        def find_by_key_and_id(key, id, options = {})
+        # [Arguments]
+        # :key    (required)    issue key
+        #
+        # :id     (required)    transition id
+        #
+        def find_by_key_and_id(key, id)
           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
+          return new(response.parsed_response['transitions'])
         end
 
         ##
         # Processes the Transition based on the provided options
         #
+        # [Arguments]
+        # :key      (required)    issue key
+        #
+        # :id       (required)    transaction id
+        #
+        # :comment  (optional)    comment to be added with transition
+        #
+        # :fields   (mixed)       the fields that are required or optional
+        #                             based on the individual transition
+        #
         def go(key, id, options = {})
           transition = {"transition" => {"id" => id}}
           if options[:comment].is_a? String
@@ -90,14 +112,20 @@ module Jiralicious
         # Retrieves the meta data for the Transition based on the
         # options, Issue Key and Transition ID provided.
         #
+        # [Arguments]
+        # :key      (required)    issue key
+        #
+        # :id       (required)    transaction id
+        #
+        # :return   (optional)    boolean flag to determine if an object or hash is returned
+        #
         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"}})
           response.parsed_response['transitions'].each do |t|
             t['jira_key'] = key
           end
-          a = (options[:return].nil?) ?  new(response.parsed_response['transitions'], key) : response
-          return a
+          return (options[:return].nil?) ?  new(response.parsed_response['transitions'], key) : response
         end
 
         alias :find_all :find
@@ -113,6 +141,9 @@ module Jiralicious
       ##
       # Processes the Transition based on the provided options
       #
+      # [Arguments]
+      # :options are passed on to the 'class.go' function
+      #
       def go(options = {})
         self.class.go(self.jira_key, self.id, options)
       end