jiraSOAP 0.7.1 → 0.8.0

data/lib/jiraSOAP/entities/issue_property.rb

@@ -1,9 +1,12 @@
+##
 # @abstract A common base for most issue properties; core issue properties
-#  have an icon to go with them to help identify properties of issues more
-#  quickly.
+#           also have an icon.
 class JIRA::IssueProperty < JIRA::DescribedEntity
-  add_attributes(
-    # NSURL on MacRuby and a URI::HTTP object on CRuby
-    ['icon', :icon, :to_url]
-  )
+
+  ##
+  # NSURL on MacRuby, URI::HTTP on CRuby
+  #
+  # @return [URI::HTTP,NSURL]
+  add_attribute :icon, 'icon', :to_url
+
 end

data/lib/jiraSOAP/entities/issue_security_scheme.rb

@@ -1,4 +1,4 @@
+##
 # Basic metadata about a project's issue security scheme.
 class JIRA::IssueSecurityScheme < JIRA::Scheme
-  add_attributes
 end

data/lib/jiraSOAP/entities/issue_type.rb

@@ -1,7 +1,12 @@
+##
 # Contains all the metadata for an issue type.
 class JIRA::IssueType < JIRA::IssueProperty
-  add_attributes(
-    # True if the issue type is also a subtask.
-    ['subTask', :subtask, :to_boolean]
-  )
+
+  ##
+  # True if the issue type is also a subtask
+  #
+  # @return [Boolean]
+  add_attribute :subtask, 'subTask', :to_boolean
+  alias_method :sub_task, :subtask
+
 end

data/lib/jiraSOAP/entities/named_entity.rb

@@ -1,7 +1,11 @@
+##
 # @abstract Most dynamic entities also have a name
 class JIRA::NamedEntity < JIRA::DynamicEntity
-  add_attributes(
-    # A plain language name.
-    ['name', :name, :to_s]
-  )
+
+  ##
+  # A plain language name
+  #
+  # @return [String]
+  add_attribute :name, 'name', :content
+
 end

data/lib/jiraSOAP/entities/notification_scheme.rb

@@ -1,4 +1,4 @@
+##
 # Basic metadata about a project's notification scheme.
 class JIRA::NotificationScheme < JIRA::Scheme
-  add_attributes
 end

data/lib/jiraSOAP/entities/permission.rb

@@ -1,9 +1,17 @@
+##
 # A permission id and the username that it is tied to.
 class JIRA::Permission < JIRA::Entity
-  add_attributes(
-    # The permission type
-    ['name',       :name,       :to_s],
-    # A unique id number
-    ['permission', :permission, :to_i]
-  )
+
+  ##
+  # The permission type
+  #
+  # @return [String]
+  add_attribute :name, 'name', :content
+
+  ##
+  # A unique id number
+  #
+  # @return [Number]
+  add_attribute :permission, 'permission', :to_i
+
 end

data/lib/jiraSOAP/entities/permission_mapping.rb

@@ -1,7 +1,11 @@
-# @todo make sure the xml names are correct (check the XML dump)
+##
+# @todo Make sure the xml names are correct (check the XML dump)
 class JIRA::PermissionMapping < JIRA::Entity
-  add_attributes(
-    ['permission', :permission, :to_object,  JIRA::Permission],
-    ['entities',   :users,      :to_objects, JIRA::UserName]
-  )
+
+  # @return [Array<JIRA::Permission>]
+  add_attribute :permission, 'permission', [:children_as_object,  JIRA::Permission]
+
+  # @return [Array<JIRA::UserName>]
+  add_attribute :users, 'entities', [:children_as_objects, JIRA::UserName]
+
 end

data/lib/jiraSOAP/entities/permission_scheme.rb

@@ -1,7 +1,10 @@
-# @todo complete this class
+##
+# @todo Complete this class
+#
 # Includes a mapping of project specific permission settings.
 class JIRA::PermissionScheme < JIRA::Scheme
-  add_attributes(
-    ['permissionMappings', :permission_mappings, :to_objects, JIRA::PermissionMapping]
-  )
+
+  # @return [Array<JIRA::PermissionMapping>]
+  add_attribute :permission_mappings, 'permissionMappings', [:children_as_objects, JIRA::PermissionMapping]
+
 end

