Updating lots of documentation.

README.markdown

@@ -22,12 +22,12 @@ OmniAuth currently supports the following external providers:
   * Foursquare
   * LinkedIn
   * GitHub
-  * Identi.ca
-  * Gowalla [credit: [kvnsmth](http://github.com/kvnsmth)]
+  * Identi.ca (credit: [dcu](http://github.com/dcu))
+  * Gowalla (credit: [kvnsmth](http://github.com/kvnsmth))
 * OpenID
 * Google Apps (via OpenID)
-* CAS (Central Authentication Service) [credit: [jamesarosen](http://github.com/jamesarosen)]
-* LDAP [credit: **Ping Yu**]
+* CAS (Central Authentication Service) (credit: [jamesarosen](http://github.com/jamesarosen))
+* LDAP (credit: **Ping Yu**)
 
 ## Usage
 

Rakefile

@@ -136,17 +136,17 @@ end
 task :default => :spec
 
 begin
+  YARD_OPTS = ['-m', 'markdown', '-M', 'maruku']
   require 'yard'
   YARD::Rake::YardocTask.new(:doc) do |t|
-    t.name = 'doc'
     t.files   = OMNIAUTH_GEMS.inject([]){|a,g| a = a + ["#{g}/lib/**/*.rb"]; a} + ['README.markdown']
-    t.options = ["-o", "../omniauth.doc"]
+    t.options = YARD_OPTS
   end
   
   namespace :doc do
     YARD::Rake::YardocTask.new(:pages) do |t|
       t.files   = OMNIAUTH_GEMS.inject([]){|a,g| a = a + ["#{g}/lib/**/*.rb"]; a} + ['README.markdown']
-      t.options = ["-o", "../omniauth.doc"]
+      t.options = YARD_OPTS + ['-o', '../omniauth.doc']
     end
     
     namespace :pages do

oa-core/lib/omniauth/test/strategy_test_case.rb

@@ -5,8 +5,9 @@ module OmniAuth
   
   module Test
     
-    # Support for testing OmniAuth strategies. Usage:
+    # Support for testing OmniAuth strategies.
     #
+    # @example Usage
     #   class MyStrategyTest < Test::Unit::TestCase
     #     include OmniAuth::Test::StrategyTestCase
     #     def strategy

oa-enterprise/lib/omniauth/strategies/cas/configuration.rb

@@ -11,12 +11,12 @@ module OmniAuth
 
         # @param [Hash] params configuration options
         # @option params [String, nil] :cas_server the CAS server root URL; probably something like
-        #         'http://cas.mycompany.com' or 'http://cas.mycompany.com/cas'; optional.
+        #         `http://cas.mycompany.com` or `http://cas.mycompany.com/cas`; optional.
         # @option params [String, nil] :cas_login_url (:cas_server + '/login') the URL to which to
-        #         redirect for logins; options if <tt>:cas_server</tt> is specified,
+        #         redirect for logins; options if `:cas_server` is specified,
         #         required otherwise.
         # @option params [String, nil] :cas_service_validate_url (:cas_server + '/serviceValidate') the
-        #         URL to use for validating service tickets; optional if <tt>:cas_server</tt> is
+        #         URL to use for validating service tickets; optional if `:cas_server` is
         #         specified, requred otherwise.
         def initialize(params)
           parse_params params
@@ -26,8 +26,7 @@ module OmniAuth
         #
         # @param [String] service the service (a.k.a. return-to) URL
         # 
-        # @return [String] a URL like
-        # "http://cas.mycompany.com/login?service=..."
+        # @return [String] a URL like `http://cas.mycompany.com/login?service=...`
         def login_url(service)
           append_service @login_url, service
         end
@@ -37,8 +36,7 @@ module OmniAuth
         # @param [String] service the service (a.k.a. return-to) URL
         # @param [String] ticket the ticket to validate
         #
-        # @return [String] a URL like
-        # "http://cas.mycompany.com/serviceValidate?service=...&ticket=..."
+        # @return [String] a URL like `http://cas.mycompany.com/serviceValidate?service=...&ticket=...`
         def service_validate_url(service, ticket)
           url = append_service @service_validate_url, service
           url << '&ticket=' << Rack::Utils.escape(ticket)

oa-enterprise/lib/omniauth/strategies/cas/service_ticket_validator.rb

@@ -31,7 +31,7 @@ module OmniAuth
 
         private
         
-        # turns an <cas:authenticationSuccess> node into a Hash;
+        # turns an `<cas:authenticationSuccess>` node into a Hash;
         # returns nil if given nil
         def parse_user_info(node)
           return nil if node.nil?
@@ -45,8 +45,8 @@ module OmniAuth
           end
         end
         
-        # finds an <cas:authenticationSuccess> node in
-        # a <cas:serviceResponse> body if present; returns nil
+        # finds an `<cas:authenticationSuccess>` node in
+        # a `<cas:serviceResponse>` body if present; returns nil
         # if the passed body is nil or if there is no such node.
         def find_authentication_success(body)
           return nil if body.nil? || body == ''
@@ -62,7 +62,7 @@ module OmniAuth
           end
         end
         
-        # retrieves the <cas:serviceResponse> XML from the CAS server
+        # retrieves the `<cas:serviceResponse>` XML from the CAS server
         def get_service_response_body
           result = ''
           http = Net::HTTP.new(@uri.host, @uri.port)

oa-oauth/lib/omniauth/strategies/facebook.rb

@@ -3,18 +3,16 @@ require 'multi_json'
 
 module OmniAuth
   module Strategies
-    #
     # Authenticate to Facebook utilizing OAuth 2.0 and retrieve
     # basic user information.
     #
-    # Usage:
-    #
-    #    use OmniAuth::Strategies::Facebook, 'app_id', 'app_secret'
-    #
-    # Options:
-    #
-    # <tt>:scope</tt> :: Extended permissions such as <tt>email</tt> and <tt>offline_access</tt> (which are the defaults).
+    # @example Basic Usage
+    #     use OmniAuth::Strategies::Facebook, 'app_id', 'app_secret'
     class Facebook < OAuth2
+      # @param [Rack Application] app standard middleware application parameter
+      # @param [String] app_id the application id as [registered on Facebook](http://www.facebook.com/developers/)
+      # @param [String] app_secret the application secret as registered on Facebook
+      # @option options [String] :scope ('email,offline_access') comma-separated extended permissions such as `email` and `manage_pages`
       def initialize(app, app_id, app_secret, options = {})
         options[:site] = 'https://graph.facebook.com/'
         super(app, :facebook, app_id, app_secret, options)

oa-oauth/lib/omniauth/strategies/github.rb

@@ -3,7 +3,13 @@ require 'multi_json'
 
 module OmniAuth
   module Strategies
+    # OAuth 2.0 based authentication with GitHub. In order to 
+    # sign up for an application, you need to [register an application](http://github.com/account/applications/new)
+    # and provide the proper credentials to this middleware.
     class GitHub < OAuth2
+      # @param [Rack Application] app standard middleware application argument
+      # @param [String] app_id the application ID for your client
+      # @param [String] app_secret the application secret
       def initialize(app, app_id, app_secret, options = {})
         options[:site] = 'https://github.com/'
         options[:authorize_path] = '/login/oauth/authorize'
@@ -11,6 +17,8 @@ module OmniAuth
         super(app, :github, app_id, app_secret, options)
       end
       
+      protected
+      
       def user_data
         @data ||= MultiJson.decode(@access_token.get('/api/v2/json/user/show'))['user']
       end

oa-oauth/lib/omniauth/strategies/gowalla.rb

@@ -7,14 +7,13 @@ module OmniAuth
     # Authenticate to Gowalla utilizing OAuth 2.0 and retrieve
     # basic user information.
     #
-    # Usage:
-    #
-    #    use OmniAuth::Strategies::Gowalla, 'API Key', 'Secret Key'
-    #
-    # Options:
-    #
-    # <tt>:scope</tt> :: Extended permissions such as <tt>email</tt> and <tt>offline_access</tt> (which are the defaults).
+    # @example Basic Usage
+    #     use OmniAuth::Strategies::Gowalla, 'API Key', 'Secret Key'
     class Gowalla < OAuth2
+      # @param [Rack Application] app standard middleware application parameter
+      # @param [String] api_key the application id as [registered on Gowalla](http://gowalla.com/api/keys)
+      # @param [String] secret_key the application secret as [registered on Gowalla](http://gowalla.com/api/keys)
+      # @option options ['read','read-write'] :scope ('read') the scope of your authorization request; must be `read` or `read-write`
       def initialize(app, api_key, secret_key, options = {})
         options[:site] = 'https://api.gowalla.com/api/oauth'
         options[:authorize_url] = 'https://gowalla.com/api/oauth/new'
@@ -22,12 +21,14 @@ module OmniAuth
         super(app, :gowalla, api_key, secret_key, options)
       end
       
+      protected
+      
       def user_data
         @data ||= MultiJson.decode(@access_token.get("/users/me.json"))
       end
       
       def request_phase
-        options[:scope] ||= "email,offline_access"
+        options[:scope] ||= "read"
         super
       end
       

oa-oauth/lib/omniauth/strategies/oauth2.rb

@@ -5,11 +5,21 @@ require 'omniauth/oauth'
 
 module OmniAuth
   module Strategies
+    # Authentication strategy for connecting with APIs constructed using
+    # the [OAuth 2.0 Specification](http://tools.ietf.org/html/draft-ietf-oauth-v2-10).
+    # You must generally register your application with the provider and
+    # utilize an application id and secret in order to authenticate using
+    # OAuth 2.0.
     class OAuth2
       include OmniAuth::Strategy
       
-      attr_accessor :options, :client
+      # The options passed in to the strategy.
+      attr_accessor :options
+      # The `OAuth2::Client` for this strategy.
+      attr_accessor :client
       
+      # An error that is indicated in the OAuth 2.0 callback.
+      # This could be a `redirect_uri_mismatch` or other 
       class CallbackError < StandardError
         attr_accessor :error, :error_reason, :error_uri
         
@@ -20,6 +30,13 @@ module OmniAuth
         end
       end
       
+      # Initialize a new OAuth 2.0 authentication provider.
+      
+      # @param [Rack Application] app standard middleware application argument
+      # @param [String] name the name for this provider to be used in its URL, e.g. `/auth/name`
+      # @param [String] client_id the client/application ID of this provider
+      # @param [String] client_secret the client/application secret of this provider
+      # @param [Hash] options that will be passed through to the OAuth2::Client (see [oauth2 docs](http://rubydoc.info/gems/oauth2))
       def initialize(app, name, client_id, client_secret, options = {})
         super(app, name)
         self.options = options

oa-openid/lib/omniauth/openid.rb

@@ -4,7 +4,7 @@ module OmniAuth
   # OmniAuth::OpenID provides strategies for authenticating to providers
   # using the OpenID standard. 
   # 
-  # == Installation
+  # # Installation
   # 
   # To get just OpenID functionality:
   # 
@@ -14,7 +14,7 @@ module OmniAuth
   # 
   #     gem install omniauth
   # 
-  # == Stand-Alone Example
+  # # Stand-Alone Example
   # 
   # Use the strategy as a middleware in your application:
   # 
@@ -28,7 +28,7 @@ module OmniAuth
   # 
   # A list of all OpenID stores is available at http://github.com/openid/ruby-openid/tree/master/lib/openid/store/
   # 
-  # == OmniAuth Builder
+  # # OmniAuth Builder
   # 
   # If OpenID is one of several authentication strategies, use the OmniAuth Builder:
   # 
@@ -41,7 +41,7 @@ module OmniAuth
   #       provider :campfire
   #     end
   # 
-  # == Configured Identifiers
+  # # Configured Identifiers
   # 
   # You may pre-configure an OpenID identifier.  For example, to use Google's main OpenID endpoint:
   #