ruby_desk 0.7.0 → 0.8.0

data/README.rdoc

@@ -6,6 +6,8 @@ A gem built by BadrIT (www.badrit.com) that works as an interface for oDesk APIs
 If you want to use oDesk APIs with Rails applications you may better use ror_desk.
 ror_desk is a plugin built on Ruby Desk and makes it much easier to use with Rails.
 
+For more information read the documentation at http://aseldawy.github.com/ruby_desk/
+
 == Example
 Initialize with your api key
   rd = RubyDesk::Connector.new(api_key, api_secret)

data/VERSION

@@ -1 +1 @@
-0.7.0
+0.8.0

data/lib/ruby_desk/connector.rb

@@ -6,6 +6,8 @@ require 'rexml/document'
 require 'json'
 
 module RubyDesk
+  # Basic methods used for connecting with oDesk like signing request parameters and parsing response.
+  # This class is also responsible for authorizing user
   class Connector
     ODESK_URL = "www.odesk.com/"
     ODESK_API_URL = "#{ODESK_URL}api/"
@@ -15,6 +17,7 @@ module RubyDesk
       :base_url=>ODESK_API_URL, :auth=>true}
 
     attr_writer :frob
+    attr_accessor :auth_user
 
     def initialize(api_key=nil, api_secret=nil, api_token=nil)
       @api_key = api_key
@@ -76,7 +79,8 @@ module RubyDesk
       http = Net::HTTP.new(url.host, url.port)
       http.use_ssl = true
 
-      data = api_call[:params].to_a.map{|pair| pair.join '='}.join('&')
+      # Concatenate parameters to form data
+      data = api_call[:params].to_a.map{|pair| pair.map{|x| URI.escape(x.to_s)}.join '='}.join('&')
       headers = {
         'Content-Type' => 'application/x-www-form-urlencoded'
       }
@@ -99,9 +103,11 @@ module RubyDesk
 
       case resp.code
         when "200" then return data
-        when "401" then raise RubyDesk::UnauthorizedError, data
+        when "400" then raise RubyDesk::BadRequest, data
+        when "401", "403" then raise RubyDesk::UnauthorizedError, data
         when "404" then raise RubyDesk::PageNotFound, data
         when "500" then raise RubyDesk::ServerError, data
+        else raise RubyDesk::Error, data
       end
 
     end
@@ -131,7 +137,7 @@ module RubyDesk
     # return the URL that logs user out of odesk applications
     def logout_url
       logout_call = prepare_api_call("", :base_url=>ODESK_AUTH_URL,
-        :secure=>false, :auth=>false)
+        :secure=>false, :auth=>false, :format=>nil)
       return logout_call[:url]
     end
 
@@ -147,6 +153,7 @@ module RubyDesk
       json = prepare_and_invoke_api_call 'auth/v1/keys/tokens',
           :params=>{:frob=>@frob, :api_key=>@api_key}, :method=>:post,
           :auth=>false
+      @auth_user = User.new(json['auth_user'])
       @api_token = json['token']
     end
 

data/lib/ruby_desk/job.rb

@@ -0,0 +1,215 @@
+# A job opening with the following attributes
+# * adj_score
+# * amount
+# * ciphertext
+# * country
+# * create_date
+# * engagement_weeks
+# * hours_per_week
+# * job_category_level_one
+# * job_category_level_two
+# * job_type
+# * op_adjusted_score
+# * op_amount
+# * op_buyer_ace
+# * op_city
+# * op_company_name
+# * op_contract_date
+# * op_country
+# * op_date_created
+# * op_description
+# * op_eng_duration
+# * op_hrs_per_week
+# * op_job
+# * op_job_category_
+# * op_job_type
+# * op_num_of_pending_invites
+# * op_pref_english_skill
+# * op_pref_fb_score
+# * op_pref_hourly_rate
+# * op_pref_odesk_hours
+# * op_pref_test
+# * op_pref_test_name
+# * op_recno
+# * op_required_skills
+# * op_status_for_search
+# * op_title
+# * op_tot_asgs
+# * op_tot_cand
+# * op_tot_cand_client
+# * op_tot_cand_prof
+# * op_tot_feedback
+# * op_tot_fp_asgs
+# * op_tot_fp_charge
+# * op_tot_hours
+# * op_tot_hr_asgs
+# * op_tot_hr_charge
+# * op_tot_intv
+# * op_tot_jobs_filled
+# * op_tot_jobs_posted
+# * record_id
+# * search_status
+# * timezone
+# * total_billed_assignments
+# * total_charge
+# * total_hours
+class RubyDesk::Job < RubyDesk::OdeskEntity
+  attributes :op_tot_hours, :job_category_level_two, :op_company_name,
+      :op_tot_cand_client, :record_id, :op_amount, :total_hours,
+      :op_date_created, :op_city, :country, :op_tot_intv, :op_tot_feedback,
+      :search_status, :op_job, :op_hrs_per_week, :op_job_category_, :op_country,
+      :amount, :op_tot_cand_prof, :op_tot_asgs, :total_charge,
+      :op_status_for_search, :op_tot_cand, :op_buyer_ace,
+      :job_category_level_one, :timezone, :op_pref_test, :adj_score,
+      :op_num_of_pending_invites, :op_tot_fp_asgs, :op_required_skills,
+      :ciphertext, :op_title, :op_pref_fb_score, :op_tot_hr_asgs, :create_date,
+      :op_tot_jobs_filled, :op_pref_hourly_rate, :op_tot_jobs_posted,
+      :job_type, :hours_per_week, :op_job_type, :op_pref_test_name,
+      :op_pref_english_skill, :op_pref_odesk_hours, :op_tot_fp_charge,
+      :op_contract_date, :op_tot_hr_charge, :engagement_weeks,
+      :op_adjusted_score, :op_recno, :total_billed_assignments,
+      :op_description, :op_eng_duration
+   
+  # <h2>Details on Search Parameters</h2>
+  # <p>&nbsp;</p>
+  # <ul>
+  # <li><b>q -</b> OpeningData<b>&nbsp;</b>(Opening Data)
+  # 
+  # <ul>
+  # <li>Search the text of the job description</li>
+  # </ul>
+  # </li>
+  # <li><b>c1 -</b> JobCategory<b>&nbsp;(</b>Level One Job Category)
+  # <ul>
+  # <li>Limit your search to a specific <a href="/all-categories">category</a></li>
+  # </ul>
+  # </li>
+  # <li><b>c2 -</b> second_category<b>&nbsp;</b>(Second Level Job Category)
+  # 
+  # <ul>
+  # <li>Limit your search to a specific <a href="/all-categories">sub-category</a>
+  # <ul>
+  # <li>You must use a level one category in order to use a second level category.</li>
+  # </ul>
+  # </li>
+  # </ul>
+  # </li>
+  # <li><b>fb -</b> adjusted_score<b>&nbsp;</b>(Adjusted Score)
+  # <ul>
+  # <li>Limit your search to buyers with at least a score of the number passed in this parameter.
+  # 
+  # <ul>
+  # <li>This number must be <strong>5</strong> or less</li>
+  # </ul>
+  # </li>
+  # </ul>
+  # </li>
+  # <li><b>min -</b> min_budget<b>&nbsp;</b>(Min Budget)
+  # <ul>
+  # <li>Limit your search to jobs with a budget greater than this number.</li>
+  # 
+  # </ul>
+  # </li>
+  # <li><b>max -</b> max_budget<b>&nbsp;</b>(Max Budget)
+  # <ul>
+  # <li>Limit your search to jobs with a budget less than this number.</li>
+  # </ul>
+  # </li>
+  # <li><b>t -</b> JobType<b>&nbsp;</b>(Job Type)
+  # <ul>
+  # <li>oDesk has both hourly jobs and fixed prices jobs. This parameter allows you to limit your search to one or the other.
+  # 
+  # <ul>
+  # <li>Hourly Jobs = '<strong>Hourly</strong>'</li>
+  # <li>Fixed Priced Jobs = '<strong>Fixed</strong>'</li>
+  # </ul>
+  # </li>
+  # <li><strong>wl -</strong> hours_per_week(Hours per Week)
+  # <ul>
+  # <li>This parameter can only be used when searching Hourly jobs. These numbers are a little arbitrary, so follow the following parameters in order to successfully use this parameter:
+  # <ul>
+  # 
+  # <li>
+  # <p>As Needed &lt; 10 Hours/Week = '<strong>0</strong>'</p>
+  # </li>
+  # <li>
+  # <p>Part Time: 10-30 hrs/week = '<strong>20</strong>'</p>
+  # </li>
+  # <li>Full Time: 30+ hrs/week = '<strong>40</strong>'</li>
+  # 
+  # </ul>
+  # </li>
+  # </ul>
+  # </li>
+  # <li><b>dur -</b> engagement_duration<b>&nbsp;</b>(Engagement Duration)
+  # <ul>
+  # <li>This parameter can only be used when searching Hourly jobs. These numbers are a little arbitrary, so follow the following parameters in order to successfully use this parameter:
+  # <ul>
+  # <li>Ongoing / More than 6 months = '<strong>1</strong>'</li>
+  # <li>3 to 6 months = '<strong>2</strong>'</li>
+  # 
+  # <li>1 to 3 months = '<strong>3</strong>'</li>
+  # <li>Less than 1 month = '<strong>4</strong>'</li>
+  # <li>Less than 1 week = '<strong>5</strong>'</li>
+  # </ul>
+  # </li>
+  # </ul>
+  # </li>
+  # </ul>
+  # 
+  # </li>
+  # <li><b>dp -</b> Date_Posted<b>&nbsp;</b><strong>(</strong>Date Posted)
+  # <ul>
+  # <li>Search jobs posted after this date.
+  # <ul>
+  # <li>Format for date: <em>07-22-2009</em></li>
+  # </ul>
+  # </li>
+  # </ul>
+  # </li>
+  # <li><b>st -</b> status_for_search<b>&nbsp;</b>(Status for Search)
+  # 
+  # <ul>
+  # <li>Search Canceled jobs, In Progress Jobs and Completed Jobs: By default this default to Open Jobs
+  # <ul>
+  # <li>Open Jobs = '<strong>Open</strong>'</li>
+  # <li>Jobs in Progress = '<strong>In Progress</strong>'</li>
+  # <li>Completed Jobs = '<strong>Completed</strong>'</li>
+  # <li>Canceled Jobs = '<strong>Cancelled</strong>'</li>
+  # 
+  # </ul>
+  # </li>
+  # </ul>
+  # </li>
+  # <li><strong>tba</strong> - total_billed_assignments<b>&nbsp;</b>(Total Billed Assignments)
+  # <ul>
+  # <li>Limit your search to buyers who completed at least this number of paid assignments
+  # <ul>
+  # <li>For example tb=5 searches buyers who have at least 5 billed assignments</li>
+  # </ul>
+  # </li>
+  # </ul>
+  # </li>
+  # 
+  # <li><strong>gr</strong> -&nbsp;PrefGroup(Preferred Group)providers
+  # <ul>
+  # <li>Limits your search to buyers in a particular group</li>
+  # </ul>
+  # </li>
+  # <li><strong>to</strong> - titles_only<b>&nbsp;</b>(titles only)
+  # <ul>
+  # <li>Limits your search to job titles only. (you should be able to combine this search)</li>
+  def self.search(connector, query_options={})
+    if query_options.respond_to? :to_str
+      return search(connector, :q=>query_options.to_str)
+    end
+    json = connector.prepare_and_invoke_api_call(
+        'profiles/v1/search/jobs', :method=>:get,
+        :auth=>false, :sign=>false, :params=>query_options)
+    jobs = []
+    [json['jobs']['job']].flatten.each do |job|
+      jobs << self.new(job)
+    end
+    return jobs
+  end
+end

data/lib/ruby_desk/odesk_entity.rb

@@ -2,6 +2,46 @@ class RubyDesk::OdeskEntity
   @@complex_attributes = {}
   
   class << self
+    # Defines a new attribute or multiple attributes to this class.
+    # Allowed options:
+    #   * class: The class used to initialize this attribute
+    #   * sub_element: Indicates this is an array. Name of the key used to initialize this attribute.
+    #
+    # Here are some examples of how to use this method
+    # class Project
+    #   # Defines a new attribute called 'name'.
+    #   # This is generally used for defining simple attributes such as String or integer
+    #   attribute :name
+    #
+    #   # Defines two attributes called 'description' and 'priority'.
+    #   attributes :description, :priority
+    #   # The same effect can be accomplished by calling
+    #   attribute :description
+    #   attribute :priority
+    #
+    #   # Defines an attribute called 'manager' of class User
+    #   # This class is used to initialize this attribute as we will see later
+    #   attribute :manager, :class=>User
+    #
+    #   # Defines an attribute called 'tasks' which is an array of type Task
+    #   attribute :tasks, :class=>Task, :sub_element=>"tasks"
+    # end
+    #
+    # Initialization
+    # ==============
+    # The above class Project can be initialized like this
+    # # An instance of class Project all attributes set to nil
+    # Project.new
+    #
+    # # Initialize simple attributes with the given values
+    # Project.new :name=>"GitHub project", :description=>"Sample project on git hub"
+    #
+    # # Initialize complex attribute
+    # # This will initialize manager with: User.new(:name=>"Ahmed", :birthday=>Date.parse("3/3/1983"))
+    # Project.new :manager=>{:name=>"Ahmed", :birthday=>Date.parse("3/3/1983")}
+    #
+    # # Initializes 'tasks' attribute with [Task.new(:name=>"task1", Task.new(:name=>"task2", :priority=>3}]
+    # Project.new :tasks=>[{:name=>"task1"}, {:name=>"task2", :priority=>3}]
     def attribute(*att_names)
       options = nil
       if att_names.last.is_a?Hash
