More documentation

lib/harvest/api/contacts.rb

@@ -11,7 +11,7 @@ def all(client_id = nil)
         else
           request(:get, credentials, "/contacts")
         end
-
+        
         api_model.parse(response.body)
       end
     end

lib/harvest/base.rb

@@ -12,6 +12,9 @@ def initialize(subdomain, username, password, options = {})
 
     # All API actions surrounding accounts
     #
+    # == Examples
+    #   harvest.account.rate_limit_status # Returns a Harvest::RateLimitStatus
+    #
     # @return [Harvest::API::Account]
     def account
       @account ||= Harvest::API::Account.new(credentials)
@@ -45,6 +48,26 @@ def clients
       @clients ||= Harvest::API::Clients.new(credentials)
     end
 
+    # All API Actions surrounding Client Contacts
+    # 
+    # == Examples
+    #   harvest.contacts.all() # Returns all contacts in the system
+    #   harvest.contacts.all(10) # Returns all contacts for the client id=10 in the system
+    #   
+    #   harvest.contacts.find(100) # Returns the contact with id = 100
+    #   
+    #   contact = Harvest::Contact.new(:first_name => 'Jane', :last_name => 'Doe', :client_id => 10)
+    #   saved_contact = harvest.contacts.create(contact) # returns a saved version of Harvest::Contact
+    #
+    #   contact = harvest.contacts.find(205)
+    #   contact.first_name = 'Jilly'
+    #   updated_contact = harvest.contacts.update(contact) # returns an updated version of Harvest::Contact
+    #   
+    #   contact = harvest.contacts.find(205)
+    #   harvest.contacts.delete(contact) # returns 205
+    # 
+    # @see Harvest::Behavior::Crud
+    # @return [Harvest::API::Contacts]
     def contacts
       @contacts ||= Harvest::API::Contacts.new(credentials)
     end

lib/harvest/base_model.rb

@@ -1,21 +1,58 @@
 module Harvest
+  # The parent class of all Harvest models. Contains useful inheritable methods
   class BaseModel
+
+    # Initializes the model. You can pass the attributes as a hash in a ActiveRecord-like style
+    #
+    # == Examples
+    #   client = Harvest::Client.new(:name => 'John Doe')
+    #   client.name # returns 'John Doe'
     def initialize(attributes = {})
       self.attributes = attributes
     end
-
+
+    # Given a hash, sets the corresponding attributes
+    #
+    # == Examples
+    #   client = Harvest::Client.new(:name => 'John Doe')
+    #   client.name # returns 'John Doe'
+    #   client.attributes = {:name => 'Terry Vaughn'}
+    #   client.name # returns 'Terry Vaughn'
+    #
+    # @return [void]
     def attributes=(attributes)
       attributes.each {|k,v| send("#{k}=", v)}
     end
-
+
+    # Checks the equality of another model based on the id
+    #
+    # == Examples
+    #  client1 = Harvest::Client.new(:id => 1)
+    #  client2 = Harvest::Client.new(:id => 1)
+    #  client3 = Harvest::Client.new(:id => 2)
+    #  
+    #  client1 == client2 # returns true
+    #  client1 == client3 # returns false
+    #
+    # @return [Boolean]
     def ==(other)
       id == other.id
     end
-
+
+    # Returns the id of the model
+    #
+    # == Examples
+    #  client = Harvest::Client.new(:id => 1)
+    #  client.to_i # returns 1
+    #
+    # @return [Fixnum]
     def to_i
       id
     end
-
+
+    # Builds the XML of the model. Primarily used to interact with the Harvest API.
+    # 
+    # @return [String]
     def to_xml
       builder = Builder::XmlMarkup.new
       builder.tag!(self.class.tag_name) do |c|
@@ -26,6 +63,8 @@ def to_xml
     end
 
     class << self
+      # This sets the API path so the API collections can use them in an agnostic way
+      # @return [void]
       def api_path(path = nil)
         @path ||= path
       end

lib/harvest/client.rb

@@ -1,4 +1,14 @@
 module Harvest
+  # The model that contains information about a client
+  #
+  # == Fields
+  # [+id+] the id of the client
+  # [+name+] (REQUIRED) the name of the client
+  # [+details+] the details of the client
+  # [+currency+] what type of currency is associated with the client
+  # [+currency_symbol+] what currency symbol is associated with the client
+  # [+update_at+] the last modification timestamp
+  # [+active?+] true|false on whether the client is active
   class Client < BaseModel
     include HappyMapper
 
@@ -12,7 +22,7 @@ class Client < BaseModel
     element :currency_symbol, String, :tag => "currency-symbol"
     element :cache_version, Integer, :tag => "cache-version"
     element :updated_at, Time, :tag => "updated-at"
-
+    
     alias_method :active?, :active
   end
 end

lib/harvest/contact.rb

@@ -1,4 +1,16 @@
 module Harvest
+  # The model that contains information about a client contact
+  #
+  # == Fields
+  # [+id+] the id of the contact
+  # [+client_id+] (REQUIRED) the id of the client this contact is associated with
+  # [+first_name+] (REQUIRED) the first name of the contact
+  # [+last_name+] (REQUIRED) the last name of the contact
+  # [+email+] the email of the contact
+  # [+title+] the title of the contact
+  # [+phone_office+] the office phone number of the contact
+  # [+phone_moble+] the moble phone number of the contact
+  # [+fax+] the fax number of the contact
   class Contact < BaseModel
     include HappyMapper
 
@@ -12,5 +24,6 @@ class Contact < BaseModel
     element :phone_office, String, :tag => "phone-office"
     element :phone_mobile, String, :tag => "phone-mobile"
     element :fax, String
+    element :title, String
   end
 end

lib/harvest/rate_limit_status.rb

@@ -1,4 +1,13 @@
 module Harvest
+
+  # The model that contains the information about the user's rate limit
+  #
+  # == Fields
+  # [+last_access_at+]  The last registered request
+  # [+count+] The current number of requests registered
+  # [+timeframe_limit+] The amount of seconds before a rate limit refresh occurs
+  # [+max_calls+] The number of requests you can make within the +timeframe_limit+
+  # [+lockout_seconds+] If you exceed the rate limit, how long you will be locked out from Harvest
   class RateLimitStatus < BaseModel
     include HappyMapper
 
@@ -9,6 +18,9 @@ class RateLimitStatus < BaseModel
     element :max_calls, Integer, :tag => 'max-calls'
     element :lockout_seconds, Integer, :tag => 'lockout-seconds'
 
+    # Returns true if the user is over their rate limit
+    # @return [Boolean]
+    # @see http://www.getharvest.com/api
     def over_limit?
       count > max_calls
     end