Permalink
Browse files

Starting to document the codebase

  • Loading branch information...
1 parent 851e0ce commit 94a20420bb6eb78698fdb15ab70a8a3fc4d472d8 @zmoazeni committed Apr 13, 2010
Showing with 79 additions and 3 deletions.
  1. +3 −0 .document
  2. +10 −1 Rakefile
  3. +5 −0 lib/harvest/api/account.rb
  4. +29 −0 lib/harvest/base.rb
  5. +1 −2 lib/harvest/timezones.rb
  6. +31 −0 lib/harvested.rb
View
@@ -0,0 +1,3 @@
+README.md
+lib/**/*.rb
+MIT-LICENSE
View
@@ -6,7 +6,7 @@ begin
Jeweler::Tasks.new do |gem|
gem.name = "harvested"
gem.summary = %Q{A Ruby Wrapper for the Harvest API http://www.getharvest.com/}
- gem.description = %Q{Harvested wraps the Harvest API concisely without the use of Rails dependencies. More information about the Harvest API can be found at http://www.getharvest.com/api}
+ gem.description = %Q{Harvested wraps the Harvest API concisely without the use of Rails dependencies. More information about the Harvest API can be found on their website (http://www.getharvest.com/api). For support hit up the Mailing List (http://groups.google.com/group/harvested)}
gem.email = "zach.moazeni@gmail.com"
gem.homepage = "http://github.com/zmoazeni/harvested"
gem.authors = ["Zach Moazeni"]
@@ -50,3 +50,12 @@ rescue LoadError
end
task :default => %w(spec features)
+
+begin
+ require 'yard'
+ YARD::Rake::YardocTask.new
+rescue LoadError
+ task :yardoc do
+ abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+ end
+end
@@ -1,6 +1,11 @@
module Harvest
module API
+
+ # API Methods to contain all account actions
class Account < Base
+
+ # Returns the current rate limit information
+ # @return [Harvest::RateLimitStatus]
def rate_limit_status
response = request(:get, credentials, '/account/rate_limit_status')
Harvest::RateLimitStatus.parse(response.body)
View
@@ -2,16 +2,45 @@ module Harvest
class Base
attr_reader :request, :credentials
+ # @see Harvest.client
+ # @see Harvest.hardy_client
def initialize(subdomain, username, password, options = {})
options[:ssl] = true if options[:ssl].nil?
@credentials = Credentials.new(subdomain, username, password, options[:ssl])
raise InvalidCredentials unless credentials.valid?
end
+ # All API actions surrounding accounts
+ #
+ # @return [Harvest::API::Account]
def account
@account ||= Harvest::API::Account.new(credentials)
end
+ # All API Actions surrounding Clients
+ #
+ # == Examples
+ # harvest.clients.all() # Returns all clients in the system
+ #
+ # harvest.clients.find(100) # Returns the client with id = 100
+ #
+ # client = Harvest::Client.new(:name => 'SuprCorp')
+ # saved_client = harvest.clients.create(client) # returns a saved version of Harvest::Client
+ #
+ # client = harvest.clients.find(205)
+ # client.name = 'SuprCorp LTD.'
+ # updated_client = harvest.clients.update(client) # returns an updated version of Harvest::Client
+ #
+ # client = harvest.clients.find(205)
+ # harvest.clients.delete(client) # returns 205
+ #
+ # client = harvest.clients.find(301)
+ # deactivated_client = harvest.clients.deactivate(client) # returns an updated deactivated client
+ # activated_client = harvest.clients.activate(client) # returns an updated activated client
+ #
+ # @see Harvest::Behavior::Crud
+ # @see Harvest::Behavior::Activatable
+ # @return [Harvest::API::Clients]
def clients
@clients ||= Harvest::API::Clients.new(credentials)
end
View
@@ -1,6 +1,5 @@
-# shamelessly ripped from Rails: http://github.com/rails/rails/blob/master/activesupport/lib/active_support/values/time_zone.rb
-
module Harvest
+ # shamelessly ripped from Rails: http://github.com/rails/rails/blob/master/activesupport/lib/active_support/values/time_zone.rb
module Timezones
MAPPING = {
"pacific/midway" => "International Date Line West",
View
@@ -19,10 +19,41 @@ module Harvest
VERSION = "0.3.0".freeze
class << self
+
+ # Creates a standard client that will raise all errors it encounters
+ #
+ # == Options
+ # * +:ssl+ - Whether or not to use SSL when connecting to Harvest. This is dependent on whether your account supports it. Set to +true+ by default
+ # == Examples
+ # Harvest.client('mysubdomain', 'myusername', 'mypassword', :ssl => false)
+ #
+ # @return [Harvest::Base]
def client(subdomain, username, password, options = {})
Harvest::Base.new(subdomain, username, password, options)
end
+ # Creates a hardy client that will retry common HTTP errors it encounters and sleep() if it determines it is over your rate limit
+ #
+ # == Options
+ # * +:ssl+ - Whether or not to use SSL when connecting to Harvest. This is dependent on whether your account supports it. Set to +true+ by default
+ # * +:retry+ - How many times the hardy client should retry errors. Set to +5+ by default.
+ #
+ # == Examples
+ # Harvest.hardy_client('mysubdomain', 'myusername', 'mypassword', :ssl => true, :retry => 3)
+ #
+ # == Errors
+ # The hardy client will retry the following errors
+ # * Harvest::Unavailable
+ # * Harvest::InformHarvest
+ # * Net::HTTPError
+ # * Net::HTTPFatalError
+ # * Errno::ECONNRESET
+ #
+ # == Rate Limits
+ # The hardy client will make as many requests as it can until it detects it has gone over the rate limit. Then it will +sleep()+ for the how ever long it takes for the limit to reset. You can find more information about the Rate Limiting at http://www.getharvest.com/api
+ #
+ # @return [Harvest::HardyClient] a Harvest::Base wrapped in a Harvest::HardyClient
+ # @see Harvest::Base
def hardy_client(subdomain, username, password, options = {})
retries = options.delete(:retry)
Harvest::HardyClient.new(client(subdomain, username, password, options), (retries || 5))

0 comments on commit 94a2042

Please sign in to comment.