@@ -16,7 +56,18 @@ class RubyDesk::OdeskEntity
     alias attributes attribute
   end
 
-  
+
+  # Creates a new object of this class
+  # Initial values of attributes is passed as a paramter
+  #   * params: A hash used to initialize this object.
+  #     The key is the name of the attribute to initialize.
+  #     The value is used as the initial value for this attribute.
+  #     If the attribute is defined a class in creation,
+  #     the value is used as an initialization parameter with this class.
+  #     If the attribute is marked as "sub_element" in creation,
+  #     the value is assumed to be an array.
+  #     Each entry in the array is used as an initialization parameter to create a new element.
+  #     If the value is not an array, it is used to create an array of single element.
   def initialize(params={})
     params.each do |k, v|
       attribute_options = @@complex_attributes[k.to_s] || {}
@@ -34,7 +85,7 @@ class RubyDesk::OdeskEntity
             end
           end
         else
-          # This attribute is a single comple attribute
+          # This attribute is a single complex attribute
           self.instance_variable_set("@#{k}", attribute_options[:class].new(v))
         end
       else

data/lib/ruby_desk/provider.rb

@@ -1,3 +1,126 @@
+# A provider in oDesk.
+# <p>There is a TON&nbsp;of info returned here and the best way to see what this actually means is to try pulling data from a few providers and match up the fields, most of the response fields are human readable. Here is some aditional info that should help decipher this response:</p>
+# 
+# <p>&nbsp;</p>
+# <ul>
+# <li>&lt;dev_userid&gt;scoopwilson&lt;/dev_userid&gt; The odesk users id of the provider</li>
+# <li>&lt;dev_rank_percentile&gt;82&lt;/dev_rank_percentile&gt; The providers rank overall on oDesk</li>
+# <li>&lt;dev_usr_score&gt;4.9681818181818&lt;/dev_usr_score&gt; The providers feedback score</li>
+# 
+# <li>&lt;dev_profile_access&gt;public&lt;/dev_profile_access&gt; The status of the providers profile (public or private)</li>
+# <li>&lt;skill&gt; The Skill tag describes a skill that the provider has listed in their profile</li>
+# <li>&lt;tsexam&gt; tsexam describes a test that the provider has taken and made public.</li>
+# <li>&lt;dev_score&gt; dev_score describes feedback that the provider has received after a job has been completed (or just closed)</li>
+# 
+# <li>&lt;dev_recent_rank_percentile&gt;80&lt;/dev_recent_rank_percentile&gt; The providers rank on oDesk using data from the last 90 days.</li>
+# <li>&lt;dev_active_interviews&gt;0&lt;/dev_active_interviews&gt; How many active interviews the provider is engaged in now.</li>
+# <li>&lt;dev_total_hours&gt;2526.1666666667&lt;/dev_total_hours&gt; The providers total hours worked on oDesk.</li>
+# 
+# <li>&lt;experience&gt; Describes the providers experience as listed in their profile under the Experience section</li>
+# <li>&lt;assignment&gt; Describes past assignements that are publicly viewable.</li>
+#
+# Here's a full list of all attributes available:
+# * affiliated
+# * ag_active_assignments
+# * ag_adj_score
+# * ag_adj_score_recent
+# * ag_billed_assignments
+# * ag_city
+# * ag_cny_recno
+# * ag_country
+# * ag_country_tz
+# * ag_description
+# * ag_hours_lastdays
+# * ag_last_date_worked
+# * ag_logo
+# * ag_manager_blurb
+# * ag_manager_name
+# * ag_member_since
+# * ag_name
+# * ag_portrait
+# * ag_rank_percentile
+# * ag_recent_hours
+# * ag_summary
+# * ag_teamid
+# * ag_teamid_rollup
+# * ag_tot_feedback
+# * ag_total_developers
+# * ag_total_hours
+# * agency_ciphertext
+# * assignments
+# * assignments_count
+# * candidacies
+# * certification
+# * ciphertext
+# * competencies
+# * dev_ac_agencies
+# * dev_active_interviews
+# * dev_adj_score
+# * dev_adj_score_recent
+# * dev_agency_ciphertext
+# * dev_agency_ref
+# * dev_availability
+# * dev_bill_rate
+# * dev_billed_assignments
+# * dev_billed_assignments_recent
+# * dev_blurb
+# * dev_blurb_short
+# * dev_category
+# * dev_city
+# * dev_country
+# * dev_cur_assignments
+# * dev_eng_skill
+# * dev_est_availability
+# * dev_expose_full_name
+# * dev_full_name
+# * dev_groups
+# * dev_ic
+# * dev_is_affiliated
+# * dev_is_ready
+# * dev_last_activity
+# * dev_last_worked
+# * dev_location
+# * dev_member_since
+# * dev_pay_agency_rate
+# * dev_pay_rate
+# * dev_portfolio_items_count
+# * dev_portrait
+# * dev_profile_title
+# * dev_rank_percentile
+# * dev_recent_hours
+# * dev_recent_rank_percentile
+# * dev_recno
+# * dev_region
+# * dev_scores
+# * dev_short_name
+# * dev_test_passed_count
+# * dev_timezone
+# * dev_tot_feedback
+# * dev_tot_feedback_recent
+# * dev_total_assignments
+# * dev_total_hours
+# * dev_total_hours_rounded
+# * dev_ui_profile_access
+# * dev_usr_score
+# * dev_year_exp
+# * education
+# * experiences
+# * favorited
+# * iinitialize
+# * is_odesk_ready
+# * job_categories
+# * oth_experiences
+# * permalink
+# * portfolio_items
+# * profile_title_full
+# * provider_profile_api
+# * response_time
+# * search_affiliate_providers_url
+# * skills
+# * trends
+# * tsexams
+# * tsexams_count
+# * version
 class RubyDesk::Provider < RubyDesk::OdeskEntity
 
   attributes :affiliated, :ag_name, :ag_description, :dev_adj_score_recent,
