toopher_api 1.0.1 → 1.0.2

data/Rakefile

@@ -1,8 +1,12 @@
 require 'rake/testtask'
+require 'yard'
+
+task :default => :test
 
 Rake::TestTask.new do |t|
   t.libs << 'test'
 end
-
 desc 'Run tests'
-task :default => :test
+
+YARD::Rake::YardocTask.new do |t|
+end

data/lib/toopher_api.rb

@@ -27,11 +27,14 @@ require 'uri'
 require 'json'
 require 'oauth'
 
+# An exception class used to indicate an error returned by a Toopher API request
 class ToopherApiError < StandardError
 end
 
+# Abstracts calls to the Toopher OAuth webservice
 class ToopherAPI
 
+  # Default URL for the Toopher webservice API.  Can be overridden in the constructor if necessary.
   DEFAULT_BASE_URL = 'https://toopher-api.appspot.com/v1/'
 
   # Creates a Toopher API consumer
@@ -54,8 +57,8 @@ class ToopherAPI
 
   # Create the pairing between a particular user and their mobile device
   #
-  # @param [String] pairing_phrase The pairing phrase (from the user's mobile device).
-  # @param [String] user_name User name
+  # @param [String] pairing_phrase The pairing phrase generated by a user's mobile application.
+  # @param [String] user_name A human recognizable string which represents the user making the request (usually their username). This is displayed to the user on the mobile app when authenticating.
   #
   # @return [PairingStatus] Information about the pairing request
   def pair(pairing_phrase, user_name)
@@ -66,10 +69,21 @@ class ToopherAPI
   end
 
   # Check on the status of a previous pairing request
+  #
+  # @param [String] pairing_request_id The unique string identifier id returned by a previous pairing request.
+  #
+  # @return [PairingStatus] Information about the pairing request
   def get_pairing_status(pairing_request_id)
     return PairingStatus.new(get('pairings/' + pairing_request_id))
   end
 
+  # Authenticate an action with Toopher
+  #
+  # @param [String] pairing_id The unique string identifier id returned by a previous pairing request.
+  # @param [String] terminal_name A human recognizable string which represents the terminal from which the user is making the request. This is displayed to the user on the mobile app when authenticating. If this is not included, then a terminal_id returned from a previous request must be provided (see below). These should be unique values for each different device from which a user connects to your service (as best you can detect).
+  # @param [String] action_name Optional action name, defaults to "log in" (displayed to the user)
+  #
+  # @return [AuthenticationStatus] Information about the authentication request
   def authenticate(pairing_id, terminal_name, action_name = '')
     parameters = {
       'pairing_id' => pairing_id,
@@ -79,6 +93,9 @@ class ToopherAPI
     return AuthenticationStatus.new(post('authentication_requests/initiate', parameters))
   end
 
+  # Check on the status of a previous authentication request
+  #
+  # @param [String] authentication_request_id The unique string identifier id returned by a previous authentication request.
   def get_authentication_status(authentication_request_id)
     return AuthenticationStatus.new(get('authentication_requests/' + authentication_request_id))
   end
@@ -110,10 +127,23 @@ class ToopherAPI
   end
 end
 
+# Contains information about a particular pairing request
 class PairingStatus
+
+  # @!attribute id
+  #   @return [String] A unique identifier generated and returned by the Toopher web service that is used to identify this pairing. It can be used to request status information for the pairing and must be included in subsequent authentication requests for this user.
   attr_accessor :id
+
+  # @!attribute enabled
+  #   @return [Boolean] Indicates whether or not the pairing has been acknowledged and enabled by the user.
   attr_accessor :enabled
+
+  # @!attribute user_id
+  #   @return [String] A unique identifier generated and returned by the Toopher web service for a given user.
   attr_accessor :user_id
+
+  # @!attribute user_name
+  #   @return [String] The human recognizable user name associated with the given id.
   attr_accessor :user_name
 
   def initialize(json_obj)
@@ -124,13 +154,35 @@ class PairingStatus
   end
 end
 
+# Contains information about a particular authentication request
 class AuthenticationStatus
+
+  # @!attribute id
+  #   @return [String] A unique string identifier generated and returned by the Toopher web service that is used to identify this authentication request. It can be used to request status information for the authentication request.
   attr_accessor :id
+
+  # @!attribute pending
+  #   @return [Boolean] Indicates whether the request is still pending.
   attr_accessor :pending
+
+  # @!attribute granted
+  #   @return [Boolean] Indicates whether the request was granted.
   attr_accessor :granted
+
+  # @!attribute automated
+  #   @return [Boolean] Indicates whether the request was automated.
   attr_accessor :automated
+
+  # @!attribute reason
+  #   @return  [String]A string which provides additional information about the reason for the authentication outcome (if available).
   attr_accessor :reason
+
+  # @!attribute terminal_id
+  #   @return  [String]A unique string identifier generated and returned by the Toopher web service for a given terminal.
   attr_accessor :terminal_id
+
+  # @!attribute terminal_name
+  #   @return [String] The human recognizable terminal name associated with the given id.
   attr_accessor :terminal_name
 
   def initialize(json_obj)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toopher_api
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -59,6 +59,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 1.9.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.3
 description: Synchronous interface to the toopher.com authentication api.
 email: support@toopher.com
 executables: []
@@ -69,7 +85,7 @@ files:
 - lib/toopher_api.rb
 - test/test_toopher_api.rb
 - demo/toopher_demo.rb
-homepage: http://toopher.org
+homepage: http://dev.toopher.org
 licenses: []
 post_install_message: 
 rdoc_options: []
@@ -94,3 +110,4 @@ signing_key:
 specification_version: 3
 summary: Interface to the toopher.com authentication api
 test_files: []
+has_rdoc: