Add documentation for new features

README.rdoc

@@ -2,7 +2,7 @@
 
 == Description
 
-The Unfuzzle gem provides an interface to the Unfuddle JSON API
+The Unfuzzle gem provides an interface to the Unfuddle XML API
 
 == Installation
 
@@ -81,8 +81,28 @@ And can also be associated to a milestone for the project:
     ticket.description  # => "Wash my car"
     ticket.status       # => "closed"
 
+Unfuddle has additional associations for a ticket, including component, severity,
+and priority:
+
+    ticket.component      # => #<Unfuzzle::Component:0x12c5b54 ...>
+    ticket.component_name # => "User Accounts"
+    ticket.severity       # => #<Unfuzzle::Severity:0x12a357c ...>
+    ticket.severity_name  # => "Development"
+    ticket.priority       # => #<Unfuzzle::Priority:0x12811fc @id=3>
+    ticket.priority_name  # => "Normal"
+
 See the Ticket documentation for more information.
 
+== Updating
+
+Currently, only ticket updating is supported and only for a subset of the data:
+
+    ticket.title = 'This is a new title' # => "This is a new title"
+    ticket.update                        # => #<Unfuzzle::Response:0x1275280 ...>
+
+This will update the title of the ticket.  Other fields that can be updated include
+description and status. 
+
 == License
 
 Copyright (c) 2009 Patrick Reagan of Viget Labs (mailto:patrick.reagan@viget.com)

lib/unfuzzle.rb

@@ -31,7 +31,15 @@
 # 
 # From there, you can start accessing a list of projects:
 #
-#    Project.all
+#   >> Unfuzzle.projects
+#   => [#<Unfuzzle::Project:0x5f5c44 @id=1, @name="BlipCo", ...>, ... ]
+#
+# Or a specific project by its 'short name':
+#
+#   >> Unfuzzle.project('sample')
+#   => #<Unfuzzle::Project:0x123f888 @id=2, @name="Sample Project", ... >
+#
+# For more usage documentation, see README.doc.
 #
 module Unfuzzle
 

lib/unfuzzle/component.rb

@@ -1,4 +1,16 @@
 module Unfuzzle
+
+  # = Component
+  #
+  # Represents a Component in an Unfuddle project.  These are user-configurable
+  # and are custom for each project you have.  Examples include 'Administration',
+  # 'User Registration', etc..  A component has the following attributes:
+  #
+  # [id] The unique id for this component
+  # [name] The name of this component (e.g User Registration)
+  # [created_at] The date/time that this component was created
+  # [updated_at] The date/time that this component was last updated
+  #
   class Component
 
     include Graft::Model
@@ -9,6 +21,7 @@ class Component
     attribute :created_at, :from => 'created-at', :type => :time
     attribute :updated_at, :from => 'updated-at', :type => :time
 
+    # Find a component by ID for a given project
     def self.find_by_project_id_and_component_id(project_id, component_id)
       response = Request.get("/projects/#{project_id}/components/#{component_id}")
       new response.body

lib/unfuzzle/milestone.rb

@@ -6,7 +6,11 @@ module Unfuzzle
   #
   # [id] Unique identifier for this milestone
   # [name] Name of the milestone
-  #
+  # [archived] The archived status of this milestone (see Milestone#archived?)
+  # [due_on] The due date for this milestone
+  # [created_at] The date/time that this milestone was created
+  # [updated_at] The date/time that this milestone was last updated
+  # 
   class Milestone
 
     include Graft::Model
@@ -25,6 +29,7 @@ def self.find_all_by_project_id(project_id)
       collection_from(response.body, 'milestones/milestone')
     end
 
+    # Find a milestone by ID for a given project
     def self.find_by_project_id_and_milestone_id(project_id, milestone_id)
       response = Request.get("/projects/#{project_id}/milestones/#{milestone_id}")
       new response.body
@@ -35,6 +40,7 @@ def archived?
       archived == true
     end
 
+    # Does this milestone occur in the past?
     def past?
       due_on < Date.today
     end