@@ -42,6 +165,11 @@ class RubyDesk::Provider < RubyDesk::OdeskEntity
   attribute :portfolio_items, :class=>RubyDesk::PortfolioItem, :sub_element=>'portfolio_item'
 
   class << self
+    # Returns all categories defined in oDesk.
+    # These categories are retrieved from a static text file and not updated from the web.
+    # Return value is a hash.
+    # Each key is a name of a root category.
+    # Value is an array of subcategories.
     def all_categories
       text = File.read(File.join(File.dirname(__FILE__), "..", "categories"))
       lines = text.split(/[\r\n]+/).map{|line| line.strip}
@@ -57,7 +185,9 @@ class RubyDesk::Provider < RubyDesk::OdeskEntity
       return categories
     end
 
-    # Implements search with the given criteria
+    # Implements search with the given criteria.
+    # For basic search, pass a string as the second parameter
+    # For advanced search, pass a string according to the following parameters
     #* q - ProfileData (ProfileData)
     #      * Profile data is any text that appears in a provider's profile. For example if q = 'odesk' the search would return any user's with the word odesk in their profile.
     #* c1 - JobCategory (First Level Job Category)
@@ -118,15 +248,22 @@ class RubyDesk::Provider < RubyDesk::OdeskEntity
       end
       json = connector.prepare_and_invoke_api_call(
         'profiles/v1/search/providers', :method=>:get,
-        :auth=>false, :sign=>false)
+        :auth=>false, :sign=>false, :params=>options)
 
       providers = []
