Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fill out documentation

  • Loading branch information...
commit e7ed9f7830fa1ba683b310c416081a3f7077f69e 1 parent eb11b0d
@sferik sferik authored
Showing with 114 additions and 45 deletions.
  1. +1 −0  .yardopts
  2. +2 −1  lib/faraday/multipart.rb
  3. +2 −1  lib/faraday/oauth.rb
  4. +2 −1  lib/faraday/raise_http_4xx.rb
  5. +2 −1  lib/faraday/raise_http_5xx.rb
  6. +1 −1  lib/twitter/api.rb
  7. +1 −1  lib/twitter/authentication.rb
  8. +2 −1  lib/twitter/base.rb
  9. +4 −0 lib/twitter/client.rb
  10. +1 −0  lib/twitter/client/account.rb
  11. +2 −0  lib/twitter/client/block.rb
  12. +1 −0  lib/twitter/client/direct_messages.rb
  13. +1 −0  lib/twitter/client/favorites.rb
  14. +1 −0  lib/twitter/client/friends_and_followers.rb
  15. +1 −0  lib/twitter/client/friendship.rb
  16. +1 −0  lib/twitter/client/geo.rb
  17. +1 −0  lib/twitter/client/legal.rb
  18. +3 −0  lib/twitter/client/list.rb
  19. +3 −0  lib/twitter/client/list_members.rb
  20. +3 −0  lib/twitter/client/list_subscribers.rb
  21. +2 −0  lib/twitter/client/local_trends.rb
  22. +1 −0  lib/twitter/client/notification.rb
  23. +1 −0  lib/twitter/client/saved_searches.rb
  24. +2 −0  lib/twitter/client/spam_reporting.rb
  25. +1 −0  lib/twitter/client/timeline.rb
  26. +2 −0  lib/twitter/client/trends.rb
  27. +1 −0  lib/twitter/client/tweets.rb
  28. +1 −0  lib/twitter/client/user.rb
  29. +1 −1  lib/twitter/client/utils.rb
  30. +55 −25 lib/twitter/configuration.rb
  31. +1 −1  lib/twitter/connection.rb
  32. +9 −9 lib/twitter/error.rb
  33. +1 −1  lib/twitter/request.rb
  34. +1 −1  lib/twitter/search.rb