lib/unfuzzle/priority.rb

@@ -1,10 +1,16 @@
 module Unfuzzle
+
+  # = Priority
+  #
+  # Represents a priority for a ticket.
+  #
   class Priority
 
     def initialize(id)
       @id = id
     end
 
+    # The name of the priority based on the supplied ID
     def name
       mapping[@id]
     end

lib/unfuzzle/project.rb

@@ -8,6 +8,9 @@ module Unfuzzle
   # [slug] The "short name" for this project
   # [name] The name of this project
   # [description] The description for the project
+  # [archived] The archived status of this project (see Project#archived?)
+  # [created_at] The date/time that this project was created
+  # [updated_at] The date/time that this project was last updated
   #
   class Project
 

lib/unfuzzle/request.rb

@@ -12,6 +12,7 @@ def self.get(resource_path)
       request.get
     end
 
+    # Send a PUT request with data and retrieve a Response
     def self.put(resource_path, payload)
       request = new(resource_path, payload)
       request.put
@@ -39,6 +40,7 @@ def get
       Response.new(client.request(request))
     end
 
+    # Send a PUT request to the configured endpoint
     def put
       request = Net::HTTP::Put.new(endpoint_uri.path)
       request.basic_auth Unfuzzle.username, Unfuzzle.password

lib/unfuzzle/severity.rb

@@ -1,4 +1,16 @@
 module Unfuzzle
+
+  # = Severity
+  #
+  # Represents a Severity in an Unfuddle project.  These are user-configurable
+  # and are custom for each project you have.  Examples include 'Story',
+  # 'Defect', etc..  A severity has the following attributes:
+  #
+  # [id] The unique identifier for this severity
+  # [name] The name of this severity
+  # [created_at] The date/time that this severity was created
+  # [updated_at] The date/time that this severity was last updated
+  #
   class Severity
 
     include Graft::Model
@@ -9,6 +21,7 @@ class Severity
     attribute :created_at, :from => 'created-at', :type => :time
     attribute :updated_at, :from => 'updated-at', :type => :time
 
+    # Find the severity by ID for a given project
     def self.find_by_project_id_and_severity_id(project_id, severity_id)
       response = Request.get("/projects/#{project_id}/severities/#{severity_id}")
       new response.body

lib/unfuzzle/ticket.rb

@@ -10,6 +10,9 @@ module Unfuzzle
   # [title] The title of the ticket (short)
   # [description] The full description of the ticket
   # [status] The ticket's status (new / accepted / resolved / closed)
+  # [due_on] The due date for this ticket
+  # [created_at] The date/time that this ticket was created
+  # [updated_at] The date/time that this ticket was last updated
   #
   class Ticket
 
@@ -41,10 +44,12 @@ def self.find_all_by_project_id_and_milestone_id(project_id, milestone_id)
       collection_from(response.body, 'tickets/ticket')
     end
 
+    # The Milestone associated with this ticket
     def milestone
       Milestone.find_by_project_id_and_milestone_id(project_id, milestone_id)
     end
 
+    # The Severity associated with this ticket
     def severity
       Severity.find_by_project_id_and_severity_id(project_id, severity_id)
     end
@@ -53,6 +58,7 @@ def severity_name
       severity.name
     end
 
+    # The Priority associated with this ticket
     def priority
       Priority.new(priority_id)
     end
@@ -61,6 +67,7 @@ def priority_name
       priority.name
     end
 
+    # The Component associated with this ticket
     def component
       Component.find_by_project_id_and_component_id(project_id, component_id)
     end
@@ -69,6 +76,7 @@ def component_name
       component.name
     end
 
+    # Hash representation of this ticket's data (for updating)
     def to_hash
       {
         'id'           => id,
@@ -81,6 +89,7 @@ def to_hash
       }
     end
 
+    # Update the ticket's data in unfuddle
     def update
       resource_path = "/projects/#{project_id}/tickets/#{id}"
       Request.put(resource_path, self.to_xml('ticket'))