Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Switch from TomDoc to YARD

This changes a lot of the documentation, but also changes the code a bit
to be able to document everything properly. The biggest changes are:

* No more setters in ContextIO::Account. These were private anyways, and
  code inside it was changed to adapt to this.
* ContextIO::Config now sets its attr_accessors explicitly.

The method visibility should now be specified both in the documentation
and in Ruby. The latter can be dropped if it makes for worse code inside
the library. Everything in the public API should be tagged @api public.
Everything not in the public API should be tagged @api private. This
means that you can easily find public and private API methods by running
yardoc with the --query option (--query="@api.text == 'public'" to only
get public API).

With this commit we have 100% documented. Let's try to keep it this way.
  • Loading branch information...
commit bfcdf4f5b04e6964d76be4191ea6964f52d2819c 1 parent 61d52f9
@henrikhodne henrikhodne authored
Showing with 432 additions and 266 deletions.
  1. +2 −1  .gitignore
  2. +7 −0 .yardopts
  3. +13 −13 README.md
  4. +2 −7 Rakefile
  5. +4 −1 context-io.gemspec
  6. +1 −0  lib/context-io.rb
  7. +158 −135 lib/context-io/account.rb
  8. +7 −4 lib/context-io/authentication.rb
  9. +52 −2 lib/context-io/config.rb
  10. +10 −6 lib/context-io/connection.rb
  11. +15 −3 lib/context-io/core_ext/hash.rb
  12. +11 −6 lib/context-io/error.rb
  13. +4 −0 lib/context-io/error/bad_request.rb
  14. +3 −1 lib/context-io/error/client_error.rb
  15. +5 −1 lib/context-io/error/forbidden.rb
  16. +2 −0  lib/context-io/error/internal_server_error.rb
  17. +5 −1 lib/context-io/error/not_found.rb
  18. +6 −1 lib/context-io/error/payment_required.rb
  19. +3 −1 lib/context-io/error/server_error.rb
  20. +3 −1 lib/context-io/error/service_unavailable.rb
  21. +5 −1 lib/context-io/error/unauthorized.rb
  22. +26 −29 lib/context-io/request.rb
  23. +16 −13 lib/context-io/request/oauth.rb
  24. +2 −3 lib/context-io/resource.rb
  25. +5 −0 lib/context-io/response.rb
  26. +6 −4 lib/context-io/response/parse_json.rb
  27. +19 −9 lib/context-io/response/raise_client_error.rb
  28. +13 −2 lib/context-io/response/raise_server_error.rb
  29. +9 −6 lib/context-io/source.rb
  30. +3 −1 lib/context-io/version.rb
  31. +15 −14 spec/account_spec.rb