data/lib/jiraSOAP/entities/priority.rb

@@ -1,10 +1,13 @@
+##
 # Contains all the metadata for a priority level.
 class JIRA::Priority < JIRA::IssueProperty
-  add_attributes(
-    # the RGB components as a triple
-    ['color', :color, :to_hex_string]
-  )
 
+  ##
+  # The RGB components as a triple
+  #
+  # @return [Array(String,String,String)]
+  add_attribute :color, 'color', :to_colour_triple
   alias_method :colour, :color
   alias_method :colour=, :color=
+
 end

data/lib/jiraSOAP/entities/project.rb

@@ -1,20 +1,35 @@
+##
 # Contains the data and metadata about a project and its configuration.
 class JIRA::Project < JIRA::DescribedEntity
-  add_attributes(
-    ['key',                 :key,                   :to_s],
-    ['lead',                :lead_username,         :to_s],
-    ['issueSecurityScheme', :issue_security_scheme, :to_object, JIRA::IssueSecurityScheme],
-    ['notificationScheme',  :notification_scheme,   :to_object, JIRA::NotificationScheme],
-    ['permissionScheme',    :permission_scheme,     :to_object, JIRA::PermissionScheme],
-    ['url',                 :jira_url,              :to_url],
-    ['projectUrl',          :project_url,           :to_url]
-  )
-
-  # @todo make this method shorter
-  # @todo encode the schemes
+
+  # @return [String]
+  add_attribute :key, 'key', :content
+
+  # @return [String]
+  add_attribute :lead_username, 'lead', :content
+
+  # @return [String]
+  add_attribute :issue_security_scheme, 'issueSecurityScheme', [:children_as_object, JIRA::IssueSecurityScheme]
+
+  # @return [String]
+  add_attribute :notification_scheme, 'notificationScheme', [:children_as_object, JIRA::NotificationScheme]
+
+  # @return [String]
+  add_attribute :permission_scheme, 'permissionScheme', [:children_as_object, JIRA::PermissionScheme]
+
+  # @return [NSURL,URI::HTTP]
+  add_attribute :jira_url, 'url', :to_url
+
+  # @return [NSURL,URI::HTTP]
+  add_attribute :project_url, 'projectUrl', :to_url
+
+
+  ##
+  # @todo Encode the schemes
+  #
   # @param [Handsoap::XmlMason::Node] msg
   # @return [Handsoap::XmlMason::Node]
-  def soapify_for(msg)
+  def soapify_for msg
     msg.add 'id', @id
     msg.add 'name', @name
     msg.add 'key', @key
@@ -23,4 +38,5 @@ class JIRA::Project < JIRA::DescribedEntity
     msg.add 'lead', @lead_username
     msg.add 'description', @description
   end
+
 end

data/lib/jiraSOAP/entities/project_role.rb

@@ -1,6 +1,6 @@
-# Only a name, description and id.
+##
+# Only a name, description, and id.
 class JIRA::ProjectRole < JIRA::DescribedEntity
-  add_attributes
 
   # @param [Handsoap::XmlMason::Node] msg the node where to add self
   def soapify_for msg
@@ -8,4 +8,5 @@ class JIRA::ProjectRole < JIRA::DescribedEntity
     msg.add 'name', @name
     msg.add 'description', @description
   end
+
 end

data/lib/jiraSOAP/entities/resolution.rb

@@ -1,4 +1,4 @@
+##
 # Contains all the metadata for a resolution.
 class JIRA::Resolution < JIRA::IssueProperty
-  add_attributes
 end

data/lib/jiraSOAP/entities/scheme.rb

@@ -1,9 +1,13 @@
+##
 # @abstract
+#
 # Schemes used by the server.
 class JIRA::Scheme < JIRA::DescribedEntity
-  add_attributes
 
+  ##
   # Child classes need to be careful when encoding the scheme type to XML.
+  #
   # @return [Class]
   alias_method :type, :class
+
 end

data/lib/jiraSOAP/entities/server_configuration.rb

