ey-hmac.rb in ey-hmac-0.0.3

- old
+ new

@@ -28,19 +28,23 @@
                                Ey::Hmac::Adapter::Rails
                              end
                            end
     end
 
+    # Signs request by calculating signature and adding it to the specified header
     # @example
     #   Ey::Hmac.sign!(env, @key_id, @key_secret)
     #
+    # @see Ey::Hmac::Adapter#sign!
+    #
     # @param request [Hash] request environment
     # @option options [Ey::Hmac::Adapter] :adapter (#{default_adapter}) adapter to sign request with
     # @option options [Integer] :version (nil) signature version
     # @option options [String] :authorization_header ('Authorization') Authorization header key.
-    # @option options [String] :server ('EyHmac') service name prefixed to {#authorization}
-    # @see {Ey::Hmac::Adapter#sign!}
+    # @option options [String] :service ('EyHmac') service name prefixed to {Ey::Hmac::Adapter#authorization}
+    #
+    # @return [String] authorization signature
     def self.sign!(request, key_id, key_secret, options={})
       adapter = options[:adapter] || Ey::Hmac.default_adapter
 
       raise ArgumentError, "Missing adapter and Ey::Hmac.default_adapter" unless adapter
 
@@ -50,28 +54,43 @@
     # @example
     #   Ey::Hmac.authenticated? do |key_id|
     #     @consumer = Consumer.where(auth_id: key_id).first
     #     @consumer && @consumer.auth_key
     #   end
+    #
+    # @see Ey::Hmac::Adapter#authenticated?
+    # @see Ey::Hmac#authenticate!
+    #
     # @param request [Hash] request environment
     # @option options [Ey::Hmac::Adapter] :adapter ({#default_adapter}) adapter to verify request with
-    # @see {Ey::Hmac::Adapter#authenticated?}
+    # @yieldparam key_id [String] public HMAC key
+    #
+    # @return [Boolean] success of authentication
     def self.authenticated?(request, options={}, &block)
       adapter = options[:adapter] || Ey::Hmac.default_adapter
 
       raise ArgumentError, "Missing adapter and Ey::Hmac.default_adapter" unless adapter
 
       adapter.new(request, options).authenticated?(&block)
     end
 
+    # Check {Ey::Hmac::Adapter#authorization_signature} against calculated {Ey::Hmac::Adapter#signature}
     # @example
     #   Ey::Hmac.authenticate! do |key_id|
     #     @consumer = Consumer.where(auth_id: key_id).first
     #     @consumer && @consumer.auth_key
     #   end
+    #
+    # @see Ey::Hmac::Adapter#authenticate!
+    #
     # @param request [Hash] request environment
+    # @yieldparam key_id [String] public HMAC key
     # @option options [Ey::Hmac::Adapter] :adapter ({#default_adapter}) adapter to verify request with
-    # @see {Ey::Hmac::Adapter#authenticate!}
+    #
+    # @raise [SignatureMismatch] if the value of {Ey::Hmac::Adapter#authorization_signature} does not match {Ey::Hmac::Adapter#signature}
+    # @raise [MissingSecret] if the block does not return a private key matching +key_id+
+    # @raise [MissingAuthorization] if the value of {Ey::Hmac::Adapter#authorization_signature} is nil
+    # @return [TrueClass] if authentication was successful
     def self.authenticate!(request, options={}, &block)
       adapter = options[:adapter] || Ey::Hmac.default_adapter
 
       raise ArgumentError, "Missing adapter and Ey::Hmac.default_adapter" unless adapter
 