Permalink
Browse files

Added more YARD documentation in OAuth.

  • Loading branch information...
1 parent 1117095 commit 63cfd87d6b96d5c01123a587876015e2507af1b0 @arsduo committed Nov 20, 2011
Showing with 98 additions and 26 deletions.
  1. +3 −0 .yardopts
  2. +4 −1 lib/koala.rb
  3. +24 −15 lib/koala/api.rb
  4. +4 −1 lib/koala/api/legacy.rb
  5. +63 −9 lib/koala/oauth.rb
View
@@ -0,0 +1,3 @@
+--readme readme.md
+--title "Koala Documentation"
+--no-private
View
@@ -15,8 +15,11 @@
require 'koala/utils'
require 'koala/version'
-# @author Alex Koppel
module Koala
+ # Ruby client library for the Facebook Platform.
+ # http://github.com/arsduo/koala
+ # Copyright 2010-2011 Alex Koppel
+
class KoalaError < StandardError; end
# Making HTTP requests
View
@@ -1,16 +1,12 @@
+# graph_batch_api and legacy are required at the bottom, since they depend on API being defined
require 'koala/api/graph_api'
require 'koala/api/rest_api'
-# graph_batch_api and legacy are required at the bottom, since they depend on API being defined
module Koala
module Facebook
- # Ruby client library for the Facebook Platform.
- # Copyright 2010-2011 Alex Koppel
- # Contributors: Alex Koppel, Chris Baclig, Rafi Jacoby, and the team at Context Optional
- # http://github.com/arsduo/koala
class API
- # Initializes a new API client.
+ # Creates a new API client.
# @param [String] access_token access token
# @note If no access token is provided, you can only access some public information.
# @return [Koala::Facebook::API] the API client
@@ -25,20 +21,26 @@ def initialize(access_token = nil)
# Makes a request to the appropriate Facebook API.
# @note You'll rarely need to call this method directly.
+ #
# @see GraphAPIMethods#graph_call
# @see RestAPIMethods#rest_call
- # @param [String] path the server path for this request (leading / is prepended if not present)
- # @param [Hash] args arguments to be sent to Facebook for this request
- # @param [String] verb the HTTP method to use
- # @param [Hash] options request-related options for Koala and Faraday
+ #
+ # @param path the server path for this request (leading / is prepended if not present)
+ # @param args arguments to be sent to Facebook for this request
+ # @param verb the HTTP method to use
+ # @param options request-related options for Koala and Faraday.
+ # See https://github.com/arsduo/koala/wiki/HTTP-Services for additional options.
# @option options [Symbol] :http_component which part of the response (headers, body, or status) to return
# @option options [Boolean] :beta use Facebook's beta tier
- # @option options [Boolean] :use_ssl force SSL for this request, even if it's tokenless (all APIs with tokens use SSL)
- # @note See https://github.com/arsduo/koala/wiki/HTTP-Services for additional HTTP options used by Faraday
- # @param [Proc] error_checking_block a block to evaluate the response status for additional JSON-encoded errors
- # @yield [body] yields the response body for evaluation
+ # @option options [Boolean] :use_ssl force SSL for this request, even if it's tokenless.
+ # (All API requests with access tokens use SSL.)
+ # @param error_checking_block a block to evaluate the response status for additional JSON-encoded errors
+ #
+ # @yield The response body for evaluation
+ #
# @raise [Koala::Facebook::APIError] if Facebook returns an error (response status >= 500)
- # @returns the body of the response from Facebook (unless another http_component is requested)
+ #
+ # @return the body of the response from Facebook (unless another http_component is requested)
def api(path, args = {}, verb = "get", options = {}, &error_checking_block)
# Fetches the given path in the Graph API.
args["access_token"] = @access_token || @app_access_token if @access_token || @app_access_token
@@ -67,6 +69,13 @@ def api(path, args = {}, verb = "get", options = {}, &error_checking_block)
class APIError < StandardError
attr_accessor :fb_error_type, :raw_response
+
+ # Creates a new APIError.
+ #
+ # Assigns the error type (as reported by Facebook) to #fb_error_type
+ # and the raw error response available to #raw_response.
+ #
+ # @param details error details containing "type" and "message" keys.
def initialize(details = {})
self.raw_response = details
self.fb_error_type = details["type"]
View
@@ -3,8 +3,11 @@ module Koala
module Facebook
# Legacy support for old pre-1.2 APIs
+ # A wrapper for the old APIs deprecated in 1.2.0, which triggers a deprecation warning when used.
+ # Otherwise, this class functions identically to API.
+ # @see API
# @private
- class OldAPI < API;
+ class OldAPI < API
def initialize(*args)
Koala::Utils.deprecate("#{self.class.name} is deprecated and will be removed in a future version; please use the API class instead.")
super
View
@@ -9,21 +9,29 @@ module Facebook
class OAuth
attr_reader :app_id, :app_secret, :oauth_callback_url
+
+ # Creates a new OAuth client.
+ #
+ # @param app_id [String, Integer] a Facebook application ID
+ # @param app_secret a Facebook application secret
+ # @param oauth_callback_url the URL in your app to which users authenticating with OAuth will be sent
def initialize(app_id, app_secret, oauth_callback_url = nil)
- @app_id = app_id
+ @app_id = app_id.to_s
@app_secret = app_secret
@oauth_callback_url = oauth_callback_url
end
+ # Parses the cookie set Facebook's JavaScript SDK.
+ #
+ # @note to parse Facebook's new signed cookie format, this method makes a request to Facebook each time.
+ # We recommend storing authenticated user info in your Rails session (or equivalent) and only
+ # calling this when needed.
+ #
+ # @param cookie_hash a set of cookies that includes the Facebook cookie.
+ # You can pass Rack/Rails/Sinatra's cookie hash directly to this method.
+ #
+ # @return the authenticated user's information as a hash, or nil.
def get_user_info_from_cookie(cookie_hash)
- # Parses the cookie set Facebook's JavaScript SDK.
- # You can pass Rack/Rails/Sinatra's cookie hash directly to this method.
- #
- # If the user is logged in via Facebook, we return a dictionary with the
- # keys "uid" and "access_token". The former is the user's Facebook ID,
- # and the latter can be used to make authenticated requests to the Graph API.
- # If the user is not logged in, we return None.
-
if signed_cookie = cookie_hash["fbsr_#{@app_id}"]
parse_signed_cookie(signed_cookie)
elsif unsigned_cookie = cookie_hash["fbs_#{@app_id}"]
@@ -32,6 +40,13 @@ def get_user_info_from_cookie(cookie_hash)
end
alias_method :get_user_info_from_cookies, :get_user_info_from_cookie
+ # Parses the cookie set Facebook's JavaScript SDK and returns only the user ID.
+ #
+ # @note (see #get_user_info_from_cookie)
+ #
+ # @param (see #get_user_info_from_cookie)
+ #
+ # @return the authenticated user's Facebook ID, or nil.
def get_user_from_cookie(cookies)
if info = get_user_info_from_cookies(cookies)
# signed cookie has user_id, unsigned cookie has uid
@@ -42,6 +57,22 @@ def get_user_from_cookie(cookies)
# URLs
+ # Builds an OAuth URL, where users will be prompted to log in and for any desired permissions.
+ # When the users log in, you receive a callback with their
+ # See http://developers.facebook.com/docs/authentication/.
+ #
+ # @see #url_for_access_token
+ #
+ # @note The URL methods should only be used if your application can't use the Facebook Javascript SDK,
+ # which provides a much better user experience.
+ # See http://developers.facebook.com/docs/reference/javascript/.
+ #
+ # @param options any query values to add to the URL, as well as any special/required values listed below.
+ # @option options permissions an array or comma-separated string of desired permissions
+ #
+ # @raise ArgumentError if no OAuth callback was specified in OAuth#new or in options as :redirect_uri
+ #
+ # @return an OAuth URL you can send your users to
def url_for_oauth_code(options = {})
# for permissions, see http://developers.facebook.com/docs/authentication/permissions
if permissions = options.delete(:permissions)
@@ -53,6 +84,20 @@ def url_for_oauth_code(options = {})
build_url("https://#{GRAPH_SERVER}/oauth/authorize", true, url_options)
end
+ # Once you receive an OAuth code, you need to redeem it from Facebook using an appropriate URL.
+ # (This is done by your server behind the scenes.)
+ # See http://developers.facebook.com/docs/authentication/.
+ #
+ # @see #url_for_oauth_code
+ #
+ # @note (see #url_for_oauth_code)
+ #
+ # @param code the OAuth code received from Facebook
+ # @param options any additional query parameters to add to the URL
+ #
+ # @raise (see #url_for_oauth_code)
+ #
+ # @return an URL your server can query for the user's access token
def url_for_access_token(code, options = {})
# Creates the URL for the token corresponding to a given code generated by Facebook
url_options = {
@@ -63,6 +108,15 @@ def url_for_access_token(code, options = {})
build_url("https://#{GRAPH_SERVER}/oauth/access_token", true, url_options)
end
+ # Builds a URL for a given dialog (feed, friends, OAuth, pay, send, etc.)
+ # See http://developers.facebook.com/docs/reference/dialogs/.
+ #
+ # @note (see #url_for_oauth_code)
+ #
+ # @param dialog_type the kind of Facebook dialog you want to show
+ # @param options any additional query parameters to add to the URL
+ #
+ # @return an URL your server can query for the user's access token
def url_for_dialog(dialog_type, options = {})
# some endpoints require app_id, some client_id, supply both doesn't seem to hurt
url_options = {:app_id => @app_id, :client_id => @app_id}.merge(options)

0 comments on commit 63cfd87

Please sign in to comment.