-      [json['providers']['provider']].flatten.each do |provider|
-        providers << self.new(provider)
+      if json['providers']['provider']
+        [json['providers']['provider']].flatten.each do |provider|
+          providers << self.new(provider)
+        end
       end
       return providers
     end
 
+    # Retrieves the profile with the given user
+    # * connector: The RubyDesk::Connector that is connected to oDesk
+    # * id: The id of the user to retrieve his profile
+    # * options: A hash of options
+    #   * brief: set this to true to retrieve only a brief profile of the given user
     def get_profile(connector, id, options={})
       brief = options.delete :brief || false
       json = connector.prepare_and_invoke_api_call(

data/lib/ruby_desk/snapshot.rb

@@ -1,3 +1,126 @@
+# <h2>Response Details</h2>
+# <ul>
+# <li>&lt;snapshot&gt;
+# <ul>
+# <li>Snapshot detail container</li>
+# </ul>
+# </li>
+# <li>&lt;status&gt;PRIVATE&lt;/status&gt;
+# 
+# <ul>
+# <li>Status of the snapshot
+# <ul>
+# <li>LOGIN</li>
+# <li>NORMAL</li>
+# <li>PRIVATE</li>
+# <li>EXIT</li>
+# </ul>
+# </li>
+# </ul>
+# </li>
+# <li>&lt;time&gt;1229521500&lt;/time&gt;
+# 
+# <ul>
+# <li>The GMT&nbsp;that the snapshot was taken</li>
+# </ul>
+# </li>
+# <li>&lt;billing_status&gt;non-billed.disconnected&lt;/billing_status&gt;
+# <ul>
+# <li>A snapshot's billing status
+# <ul>
+# <li>non-billed.disconnected</li>
+# <li>billed.disconnected</li>
+# 
+# <li>billed.connected</li>
+# </ul>
+# </li>
+# </ul>
+# </li>
+# <li>&lt;activity&gt;0&lt;/activity&gt;</li>
+# <li>&lt;online_presence&gt;&lt;/online_presence&gt;</li>
+# <li>&lt;user&gt;
+# <ul>
+# <li>The general user details associated with the current use</li>
+# 
+# </ul>
+# </li>
+# <li>&lt;mouse_events_count/&gt;
+# <ul>
+# <li>The number of mouse events associated with this snapshot</li>
+# </ul>
+# </li>
+# <li>&lt;company_id&gt;agencyone&lt;/company_id&gt;
+# <ul>
+# <li>Company ID&nbsp;associated with this snapshot</li>
+# 
+# </ul>
+# </li>
+# <li>&lt;timezone&gt;America/Los_Angeles&lt;/timezone&gt;
+# <ul>
+# <li>User's time zone</li>
+# </ul>
+# </li>
+# <li>&lt;uid/&gt;
+# <ul>
+# <li>The user id</li>
+# </ul>
+# 
+# </li>
+# <li>&lt;keyboard_events_count/&gt;
+# <ul>
+# <li>Number of keyboard events counted for this snapshot</li>
+# </ul>
+# </li>
+# <li>&lt;last_worked&gt;
+# <ul>
+# <li>The timestamp last worked
+# <ul>
+# <li>Format:&nbsp;[<em>1240637782</em>]</li>
+# 
+# </ul>
+# </li>
+# </ul>
+# </li>
+# <li>&lt;memo/&gt;
+# <ul>
+# <li>Memo associated with the current time stamp</li>
+# </ul>
+# </li>
+# <li>&lt;active_window_title/&gt;
+# <ul>
+# <li>The title of the active window when the snapshot was taken</li>
+# </ul>
+# 
+# </li>
+# <li>&lt;report24_img&gt;
+# <ul>
+# <li>URL to a graph that describes a users activitly over a 24hr period</li>
+# </ul>
+# </li>
+# <li>&lt;computer_name/&gt;
+# <ul>
+# <li>The name of the computer where the snapshot was taken</li>
+# </ul>
+# </li>
+# <li>&lt;online_presence_img&gt;
+# 
+# <ul>
+# <li>URL&nbsp;for the default online user activity</li>
+# </ul>
+# </li>
+# <li>&lt;user_id&gt;
+# <ul>
+# <li>User id associated with the current snapshot</li>
+# </ul>
+# </li>
+# <li>&lt;client_version/&gt;
+# <ul>
+# <li>The oDesk Time Tracker version used to take the snapshot</li>
+# 
+# </ul>
+# </li>
+# <li>&lt;teamroom_api&gt;/api/team/v1/teamrooms/agencyone.xml&lt;/teamroom_api&gt;&nbsp;</li>
+# <li>&lt;workdiary_api&gt;/api/team/v1/workdiaries/agencyone/scoopwilson/20081217.xml&lt;/workdiary_api&gt;</li>
 class RubyDesk::Snapshot < RubyDesk::OdeskEntity
   attribute :status, :time, :billing_status, :report_url, :screenshot_img, :activity,
     :online_presence, :screenshot_url, :mouse_events_count, :company_id,
@@ -8,6 +131,10 @@ class RubyDesk::Snapshot < RubyDesk::OdeskEntity
 
   attribute :user, :class=>RubyDesk::User
 
+  # Retrieves work diary as an array of snapshots.
+  # The Work Diary method retrieves all snapshots from a single user account within a single day.
+  # Keep in mind that a day is dependent on server time and not the day in which the query is made.
+  # Make sure to test with various locations before you're done.
   def self.work_diary(connector, company_id, user_id, date = nil, timezone = "mine")
     json = connector.prepare_and_invoke_api_call(
       "team/v1/workdiaries/#{company_id}/#{user_id}" + (date ? "/"+date : ""),
@@ -19,6 +146,7 @@ class RubyDesk::Snapshot < RubyDesk::OdeskEntity
     end
   end
 
+  # Retrieves details of one snapshot
   def self.snapshot_details(connector, company_id, user_id, timestamp = nil)
     timestamp_param = case timestamp
       when String then timestamp