@@ -1,17 +1,42 @@
+##
 # A simple structure that is used by {RemoteAPI#get_server_configuration}.
 class JIRA::ServerConfiguration < JIRA::Entity
-  add_attributes(
-    ['allowExternalUserManagement', :external_user_management_allowed, :to_boolean],
-    ['allowAttachments',            :attachments_allowed,              :to_boolean],
-    ['allowIssueLinking',           :issue_linking_allowed,            :to_boolean],
-    ['allowSubTasks',               :subtasks_allowed,                 :to_boolean],
-    ['allowTimeTracking',           :time_tracking_allowed,            :to_boolean],
-    ['allowUnassignedIssues',       :unassigned_issues_allowed,        :to_boolean],
-    ['allowVoting',                 :voting_allowed,                   :to_boolean],
-    ['allowWatching',               :watching_allowed,                 :to_boolean],
-    ['timeTrackingDaysPerWeek',     :time_tracking_days_per_week,      :to_i],
-    ['timeTrackingHoursPerDay',     :time_tracking_hours_per_day,      :to_i],
-    # In case we are using a version of JIRA that misspells 'management'
-    ['allowExternalUserManagment',  :external_user_management_allowed, :to_boolean]
-  )
+
+  # @return [Boolean]
+  add_attribute :external_user_management_allowed, 'allowExternalUserManagement',  :to_boolean
+
+  # @return [Boolean]
+  add_attribute :attachments_allowed, 'allowAttachments', :to_boolean
+
+  # @return [Boolean]
+  add_attribute :issue_linking_allowed, 'allowIssueLinking', :to_boolean
+
+  # @return [Boolean]
+  add_attribute :subtasks_allowed, 'allowSubTasks', :to_boolean
+
+  # @return [Boolean]
+  add_attribute :time_tracking_allowed, 'allowTimeTracking', :to_boolean
+
+  # @return [Boolean]
+  add_attribute :unassigned_issues_allowed, 'allowUnassignedIssues', :to_boolean
+
+  # @return [Boolean]
+  add_attribute :voting_allowed, 'allowVoting', :to_boolean
+
+  # @return [Boolean]
+  add_attribute :watching_allowed, 'allowWatching', :to_boolean
+
+  # @return [Number]
+  add_attribute :time_tracking_days_per_week, 'timeTrackingDaysPerWeek', :to_i
+
+  # @return [Number]
+  add_attribute :time_tracking_hours_per_day, 'timeTrackingHoursPerDay', :to_i
+
+  ##
+  # @note JIRA misspells 'management', so we define this attribute twice
+  #       to cover both cases.
+  #
+  # @return [Boolean]
+  add_attribute :external_user_management_allowed, 'allowExternalUserManagment', :to_boolean
+
 end

data/lib/jiraSOAP/entities/server_info.rb

@@ -1,12 +1,24 @@
+##
 # Only contains basic information about the endpoint server and only used
 # by {RemoteAPI#get_server_info}.
 class JIRA::ServerInfo < JIRA::Entity
-  add_attributes(
-    ['baseUrl',     :base_url,     :to_url],
-    ['buildDate',   :build_date,   :to_date],
-    ['buildNumber', :build_number, :to_i],
-    ['edition',     :edition,      :to_s],
-    ['version',     :version,      :to_s],
-    ['serverTime',  :server_time,  :to_object, JIRA::TimeInfo]
-  )
+
+  # @return [NSURL,URI::HTTP]
+  add_attribute :base_url, 'baseUrl', :to_url
+
+  # @return [Time]
+  add_attribute :build_date, 'buildDate', :to_iso_date
+
+  # @return [Number]
+  add_attribute :build_number, 'buildNumber', :to_i
+
+  # @return [String]
+  add_attribute :edition, 'edition', :content
+
+  # @return [String]
+  add_attribute :version, 'version', :content
+
+  # @return [Array<JIRA::TimeInfo>]
+  add_attribute :server_time, 'serverTime', [:children_as_object, JIRA::TimeInfo]
+
 end

data/lib/jiraSOAP/entities/status.rb