View
1  .yardopts
@@ -1,3 +1,4 @@
+--no-private
--protected
--tag format:"Supported formats"
--tag authenticated:"Requires Authentication"
View
3  lib/faraday/multipart.rb
@@ -1,7 +1,8 @@
require 'faraday'
-# @api private
+# @private
module Faraday
+ # @private
class Request::Multipart < Faraday::Middleware
def call(env)
if env[:body].is_a?(Hash)
View
3  lib/faraday/oauth.rb
@@ -1,8 +1,9 @@
require 'faraday'
require 'simple_oauth'
-# @api private
+# @private
module Faraday
+ # @private
class Request::OAuth < Faraday::Middleware
def call(env)
params = env[:body].is_a?(Hash) ? env[:body] : {}
View
3  lib/faraday/raise_http_4xx.rb
@@ -1,7 +1,8 @@
require 'faraday'
-# @api private
+# @private
module Faraday
+ # @private
class Response::RaiseHttp4xx < Response::Middleware
def self.register_on_complete(env)
env[:response].on_complete do |response|
View
3  lib/faraday/raise_http_5xx.rb
@@ -1,7 +1,8 @@
require 'faraday'
-# @api private
+# @private
module Faraday
+ # @private
class Response::RaiseHttp5xx < Response::Middleware
def self.register_on_complete(env)
env[:response].on_complete do |response|
View
2  lib/twitter/api.rb
@@ -3,7 +3,7 @@
require File.expand_path('../authentication', __FILE__)
module Twitter
- # @api private
+ # @private
class API
attr_accessor *Configuration::VALID_OPTIONS_KEYS
View
2  lib/twitter/authentication.rb
@@ -1,5 +1,5 @@
module Twitter
- # @api private
+ # @private
module Authentication
private
View
3  lib/twitter/base.rb
@@ -1,8 +1,9 @@
module Twitter
+ # @deprecated {Twitter::Base} is deprecated and will be permanently removed in the next major version. Please use {Twitter::Client} instead.
class Base
# Alias for Twitter::Client.new
#
- # @deprecated {Twitter::Base#client} is deprecated and will be permanently removed in the next major version. Please use Twitter::Client.new instead.
+ # @deprecated {Twitter::Base} is deprecated and will be permanently removed in the next major version. Please use {Twitter::Client} instead.
# @return [Twitter::Client]
def client(options={})
Twitter::Client.new(options)
View
4 lib/twitter/client.rb
@@ -1,4 +1,8 @@
module Twitter
+ # Wrapper for the Twitter REST API
+ #
+ # @note All methods have been separated into modules and follow the same grouping used in {http://dev.twitter.com/doc the Twitter API Documentation}.
+ # @see http://dev.twitter.com/pages/every_developer
class Client < API
# Require client method modules after initializing the Client class in
# order to avoid a superclass mismatch error, allowing those modules to be
View
1  lib/twitter/client/account.rb
@@ -1,5 +1,6 @@
module Twitter
class Client
+ # Defines methods related to a user's account
module Account
# Returns the requesting user if authentication was successful, otherwise raises {Twitter::Unauthorized}
#
View
2  lib/twitter/client/block.rb
@@ -1,5 +1,7 @@
module Twitter
class Client
+ # Defines methods related to blocking and unblocking users
+ # @see Twitter::Client::SpamReporting
module Block
# Blocks the user specified by the authenticating user
#
View
1  lib/twitter/client/direct_messages.rb
@@ -1,5 +1,6 @@
module Twitter
class Client
+ # Defines methods related to direct messages
module DirectMessages
# Returns the 20 most recent direct messages sent to the authenticating user
#
View
1  lib/twitter/client/favorites.rb
@@ -1,5 +1,6 @@
module Twitter
class Client
+ # Defines methods related to favorites (or favourites)
module Favorites
# @overload favorites(options={})
# Returns the 20 most recent favorite statuses for the authenticating user
View
1  lib/twitter/client/friends_and_followers.rb
@@ -1,5 +1,6 @@
module Twitter
class Client
+ # Defines methods related to friends and followers
module FriendsAndFollowers
# @todo Move the code that makes the parsed XML consistent with the parsed JSON into MultiXML.
# @overload friend_ids(options={})
View
1  lib/twitter/client/friendship.rb
@@ -1,5 +1,6 @@
module Twitter
class Client
+ # Defines methods related to friendship
module Friendship
# Allows the authenticating user to follow the specified user
#
View
1  lib/twitter/client/geo.rb
@@ -1,5 +1,6 @@
module Twitter
class Client
+ # Defines methods related to geography
# @see http://dev.twitter.com/pages/geo_dev_guidelines Twitter Geo Developer Guidelines
module Geo
# Search for places that can be attached to a {Twitter::Client::Tweets#update}
View
1  lib/twitter/client/legal.rb
@@ -1,5 +1,6 @@
module Twitter
class Client
+ # Defines methods related to legal documents
module Legal
# Returns {http://twitter.com/tos Twitter's Terms of Service}
#
View
3  lib/twitter/client/list.rb
@@ -1,5 +1,8 @@
module Twitter
class Client
+ # Defines methods related to lists
+ # @see Twitter::Client::ListMembers
+ # @see Twitter::Client::ListSubscribers
module List
# Creates a new list for the authenticated user
#
View
3  lib/twitter/client/list_members.rb
@@ -1,5 +1,8 @@
module Twitter
class Client
+ # Defines methods related to list members
+ # @see Twitter::Client::List
+ # @see Twitter::Client::ListSubscribers
module ListMembers
# Returns the members of the specified list
#
View
3  lib/twitter/client/list_subscribers.rb
@@ -1,5 +1,8 @@
module Twitter
class Client
+ # Defines methods related to list subscribers
+ # @see Twitter::Client::List
+ # @see Twitter::Client::ListMembers
module ListSubscribers
# Returns the subscribers of the specified list
#
View
2  lib/twitter/client/local_trends.rb
@@ -1,5 +1,7 @@
module Twitter
class Client
+ # Defines methods related to local trends
+ # @see Twitter::Client::Trends
module LocalTrends
# Returns the locations that Twitter has trending topic information for
#
View
1  lib/twitter/client/notification.rb
@@ -1,5 +1,6 @@
module Twitter
class Client
+ # Defines methods related to notification
module Notification
# Enables device notifications for updates from the specified user to the authenticating user
#
View
1  lib/twitter/client/saved_searches.rb
@@ -1,5 +1,6 @@
module Twitter
class Client
+ # Defines methods related to saved searches
module SavedSearches
# Returns the authenticated user's saved search queries
#
View
2  lib/twitter/client/spam_reporting.rb
@@ -1,5 +1,7 @@
module Twitter
class Client
+ # Defines methods related to spam reporting
+ # @see Twitter::Client::Block
module SpamReporting
# The user specified is blocked by the authenticated user and reported as a spammer
#
View
1  lib/twitter/client/timeline.rb
@@ -1,5 +1,6 @@
module Twitter
class Client
+ # Defines methods related to timelines
module Timeline
# Returns the 20 most recent statuses, including retweets if they exist, from non-protected users
#
View
2  lib/twitter/client/trends.rb
@@ -1,5 +1,7 @@
module Twitter
class Client
+ # Defines methods related to global trends
+ # @see Twitter::Client::LocalTrends
module Trends
# Returns the top ten topics that are currently trending on Twitter
#
View
1  lib/twitter/client/tweets.rb
@@ -1,5 +1,6 @@
module Twitter
class Client
+ # Defines methods related to tweets
module Tweets
# Returns a single status, specified by ID
#
View
1  lib/twitter/client/user.rb
@@ -1,5 +1,6 @@
module Twitter
class Client
+ # Defines methods related to users
module User
# Returns extended information of a given user
#
View
2  lib/twitter/client/utils.rb
@@ -1,7 +1,7 @@
# -*- encoding: utf-8 -*-
module Twitter
class Client
- # @api private
+ # @private
module Utils
private
View
80 lib/twitter/configuration.rb
@@ -2,47 +2,77 @@
require File.expand_path('../version', __FILE__)
module Twitter
+ # Defines constants and methods related to configuration
module Configuration
- # Valid keys in the options hash when configuring a {Twitter::API}
- VALID_OPTIONS_KEYS = [:consumer_key, :consumer_secret, :oauth_token, :oauth_token_secret, :adapter, :endpoint, :format, :proxy, :search_endpoint, :user_agent].freeze
- # Valid Twitter request/response formats
+ # An array of valid keys in the options hash when configuring a {Twitter::API}
+ VALID_OPTIONS_KEYS = [:consumer_key, :consumer_secret, :oauth_token, :oauth_token_secret, :adapter, :endpoint, :format, :proxy, :search_endpoint, :user_agent].freeze
+
+ # An array of valid request/response formats
#
- # @note Not all methods support all formats
- VALID_FORMATS = [:json, :xml].freeze
-
- # The consumer key set in {Twitter::Authentication}, unless overridden
- DEFAULT_CONSUMER_KEY = nil.freeze
- # The consumer secret set in {Twitter::Authentication}, unless overridden
- DEFAULT_CONSUMER_SECRET = nil.freeze
- # The OAuth token set in {Twitter::Authentication}, unless overridden
- DEFAULT_OAUTH_TOKEN = nil.freeze
- # The OAuth token secret set in {Twitter::Authentication}, unless overridden
+ # @note Not all methods support the XML format.
+ VALID_FORMATS = [:json, :xml].freeze
+
+ # By default, don't set an application key
+ DEFAULT_CONSUMER_KEY = nil.freeze
+
+ # By default, don't set an application secret
+ DEFAULT_CONSUMER_SECRET = nil.freeze
+
+ # By default, don't set a user oauth token
+ DEFAULT_OAUTH_TOKEN = nil.freeze
+
+ # By default, don't set a user oauth secret
DEFAULT_OAUTH_TOKEN_SECRET = nil.freeze
- # The Faraday adapter set in {Twitter::Connection}, unless overridden
- DEFAULT_ADAPTER = Faraday.default_adapter.freeze
- # The Twitter REST API endpoint set in {Twitter::Connection}, unless overridden
- DEFAULT_ENDPOINT = 'https://api.twitter.com/1/'.freeze
- # The Twitter Search API endpoint set in {Twitter::Connection}, unless overridden
- DEFAULT_SEARCH_ENDPOINT = 'https://search.twitter.com/'.freeze
- # The response format appended to the path in {Twitter::Request} and sent in the Accept header in {Twitter::Connection}, unless overridden
- DEFAULT_FORMAT = :json.freeze
- # The proxy server set in {Twitter::Connection}, unless overridden
- DEFAULT_PROXY = nil.freeze
- # The user agent set in {Twitter::Connection}, unless overridden
+
+ # The faraday adapter that will be used to connect if none is set
+ #
+ # @note The default faraday adapter is Net::HTTP.
+ DEFAULT_ADAPTER = Faraday.default_adapter.freeze
+
+ # The endpoint that will be used to connect if none is set
+ #
+ # @note This is configurable in case you want to use HTTP instead of HTTPS, specify a different API version, or use a Twitter-compatible endpoint.
+ # @see http://status.net/wiki/Twitter-compatible_API
+ # @see http://en.blog.wordpress.com/2009/12/12/twitter-api/
+ # @see http://staff.tumblr.com/post/287703110/api
+ # @see http://developer.typepad.com/typepad-twitter-api/twitter-api.html
+ DEFAULT_ENDPOINT = 'https://api.twitter.com/1/'.freeze
+
+ # The search endpoint that will be used to connect if none is set
+ #
+ # @note This is configurable in case you want to use HTTP instead of HTTPS or use a Twitter-compatible endpoint.
+ # @see http://status.net/wiki/Twitter-compatible_API
+ DEFAULT_SEARCH_ENDPOINT = 'https://search.twitter.com/'.freeze
+
+ # The response format appended to the path and sent in the 'Accept' header if none is set
+ #
+ # @note JSON is preferred over XML because it is more concise and faster to parse.
+ DEFAULT_FORMAT = :json.freeze
+
+ # By default, don't use a proxy server
+ DEFAULT_PROXY = nil.freeze
+
+ # The user agent that will be sent to the API endpoint if none is set
DEFAULT_USER_AGENT = "Twitter Ruby Gem #{Twitter::VERSION}".freeze
+ # @private
attr_accessor *VALID_OPTIONS_KEYS
+ # When this module is extended, set all configuration options to their default values
def self.extended(base)
base.reset
end
+ # Convenience method to allow configuration options to be set in a block
def configure
yield self
end
+ # Create a hash of options and their values
def options
- VALID_OPTIONS_KEYS.inject({}){|o, k| o.merge!(k => send(k))}
+ VALID_OPTIONS_KEYS.inject({}) do |option, key|
+ option.merge!(key => send(key))
+ end
end
# Reset all configuration options to defaults
View
2  lib/twitter/connection.rb
@@ -2,7 +2,7 @@
Dir[File.expand_path('../../faraday/*.rb', __FILE__)].each{|f| require f}
module Twitter
- # @api private
+ # @private
module Connection
private
View
18 lib/twitter/error.rb
@@ -2,22 +2,22 @@ module Twitter
# Custom error class for rescuing from all Twitter errors
class Error < StandardError; end
- # Raised when Twitter returns a 400 HTTP status code
+ # Raised when Twitter returns the HTTP status code 400
class BadRequest < Error; end
- # Raised when Twitter returns a 401 HTTP status code
+ # Raised when Twitter returns the HTTP status code 401
class Unauthorized < Error; end
- # Raised when Twitter returns a 403 HTTP status code
+ # Raised when Twitter returns the HTTP status code 403
class Forbidden < Error; end
- # Raised when Twitter returns a 404 HTTP status code
+ # Raised when Twitter returns the HTTP status code 404
class NotFound < Error; end
- # Raised when Twitter returns a 406 HTTP status code
+ # Raised when Twitter returns the HTTP status code 406
class NotAcceptable < Error; end
- # Raised when Twitter returns a 420 HTTP status code
+ # Raised when Twitter returns the HTTP status code 420
class EnhanceYourCalm < Error
# Creates a new EnhanceYourCalm error
def initialize(message, http_headers)
@@ -33,12 +33,12 @@ def retry_after
end
end
- # Raised when Twitter returns a 500 HTTP status code
+ # Raised when Twitter returns the HTTP status code 500
class InternalServerError < Error; end
- # Raised when Twitter returns a 502 HTTP status code
+ # Raised when Twitter returns the HTTP status code 502
class BadGateway < Error; end
- # Raised when Twitter returns a 503 HTTP status code
+ # Raised when Twitter returns the HTTP status code 503
class ServiceUnavailable < Error; end
end
View
2  lib/twitter/request.rb
@@ -1,5 +1,5 @@
module Twitter
- # @api private
+ # Defines HTTP request methods
module Request
# Perform an HTTP GET request
def get(path, options={}, raw=false)
View
2  lib/twitter/search.rb
@@ -16,7 +16,7 @@ module Twitter
# {Twitter::Client::User#user} to get the correct user id if necessary.
# @see http://dev.twitter.com/doc/get/search Twitter Search API Documentation
class Search < API
- # @api private
+ # @private
attr_reader :query
# Creates a new search
Please sign in to comment.
Something went wrong with that request. Please try again.