View
3  .gitignore
@@ -1,4 +1,5 @@
-html
+doc
+.yardoc
pkg
Gemfile.lock
View
7 .yardopts
@@ -0,0 +1,7 @@
+--no-private
+--markup-provider=redcarpet
+--markup=markdown
+lib/**/*.rb
+-
+README.md
+LICENSE
View
26 README.md
@@ -4,7 +4,7 @@ ContextIO - Extract data from email
[![Build Status](https://secure.travis-ci.org/dvyjones/context-io.png)](http://travis-ci.org/dvyjones/context-io)
[![Dependency Status](https://gemnasium.com/dvyjones/context-io.png)](https://gemnasium.com/dvyjones/context-io)
-## DESCRIPTION
+## Description
ContextIO is a Ruby wrapper for the [Context.IO][contextio] web service.
@@ -19,20 +19,24 @@ ContextIO follows the rules of [Semantic Versioning][semver] and uses
[tomdoc]: http://tomdoc.org
-## INSTALLATION
+## Installation
The best way to install ContextIO is through Rubygems:
- $ [sudo] gem install context-io
+```
+$ [sudo] gem install context-io
+```
If you're installing from source, you can use [Bundler][bundler] to pick up all
the gems:
- $ bundle install
+```
+$ bundle install
+```
[bundler]: http://gembundler.org
-## USAGE
+## Usage
The ContextIO classes map pretty much one-to-one to the Context.IO API
resources, which you can find [on their documentation site][contextiodocs].
@@ -70,8 +74,7 @@ You can also find accounts matching a given email address.
account = ContextIO::Account.all(:email => 'me@example.org').first
```
-Contributing
-------------
+## Contributing
In the spirit of [free software][free-sw], **everyone** is encouraged to help
improve this project.
@@ -89,8 +92,7 @@ Here are some ways *you* can contribute:
* by closing [issues][issues]
* by reviewing patches
-Submitting an Issue
--------------------
+### Submitting an Issue
We use the [GitHub issue tracker][issues] to track bugs and features. Before
submitting a bug report or feature request, check to make sure it hasn't
@@ -102,8 +104,7 @@ details that may be necessary to reproduce the bug, including your gem version,
Ruby version and operating system. Ideally, a bug report should include a pull
request with failing specs.
-Submitting a Pull Request
--------------------------
+### Submitting a Pull Request
1. Fork the project.
2. Create a topic branch.
@@ -123,7 +124,6 @@ Submitting a Pull Request
[issues]: https://github.com/dvyjones/context-io/issues
-Copyright
----------
+## Copyright
Copyright (c) 2012 Henrik Hodne. See LICENSE for details.
View
9 Rakefile
@@ -49,13 +49,8 @@ require 'rspec/core/rake_task'
RSpec::Core::RakeTask.new(:spec)
-require 'rdoc/task'
-RDoc::Task.new do |rdoc|
- rdoc.main = 'README.md'
- rdoc.markup = 'tomdoc'
- rdoc.options << '--all'
- rdoc.options << '--charset=UTF-8'
-end
+require 'yard'
+YARD::Rake::YardocTask.new
#############################################################################
#
View
5 context-io.gemspec
@@ -31,7 +31,10 @@ Gem::Specification.new do |s|
s.add_development_dependency('rspec', '~> 2.8.0')
s.add_development_dependency('rake', '~> 0.9.0')
- s.add_development_dependency('rdoc', '~> 3.10')
+ s.add_development_dependency('yard', '~> 0.7.4')
+ s.add_development_dependency('yard-rspec', '~> 0.1')
+ s.add_development_dependency('redcarpet', '~> 1.17.2')
+ s.add_development_dependency('github-markup', '~> 0.7.0')
# = MANIFEST =
s.files = %w(
View
1  lib/context-io.rb
@@ -4,6 +4,7 @@
require 'context-io/source'
require 'context-io/message'
+# The main ContextIO namespace.
module ContextIO
extend Config
extend Authentication
View
293 lib/context-io/account.rb
@@ -1,96 +1,82 @@
+# encoding: utf-8
+
require 'context-io/resource'
module ContextIO
- # Public: An account. Create one of these for every user.
+ # An account. Create one of these for every user.
#
# This does not represent a mail account. An Account can have several mail
- # accounts attached to it.
+ # accounts attached to it as {Source}s.
+ #
+ # Only the {#first_name} and {#last_name} can be changed after creation.
class Account < ContextIO::Resource
- # Public: Returns the unique String ID of the account.
+ # @api public
+ # @return [String] The unique ID of the account.
attr_reader :id
- # Internal: Sets the unique String ID of the account.
- attr_writer :id
-
- # Public: Returns the String username of the account.
+ # @api public
+ # @return [String] The username of the account.
attr_reader :username
- # Internal: Sets the String username of the account.
- attr_writer :username
-
- # Public: Returns the Time the account was created.
+ # @api public
+ # @return [Time] When the account was created.
attr_reader :created
- # Internal: Sets the Time the account was created.
- attr_writer :created
-
- # Public: Returns the Time the account was suspended, or nil if the account
- # isn't suspended.
+ # @api public
+ # @return [Time, nil] When the account was suspended, or nil if the account
+ # isn't suspended.
attr_reader :suspended
- # Internal: Sets the Time the account was suspended, or nil if the account
- # isn't suspended.
- attr_writer :suspended
-
- # Public: Returns the Array of String email addresses associated with the
- # account.
+ # @api public
+ # @return [Array<String>] The email addresses associated with the account.
attr_reader :email_addresses
- # Internal: Sets the Array of String email addresses associated with the
- # account.
- attr_writer :email_addresses
-
- # Public: Returns the String first name of the account holder.
- attr_reader :first_name
-
- # Public: Sets the String first name of the account holder.
- attr_writer :first_name
+ # @api public
+ # @return [String] The first name of the account holder.
+ attr_accessor :first_name
- # Public: Returns the String last name of the account holder.
- attr_reader :last_name
+ # @api public
+ # @return [String] The last name of the account holder.
+ attr_accessor :last_name
- # Public: Sets the String last name of the account holder.
- attr_writer :last_name
-
- # Public: Returns the Time the password for the account expired, or nil if
- # the password hasn't expired.
+ # @api public
+ # @return [Time, nil] When the account password expired, or nil if the
+ # password hasn't expired.
attr_reader :password_expired
- # Internal: Sets the Time the password for the account expired, or nil if
- # the password hasn't expired.
- attr_writer :password_expired
-
- # Public: Returns an Array of Source objects associated with the account.
+ # @api public
+ # @return [Array<Source>] The sources associated with this account.
attr_reader :sources
- # Internal: Sets the Array of Source objects associated with the account.
- attr_writer :sources
-
- # Public: Get all accounts.
- #
- # query - An optional Hash (default: {}) containing a query to filter the
- # responses by:
- # :email - Only return accounts associated to this String email
- # address (optional).
- # :status - Only return accounts with sources whose status is of
- # a specific Symbol value. If an account has many
- # sources, only those matching the given value will be
- # included in the response. Possible statuses are:
- # :invalid_credentials, :connection_impossible,
- # :no_access_to_all_mail, :ok, :temp_disabled and
- # :disabled (optional).
- # :status_ok - A Boolean value representing whether to only return
- # accounts with sources that are working or not
- # working properly (true/false, respectively). As with
- # the :status filter above, only sources matching the
- # specific value are included in the response
- # (optional).
- # :limit - The Integer maximum number of results to return
- # (optional).
- # :offset - The Integer offset to start the list at (zero-based)
- # (optional).
- #
- # Returns an Array of Account objects.
+ # Get all the accounts, optionally filtered with a query
+ #
+ # @api public
+ #
+ # @param [Hash] query The query to filter accounts by. All fields are
+ # optional.
+ # @option query [String] :email Only return accounts associated with this
+ # email address.
+ # @option query [:invalid_credentials, :connection_impossible,
+ # :no_access_to_all_mail, :ok, :temp_disabled, :disabled] :status Only
+ # return accounts with sources whose status is the one given. If an
+ # account has several sources, only those matching the given status will
+ # be included in the response.
+ # @option query [true, false] :status_ok Whether to only return accounts
+ # with sources that are working or not working properly (true/false,
+ # respectively). As with the `:status` filter above, only sources matching
+ # the specific value are included in the response.
+ # @option query [Integer] :limit The maximum number of results to return.
+ # @option query [Integer] :offset The offset to start the list at (0 is no
+ # offset).
+ #
+ # @example Fetch all accounts
+ # ContextIO::Account.all
+ #
+ # @example Fetch all accounts with the email address me@example.com
+ # ContextIO::Account.all(:email => 'me@example.com')
+ #
+ # @return [Array<Account>] The accounts matching the query, or all if no
+ # query is given.
def self.all(query={})
query[:status] = query[:status].to_s.upcase if query[:status]
if query.has_key?(:status_ok)
@@ -101,64 +87,97 @@ def self.all(query={})
end
end
- # Public: Finds an account given its ID.
+ # Find an account given its ID
+ #
+ # @api public
#
- # id - The String ID of the account to look up.
+ # @param [String] id The ID of the account to look up.
#
- # Returns an Account instance with the data of the account with the given
- # ID.
+ # @example Find the account with the ID 'foobar'
+ # ContextIO::Account.find('foobar')
+ #
+ # @return [Account] The account with the given ID.
def self.find(id)
Account.from_json(get("/2.0/accounts/#{id}"))
end
- # Public: Initialize an Account.
+ # Initialize an Account
+ #
+ # @api public
#
- # attributes - A Hash of attributes to set on the account (default value:
- # {}):
- # :email - The String primary email address of the
- # account holder (optional).
- # :first_name - The String first name of the account holder
- # (optional).
- # :last_name - The String last name of the account holder
- # (optional).
+ # @param [Hash] attributes The attributes to set on the account (all values
+ # are optional).
+ # @option attributes [String] :email The primary email address of the
+ # account holder.
+ # @option attributes [String] :first_name The first name of the account
+ # holder.
+ # @option attributes [String] :last_name The last name of the account
+ # holder.
+ #
+ # @example Initialize an account with the email 'me@example.com'
+ # ContextIO::Account.new(:email => 'me@example.com')
def initialize(attributes={})
- self.email_addresses = [attributes[:email]] if attributes[:email]
- self.first_name = attributes[:first_name]
- self.last_name = attributes[:last_name]
+ @email_addresses = [attributes[:email]] if attributes[:email]
+ @first_name = attributes[:first_name]
+ @last_name = attributes[:last_name]
end
- # Public: Send the account info to Context.IO
+ # Send the account info to Context.IO
+ #
+ # If this is the first time the account is sent to Context.IO, the first
+ # email address set will be sent as the primary email address, and the first
+ # and last name will be sent if they are specified. You are required to
+ # specify one email address.
+ #
+ # If the account has been sent to Context.IO before, this will update the
+ # first and last name.
+ #
+ # @api public
+ #
+ # @raise [ArgumentError] If there isn't at least one email address specified
+ # in the {#email_addresses} field.
+ #
+ # @example Create an account
+ # account = ContextIO::Account.new(:email => 'me@example.com')
+ # account.save
#
- # Returns true if the save was successful or false if it was unsuccessful.
+ # @return [true, false] Whether the save succeeded or not.
def save
self.id ? update_record : create_record
end
- # Public: Update attributes on the account object and then send them to
- # Context.IO.
+ # Update attributes on the account object and then send them to Context.IO
#
- # attributes - A Hash containing the attributes to update:
- # :first_name - The String first name of the account holder.
- # :last_name - The String last name of the account holder.
+ # @api public
#
- # Returns true if the update was successful, or false if it was
- # unsuccessful.
+ # @param [Hash] attributes The attributes to update.
+ # @option attributes [String] :first_name The first name of the account
+ # holder.
+ # @option attributes [String] :last_name The last name of the account
+ # holder.
+ #
+ # @example Update the account holder's name to "John Doe"
+ # account.update_attributes(:first_name => 'John', :last_name => 'Doe')
+ #
+ # @return [true, false] Whether the update succeeded or not.
def update_attributes(attributes)
- self.first_name = attributes[:first_name] if attributes[:first_name]
- self.last_name = attributes[:last_name] if attributes[:last_name]
+ @first_name = attributes[:first_name] if attributes[:first_name]
+ @last_name = attributes[:last_name] if attributes[:last_name]
response = put("/2.0/accounts/#{self.id}", attributes)
response['success']
end
- # Internal: Create the account on Context.IO.
+ # Create the account on Context.IO
+ #
+ # @api private
#
# This will only send the first email address in the email_addresses
- # attribute, as well as the first and last name if they are specified.
+ # attribute (which is required) as well as the first and last name if they
+ # are not-falsey.
#
- # Returns true if the creation was successful, or false if it was
- # unsuccessful.
+ # @return [true, false] Whether the creation succeeded or not.
def create_record
unless self.email_addresses && self.email_addresses.first
raise ArgumentError.new('You must specify an email address')
@@ -169,19 +188,20 @@ def create_record
attributes[:last_name] = self.last_name if self.last_name
response = post('/2.0/accounts', attributes)
- self.id = response['id']
+ @id = response['id']
@saved = response['success']
end
private :create_record
- # Internal: Update the account on Context.IO.
+ # Update the account on Context.IO
+ #
+ # Only sends the first and last name, as they are the only attributes the
+ # Context.IO API allows you to update.
#
- # This will only send the first and last name, as they are the only
- # attributes the API allows you to update.
+ # @api private
#
- # Returns true if the creation was successful, or false if it was
- # unsuccessful.
+ # @return [true, false] Whether the update succeeded or not.
def update_record
attributes = {}
attributes[:first_name] = self.first_name if self.first_name
@@ -192,37 +212,40 @@ def update_record
end
private :update_record
- # Internal: Create an Account instance from the JSON returned by the
- # Context.IO server.
+ # Create an Account instance from the JSON returned by the Context.IO server
#
- # json - The parsed JSON returned by the Context.IO server. See their
- # documentation for what keys are possible.
+ # @api private
#
- # Returns a ContextIO::Account instance.
+ # @param [Hash] json The parsed JSON object returned by a Context.IO API
+ # request. See their documentation for what keys are possible.
+ #
+ # @return [Account] An account with the given attributes.
def self.from_json(json)
account = new
- account.id = json['id']
- account.username = json['username']
- if json['created'] == 0
- account.created = nil
- else
- account.created = Time.at(json['created'])
- end
- if json['suspended'] == 0
- account.suspended = nil
- else
- account.suspended = Time.at(json['suspended'])
- end
- account.email_addresses = json['email_addresses']
- account.first_name = json['first_name']
- account.last_name = json['last_name']
- if json['password_expired'] == 0
- account.password_expired = nil
- else
- account.password_expired = json['password_expired']
- end
- account.sources = json['sources'].map do |source|
- Source.from_json(source)
+ account.instance_eval do
+ @id = json['id']
+ @username = json['username']
+ if json['created'] == 0
+ @created = nil
+ else
+ @created = Time.at(json['created'])
+ end
+ if json['suspended'] == 0
+ @suspended = nil
+ else
+ @suspended = Time.at(json['suspended'])
+ end
+ @email_addresses = json['email_addresses']
+ @first_name = json['first_name']
+ @last_name = json['last_name']
+ if json['password_expired'] == 0
+ @password_expired = nil
+ else
+ @password_expired = json['password_expired']
+ end
+ @sources = json['sources'].map do |source|
+ Source.from_json(source)
+ end
end
account
View
11 lib/context-io/authentication.rb
@@ -1,7 +1,11 @@
+# encoding: utf-8
+
module ContextIO
- # Internal: Methods related to authentication and configuration.
+ # Methods related to authentication and configuration.
+ #
+ # @api private
module Authentication
- # Internal: Returns the authentication Hash given to SimpleOAuth.
+ # @return [Hash] The authentication details for OAuth.
def authentication
{
:consumer_key => consumer_key,
@@ -11,8 +15,7 @@ def authentication
}
end
- # Internal: Returns a Boolean specifying whether authentication details
- # have been set up or not.
+ # @return [Boolean] Whether authentication details are configured or not.
def authenticated?
authentication[:consumer_key] and authentication[:consumer_secret]
end
View
54 lib/context-io/config.rb
@@ -1,7 +1,13 @@
require 'context-io/version'
module ContextIO
- # Public: Defines constants and methods related to configuration
+ # Defines constants and methods related to configuration
+ #
+ # You shouldn't interact with this module directly, as it's included in the
+ # {ContextIO} module. Mostly you'll use the {#configure} method on
+ # {ContextIO}, see the example on {#configure}.
+ #
+ # @see #configure
module Config
# The HTTP connection adapter that will be used to connect if none is set
DEFAULT_ADAPTER = :net_http
@@ -21,6 +27,7 @@ module Config
# The value of sent in the 'User-Agent' header if none is set
DEFAULT_USER_AGENT = "context-io ruby gem #{ContextIO::VERSION}"
+ # The configuration options that are settable.
VALID_OPTIONS_KEYS = [
:adapter,
:connection_options,
@@ -30,17 +37,60 @@ module Config
:user_agent
]
- attr_accessor *VALID_OPTIONS_KEYS
+ # @return [Symbol] The HTTP connection adapter. Check the Faraday
+ # documentation for possible adapters.
+ attr_accessor :adapter
+ # @return [Hash] Connection options passed to the Faraday connection object.
+ attr_accessor :connection_options
+
+ # @return [String] The OAuth consumer key received from Context.IO.
+ attr_accessor :consumer_key
+
+ # @return [String] The OAuth consumer secret received from Context.IO.
+ attr_accessor :consumer_secret
+
+ # @return [String, URI] The URI to the HTTP proxy to use.
+ attr_accessor :proxy
+
+ # @return [String] The value to be sent in the User-Agent header. Probably
+ # doesn't need to be changed unless you're writing a big app, or another
+ # library based on this one.
+ attr_accessor :user_agent
+
+ # Makes sure the default values are always set
+ #
+ # @api private
def self.extended(base)
base.reset
end
+ # Configure with a block
+ #
+ # @api public
+ #
+ # @example Configuring OAuth
+ # ContextIO.configure do |config|
+ # config.consumer_key = 'my_consumer_key'
+ # config.consumer_secret = 'my_consumer_secret'
+ # end
+ #
+ # @return [self]
def configure
yield self
self
end
+ # Reset the configuration to the default values
+ #
+ # @api public
+ #
+ # @example Reset the configuration
+ # ContextIO.adapter = :some_erroneous_thing
+ # ContextIO.reset
+ # ContextIO.adapter # => DEFAULT_ADAPTER
+ #
+ # @return [void]
def reset
self.adapter = DEFAULT_ADAPTER
self.connection_options = DEFAULT_CONNECTION_OPTIONS
View
16 lib/context-io/connection.rb
@@ -6,14 +6,17 @@
require 'context-io/response/raise_server_error'
module ContextIO
- # Internal: Methods for creating a connection to the API server.
+ # Methods for creating a connection to the API server.
+ #
+ # @api private
+ # @private
module Connection
- private
-
- # Internal: Create a Faraday connection object that's set up with the
- # correct configuration.
+ # Create and configure a Faraday connection
+ #
+ # @api private
#
- # Returns a Faraday::Connection object
+ # @return [Faraday::Connection] A Connection object that's correctly
+ # configured.
def connection
default_options = {
:headers => {
@@ -33,6 +36,7 @@ def connection
builder.adapter(ContextIO.adapter)
end
end
+ private :connection
end
end
View
18 lib/context-io/core_ext/hash.rb
@@ -1,9 +1,21 @@
+# Hash extensions
+#
+# This is borrowed from ActiveSupport. We don't want the entire ActiveSupport
+# library (it's huge), so we'll just add this method.
class Hash
- # Public: Merges self with another Hash, recursively.
+ # Merge self with another hash recursively
#
- # hash - The Hash to merge
+ # @api public
#
- # Returns self merged recursively with the passed Hash.
+ # @param [Hash] hash The hash to merge into this one.
+ #
+ # @example Merge two hashes with some common keys
+ # a_hash = { :foo => :bar, :baz => { :foobar => "hey" }}
+ # another_hash = { :foo => :foobar, :baz => { :foo => :bar }}
+ # a_hash.deep_merge(another_hash)
+ # # => { :foo => :foobar, :baz => { :foobar => "hey", :foo => :bar }}
+ #
+ # @return [Hash] The given hash merged recursively into this one.
def deep_merge(hash)
target = self.dup
hash.keys.each do |key|
View
17 lib/context-io/error.rb
@@ -1,15 +1,20 @@
+# encoding: utf-8
+
module ContextIO
- # Public: Custom error class for rescuing from all ContextIO errors
+ # Base class for ContextIO exceptions.
+ #
+ # @api public
class Error < StandardError
- # Public: The HTTP headers in the response.
+ # @return [Hash{String => String}] The HTTP headers of the response.
attr_reader :http_headers
- # Internal: Initializes a new Error object
+ # Initialize a new ContextIO error
#
- # message - The String message.
- # http_headers - A Hash containing all the HTTP headers.
+ # @api private
+ # @private
#
- # Returns a ContextIO::Error instance.
+ # @param [String] message The error message.
+ # @param [Hash{String => String}] http_headers The HTTP headers.
def initialize(message, http_headers)
@http_headers = Hash[http_headers]
super(message)
View
4 lib/context-io/error/bad_request.rb
@@ -2,6 +2,10 @@
module ContextIO
# Raised when Context.IO returns the HTTP status code 400
+ #
+ # This usually means that some required info is missing.
+ #
+ # @api public
class Error::BadRequest < ContextIO::Error::ClientError
end
end
View
4 lib/context-io/error/client_error.rb
@@ -1,7 +1,9 @@
require 'context-io/error'
module ContextIO
- # Public: Raised when Context.IO returns a 4xx HTTP status code
+ # Raised when Context.IO returns a 4xx HTTP status code
+ #
+ # @api public
class Error::ClientError < ContextIO::Error
end
end
View
6 lib/context-io/error/forbidden.rb
@@ -1,7 +1,11 @@
require 'context-io/error/client_error'
module ContextIO
- # Public: Raised when ContextIO returns the HTTP status code 403
+ # Raised when ContextIO returns the HTTP status code 403
+ #
+ # This usually means that the resource isn't accessible.
+ #
+ # @api public
class Error::Forbidden < ContextIO::Error::ClientError
end
end
View
2  lib/context-io/error/internal_server_error.rb
@@ -2,6 +2,8 @@
module ContextIO
# Raised when Context.IO returns the HTTP status code 500.
+ #
+ # @api public
class Error::InternalServerError < ContextIO::Error::ServerError
end
end
View
6 lib/context-io/error/not_found.rb
@@ -1,7 +1,11 @@
require 'context-io/error/client_error'
module ContextIO
- # Public: Raised when Context.IO returns the HTTP status code 404
+ # Raised when Context.IO returns the HTTP status code 404
+ #
+ # This means that the resource you tried to get doesn't exist.
+ #
+ # @api public
class Error::NotFound < ContextIO::Error::ClientError
end
end
View
7 lib/context-io/error/payment_required.rb
@@ -1,7 +1,12 @@
require 'context-io/error/client_error'
module ContextIO
- # Public: Raised when Context.IO returns the HTTP status code 402.
+ # Raised when Context.IO returns the HTTP status code 402
+ #
+ # This means that you're trying to do something that your plan isn't allowed
+ # to do (anymore), so you need to log in and upgrade your plan.
+ #
+ # @api public
class Error::PaymentRequired < ContextIO::Error::ClientError
end
end
View
4 lib/context-io/error/server_error.rb
@@ -1,7 +1,9 @@
require 'context-io/error'
module ContextIO
- # Public: Raised when Context.IO returns a 5xx HTTP status code.
+ # Raised when Context.IO returns a 5xx HTTP status code.
+ #
+ # @api public
class Error::ServerError < ContextIO::Error
end
end
View
4 lib/context-io/error/service_unavailable.rb
@@ -1,10 +1,12 @@
require 'context-io/error/server_error'
module ContextIO
- # Public: Raised when Context.IO returns the HTTP status code 503.
+ # Raised when Context.IO returns the HTTP status code 503
#
# The 503 status code means a request required a connection to the mail
# server, but that connection failed.
+ #
+ # @api public
class Error::ServiceUnavailable < ContextIO::Error::ServerError
end
end
View
6 lib/context-io/error/unauthorized.rb
@@ -1,7 +1,11 @@
require 'context-io/error/client_error'
module ContextIO
- # Public: Raised when Context.IO returns the HTTP status code 401
+ # Raised when Context.IO returns the HTTP status code 401
+ #
+ # This means that the OAuth signature can't be validated.
+ #
+ # @api public
class Error::Unauthorized < ContextIO::Error::ClientError
end
end
View
55 lib/context-io/request.rb
@@ -1,60 +1,57 @@
module ContextIO
- # Internal: Defines HTTP request methods.
+ # Methods for sending HTTP requests
+ #
+ # @api private
module Request
- # Internal: Perform an HTTP DELETE request.
+ # Perform an HTTP DELETE request
#
- # path - The String path for the request.
- # params - A Hash of params to put in the query part of the URL. (default:
- # {})
+ # @param [String] path The path to request.
+ # @param [Hash] params Parameters to put in the query part of the URL
#
- # Returns the parsed JSON body
+ # @return [Hash, Array, Object] The parsed JSON response.
def delete(path, params={})
request(:delete, path, params)
end
- # Internal: Perform an HTTP GET request.
+ # Perform an HTTP GET request
#
- # path - The String path for the request.
- # params - A Hash of params to put in the query part of the URL. (default:
- # {})
+ # @param [String] path The path to request.
+ # @param [Hash] params The parameters to put in the query part of the URL.
#
- # Returns the parsed JSON body.
+ # @return [Hash, Array, Object] The parsed JSON response.
def get(path, params={})
request(:get, path, params)
end
- # Internal: Perform an HTTP POST request.
+ # Perform an HTTP POST request
#
- # path - The String path for the request.
- # params - A Hash of params to put in the body of the request. (default:
- # {})
+ # @param [String] path The path to request.
+ # @param [Hash] params The parameters to put in the body of the request.
#
- # Returns the parsed JSON response body.
+ # @return [Hash, Array, Object] The parsed JSON response.
def post(path, params={})
request(:post, path, params)
end
- # Internal: Perform an HTTP PUT request.
+ # Perform an HTTP PUT request
#
- # path - The String path for the request
- # params - A Hash of params to put in the body of the request. (default:
- # {})
+ # @param [String] path The path to request.
+ # @param [Hash] The parameters to put in the body of the request.
#
- # Returns the parsed JSON response body.
+ # @return [Hash, Array, Object] The parsed JSON response.
def put(path, params={})
request(:put, path, params)
end
- # Internal: Perform an HTTP request.
+ # Perform an HTTP request
#
- # method - The HTTP method to send as a Symbol (supports :delete, :get,
- # :put and :post).
- # path - The String path for the request.
- # params - A Hash of params to put in the query part of the URL (for
- # DELETE and GET requests) or in the body of the request (for
- # POST and PUT requests).
+ # @param [:delete, :get, :put, :post] method The HTTP method to send.
+ # @param [String] path The path to request.
+ # @param [Hash] The parameters to put in the query part of the URL (for
+ # DELETE and GET requests) or in the body of the request (for POST and PUT
+ # requests).
#
- # Returns the parsed JSON response body.
+ # @return [Hash, Array, Object] The parsed JSON response.
def request(method, path, params)
response = connection.send(method) do |request|
case method.to_sym
View
29 lib/context-io/request/oauth.rb
@@ -3,14 +3,15 @@
module ContextIO
module Request
- # Internal: Faraday middleware for handling the OAuth header.
+ # Faraday middleware for handling the OAuth header
+ #
+ # @api private
class ContextIOOAuth < Faraday::Middleware
- # Internal: Add the OAuth header before passing the request on to the next
- # middleware.
+ # Add the OAuth header
#
- # env - The Rack environment.
+ # @param [Hash] env The Rack environment
#
- # Returns the Rack response from the middleware or app after this.
+ # @return [Array] The Rack response
def call(env)
params = env[:body] || {}
signature_params = params
@@ -23,15 +24,17 @@ def call(env)
@app.call(env)
end
- # Public: Initialize the OAuth middleware.
+ # Initialize the OAuth middleware
#
- # app - The Rack app or middleware to call after this one.
- # options - The Hash authentication options to be used for OAuth
- # authentication:
- # :consumer_key - The String OAuth consumer key
- # :consumer_secret - The String OAuth consumer secret
- # :token - Should be nil
- # :token_secret - Should be nil
+ # @param [#call] The next Rack middleware of app to call.
+ # @param [Hash] options The authentication options to use for OAuth
+ # authentication.
+ # @option options [String] :consumer_key The OAuth consumer key
+ # @option options [String] :consumer_secret The OAuth consumer secret
+ # @option options [nil] :token The OAuth token, should be nil since
+ # Context.IO doesn't support three-legged authentication.
+ # @option options [nil] :token_secret The Oauth token secret, should be
+ # nil since Context.IO doesn't support three-legged authentication.
def initialize(app, options)
@app, @options = app, options
end
View
5 lib/context-io/resource.rb
@@ -2,10 +2,9 @@
require 'context-io/request'
module ContextIO
- # Internal: The superclass of all classes that are a resource provided by the
- # API.
+ # The superclass of all resources provided by the API
#
- # This contains internal methods related to querying the API.
+ # @api private
class Resource
include ContextIO::Connection
include ContextIO::Request
View
5 lib/context-io/response.rb
@@ -0,0 +1,5 @@
+module ContextIO
+ # Namespace for response
+ module Response
+ end
+end
View
10 lib/context-io/response/parse_json.rb
@@ -3,13 +3,15 @@
module ContextIO
module Response
- # Internal: Faraday middleware for parsing JSON in the response.
+ # Faraday middleware for parsing JSON in the response body
+ #
+ # @api private
class ParseJson < Faraday::Response::Middleware
- # Internal: Parse the body into JSON.
+ # Parse the response body into JSON
#
- # body - The String-like body containing JSON data.
+ # @param [#to_s] The response body, containing JSON data.
#
- # Returns the parsed JSON data, probably an Array or a Hash.
+ # @return [Object] The parsed JSON data, probably an Array or a Hash.
def parse(body)
case body
when ''
View
28 lib/context-io/response/raise_client_error.rb
@@ -7,15 +7,26 @@
module ContextIO
module Response
- # Internal: Faraday middleware for raising errors when the server returns
- # a 4xx HTTP status code.
+ # Faraday middleware for raising errors on 4xx HTTP status codes
+ #
+ # @api private
class RaiseClientError < Faraday::Response::Middleware
- # Internal: Check the status code and raise an error if there's a 4xx
- # status code.
+ # Raise an error if the response has a 4xx status code
#
- # Raises a ContextIO::Error if the status code is a 4xx code.
+ # @raise [ContextIO::Error::ClientError] If the response has a 4xx status
+ # code.
+ # @raise [ContextIO::Error::BadRequest] If the response has a 400 status
+ # code.
+ # @raise [ContextIO::Error::Unauthorized] If the response has a 401 status
+ # code.
+ # @raise [ContextIO::Error::PaymentRequired] If the response has a 402
+ # status code.
+ # @raise [ContextIO::Error::Forbidden] If the response has a 403 status
+ # code.
+ # @raise [ContextIO::Error::NotFound] If the response has a 404 status
+ # code.
#
- # Returns nothing.
+ # @return [void]
def on_complete(env)
case env[:status].to_i
when 400
@@ -33,9 +44,8 @@ def on_complete(env)
private
- # Internal: Return the error message if one is defined in the body.
- #
- # Returns the String error message (or an empty String).
+ # @return [String] The error message if one is defines, or an empty
+ # string.
def error_body(body)
if body['type'] == 'error' && body['value']
body['value']
View
15 lib/context-io/response/raise_server_error.rb
@@ -4,9 +4,20 @@
module ContextIO
module Response
- # Internal: Faraday middleware that raises errors when server returns
- # 5xx status codes.
+ # Faraday middleware for raising errors on 5xx status codes
+ #
+ # @api private
class RaiseServerError < Faraday::Response::Middleware
+ # Raise an error if the response has a 5xx status code
+ #
+ # @raise [ContextIO::Error::ServerError] If the response has a 5xx status
+ # code.
+ # @raise [ContextIO::Error::InternalServerError] If the response has a 500
+ # status code.
+ # @raise [ContextIO::Error::ServiceUnavailable] If the response has a 503
+ # status code.
+ #
+ # @return [void]
def on_complete(env)
case env[:status].to_i
when 500
View
15 lib/context-io/source.rb
@@ -1,15 +1,18 @@
require 'context-io/resource'
module ContextIO
- # Public: A source. Create one of these for each mailbox a user has.
+ # A message source. Create one of these for each mailbox a user has
+ #
+ # @api public
class Source < ContextIO::Resource
- # Internal: Create a Source instance from the JSON returned by the
- # Context.IO server.
+ # Create a Source instance from the JSON returned by the Context.IO server
#
- # json - A Hash containing the parsed JSON returned by the Context.IO
- # server. See their documentation for possible keys.
+ # @api private
#
- # Returns a ContextIO::Source instance.
+ # @param [Hash] The parsed JSON object returned by a Context.IO API request.
+ # See their documentation for what keys are possible.
+ #
+ # @return [Source] A source with the given attributes.
def self.from_json(json)
source = new
# TODO: Add the necessary keys.
View
4 lib/context-io/version.rb
@@ -1,5 +1,7 @@
module ContextIO
- # Public: The ContextIO version. Follows Semantic Versioning.
+ # The ContextIO version. Follows Semantic Versioning.
+ #
+ # @see http://semver.org
VERSION = '0.0.0'
end
View
29 spec/account_spec.rb
@@ -1,6 +1,19 @@
require 'spec_helper'
describe ContextIO::Account do
+ let(:existing_account) do
+ stub_request(:post, 'https://api.context.io/2.0/accounts').
+ to_return(
+ :body => '{
+ "success": true,
+ "id": "1234567890abcdef",
+ "resource_url": "https://api.context.io/2.0/accounts/1234567890abcdef"
+ }')
+ account = ContextIO::Account.new(:email => 'foo@bar.com')
+ account.save
+
+ account
+ end
describe '.all' do
before(:each) do
json_accs = File.read(File.expand_path(File.join(File.dirname(__FILE__), "fixtures", "accounts.json")))
@@ -98,12 +111,7 @@
end
describe '#save' do
- let(:existing_record) do
- account = ContextIO::Account.new(:email => 'foo@bar.com')
- account.id = '1234567890abcdef' # We don't want to test #save here...
- account
- end
it 'returns true if the save was successful' do
@stub = stub_request(:post, 'https://api.context.io/2.0/accounts').
@@ -172,8 +180,8 @@
}'
)
- existing_record.first_name = 'John'
- existing_record.save
+ existing_account.first_name = 'John'
+ existing_account.save
@stub.should have_been_requested
end
@@ -181,13 +189,6 @@
end
describe '#update_attributes' do
- let(:existing_account) do
- account = ContextIO::Account.new(:email => 'foo@bar.com')
- account.id = '1234567890abcdef' # Pretend we're an "old" account
-
- account
- end
-
it 'calls the API request' do
@stub = stub_request(:put,
'https://api.context.io/2.0/accounts/1234567890abcdef').
Please sign in to comment.
Something went wrong with that request. Please try again.