@@ -1,4 +1,4 @@
+##
 # Contains all the metadata for an issue's status.
 class JIRA::Status < JIRA::IssueProperty
-  add_attributes
 end

data/lib/jiraSOAP/entities/time_info.rb

@@ -1,10 +1,17 @@
+##
 # Simple structure for a time and time zone; only used by JIRA::ServerInfo
 # objects, which themselves are only created when {RemoteAPI#get_server_info}
 # is called.
 class JIRA::TimeInfo < JIRA::Entity
-  add_attributes(
-    ['serverTime', :server_time, :to_date_string],
-    # in the form of 'America/Toronto'
-    ['timeZoneId', :timezone,    :to_s]
-  )
+
+  # @return [Time]
+  add_attribute :server_time, 'serverTime', :to_natural_date
+
+  ##
+  # @example
+  #  'America/Toronto'
+  #
+  # @return [String]
+  add_attribute :timezone, 'timeZoneId', :content
+
 end

data/lib/jiraSOAP/entities/user.rb

@@ -1,8 +1,12 @@
+##
 # Contains only the basic information about a user. The only things missing here
 # are the permissions and login statistics, but these are not given in the API.
 class JIRA::User < JIRA::UserName
-  add_attributes(
-    ['fullname', :full_name,     :to_s],
-    ['email',    :email_address, :to_s]
-  )
+
+  # @return [String]
+  add_attribute :full_name, 'fullname', :content
+
+  # @return [String]
+  add_attribute :email_address, 'email', :content
+
 end

data/lib/jiraSOAP/entities/usergroup.rb

@@ -0,0 +1,15 @@
+##
+# Though this class contains a name, it is not the same name that
+# you get from a {JIRA::NamedEntity}.
+class JIRA::UserGroup < JIRA::Entity
+
+  # @return [String]
+  add_attribute :name, 'name', :content
+
+  ##
+  # @todo I suspect that I will have to delete users from SOAPifying
+  #
+  # @return [Array<JIRA::User>]
+  add_attribute :users, 'users', [:children_as_objects, JIRA::User]
+
+end

data/lib/jiraSOAP/entities/username.rb

@@ -1,4 +1,10 @@
+##
+# @todo Find out if this is an abstract class.
+#
 # This is just a @name, JIRA::User should inherit from this class
 class JIRA::UserName < JIRA::Entity
-  add_attributes(['name', :username, :to_s])
+
+  # @return [String]
+  add_attribute :username, 'name', :content
+
 end

data/lib/jiraSOAP/entities/version.rb

@@ -1,22 +1,30 @@
-# @todo find out why we don't get a description for this object
+##
+# @todo Find out why we don't get a description for this object
+#
 # Represents a version for a project. The description field is never
 # included when you retrieve versions from the server.
 class JIRA::Version < JIRA::NamedEntity
-  add_attributes(
-    ['sequence',    :sequence,     :to_i],
-    ['released',    :released,     :to_boolean],
-    ['archived',    :archived,     :to_boolean],
-    ['releaseDate', :release_date, :to_date]
-  )
 
-  # @todo make this method shorter
+  # @return [Number]
+  add_attribute :sequence, 'sequence', :to_i
+
+  # @return [Boolean]
+  add_attribute :released, 'released', :to_boolean
+
+  # @return [Boolean]
+  add_attribute :archived, 'archived', :to_boolean
+
+  # @return [Time]
+  add_attribute :release_date, 'releaseDate', :to_iso_date
+
   # @param [Handsoap::XmlMason::Node] msg
   # @return [Handsoap::XmlMason::Node]
   def soapify_for(msg)
     msg.add 'name', @name
-    msg.add 'archived', @archived unless @archived.nil?
-    msg.add 'sequence', @sequence unless @sequence.nil?
-    msg.add 'releaseDate', @release_date.xmlschema unless @release_date.nil?
-    msg.add 'released', @released unless @released.nil?
+    msg.add 'archived', @archived if @archived
+    msg.add 'sequence', @sequence if @sequence
+    msg.add 'releaseDate', @release_date.xmlschema if @release_date
+    msg.add 'released', @released if @released
   end
+
 end