Merge pull request #92 from HelloFax/Audit

Audit

lib/hello_sign.rb

@@ -1,8 +1,8 @@
 #
 # The MIT License (MIT)
-# 
+#
 # Copyright (C) 2014 hellosign.com
-# 
+#
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
 # in the Software without restriction, including without limitation the rights
@@ -28,9 +28,8 @@
 
 module HelloSign
   extend Configuration
-
   #
-  # # If HelloSign module don't respond_to? method, then delegate it to HelloSign::Client
+  # # If HelloSign module doesn't respond to method, then delegates it to HelloSign::Client
   # @param  method [Symbol] method name
   # @param  *args [Array] arguments passed into the method
   # @param  &block [Block] a block passed into the method
@@ -41,7 +40,7 @@ def self.method_missing(method, *args, &block)
   end
 
   #
-  # If HelloSign module don't respond_to? method, ask HelloSign::Client whether it respond or not
+  # If HelloSign module don't respond to method, asks HelloSign::Client whether it responded or not
   # @param  method [Symbol] method name
   #
   def self.respond_to?(method, include_all=false)

lib/hello_sign/api/account.rb

@@ -26,14 +26,13 @@ module HelloSign
   module Api
 
     #
-    # Contains all the api calls for the Account resource.
-    # Take a look at our {https://app.hellosign.com/api/reference#Account account api document}
+    # Contains all the API calls for the Account resource.
+    # Take a look at our API Documentation on the Account resource (https://app.hellosign.com/api/reference#Account)
     # for more information about this.
     #
     # @author [hellosign]
     #
     module Account
-
       #
       # Returns the current user's account information.
       #
@@ -47,7 +46,7 @@ def get_account
       end
 
       #
-      # Creates a new HelloSign account. The user will still need to confirm their email address
+      # Creates a new HelloSign account. The user will still need to confirm the email address
       # to complete the creation process.
       #
       # Note: This request does not require authentication.

lib/hello_sign/api/api_app.rb

@@ -24,10 +24,9 @@
 
 module HelloSign
   module Api
-
     #
-    # Contains all the api calls for the ApiApp resource.
-    # Take a look at our {https://app.hellosign.com/api/reference#Team team api document}
+    # Contains all the API calls for the ApiApp resource.
+    # Take a look at our API Documentation for ApiApps (https://app.hellosign.com/api/reference#ApiApp)
     # for more information about this.
     #
     # @author [hellosign]
@@ -36,8 +35,9 @@ module ApiApp
 
       #
       # Retrieves information about a specific API App by a given ID
+      # @option opts [String] client_id The Client ID of the ApiApp.
       #
-      # @return [HelloSign::Resource::ApiApp] the API App
+      # @return [HelloSign::Resource::ApiApp] the ApiApp
       #
       # @example
       #   app = @client.get_api_app :client_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967'
@@ -48,8 +48,8 @@ def get_api_app(opts)
 
       #
       # Returns a list of ApiApps that you currently have access to on your account
-      # @option opts [Integer] page (1) Which page number of the list to return.
-      # @option opts [Integer] page_size (5) Number of results for each page
+      # @option opts [Integer] page Sets the page number of the list to return. Defaults to 1. (optional)
+      # @option opts [Integer] page_size Determines the number of ApiApps returned per page. Defaults to 20. (optional)
       #
       # @return [HelloSign::Resource::ResourceArray]
       #
@@ -65,12 +65,14 @@ def get_api_apps(opts={})
 
       #
       # Creates a new API Application on your account
-      # @option opts [String] name The name you want to assign to the ApiApp.
-      # @option opts [String] domain The domain name the ApiApp will be associated with.
-      # @option opts [String] callback_url (optional) The URL at which the ApiApp should receive event callbacks.
-      # @option opts [String] custom_logo_file (optional) An image file to use as a custom logo in embedded contexts. (Only applies to some API plans)
-      # @option opts [String] oauth[callback_url] (optional) The callback URL to be used for OAuth flows. (Required if oauth[scopes] is provided)
-      # @option opts [String] oauth[scopes] (optional) A comma-separated list of OAuth scopes to be granted to the app. (Required if oauth[callback_url] is provided)
+      # @option opts [String] name The name assigned to the ApiApp.
+      # @option opts [String] domain The domain associated with the ApiApp.
+      # @option opts [String] callback_url The URL that will receive callback events for the ApiApp. (optional)
+      # @option opts [String] custom_logo_file An image file to use as a custom logo in embedded workflows, if available in the API subscription. (optional)
+      # @option opts [String] oauth[callback_url] The callback URL to be used for OAuth flows. (optional)
+      # @option opts [String] oauth[scopes] A comma-separated list of OAuth scopes to be granted to the app. (optional)
+      # @option opts [String<Hash>] white_labeling_options Object with elements and values serialized to a string to customize the signer page, if available in the API subscription. (optional)
+      # @option opts [Boolean] options[can_insert_everywhere] Determines if signers can "Insert Everywhere" when signing a document. (optional)
       #
       # @return [HelloSign::Resource::ApiApp] newly created ApiApp object
       #
@@ -81,14 +83,16 @@ def create_api_app(opts)
       end
 
       #
-      # Updates parameters for a specific API Application on your account, referenced by ID
-      # @oprion opts [String] client_id (REQUIRED) The ID of the app you want to update
-      # @option opts [String] name (optional) The name you want to assign to the ApiApp.
-      # @option opts [String] domain (optional) The domain name the ApiApp will be associated with.
-      # @option opts [String] callback_url (optional) The URL at which the ApiApp should receive event callbacks.
-      # @option opts [String] custom_logo_file (optional) An image file to use as a custom logo in embedded contexts. (Only applies to some API plans)
-      # @option opts [String] oauth[callback_url] (optional) The callback URL to be used for OAuth flows. (Required if oauth[scopes] is provided)
-      # @option opts [String] oauth[scopes] (optional) A comma-separated list of OAuth scopes to be granted to the app. (Required if oauth[callback_url] is provided)
+      # Updates settings for a specific ApiApp on your account
+      # @option opts [String] client_id The Client ID of the ApiApp you want to update.
+      # @option opts [String] name The name assigned to the ApiApp. (optional)
+      # @option opts [String] domain The domain associated with the ApiApp. (optional)
+      # @option opts [String] callback_url The URL that will receive callback events for the ApiApp. (optional)
+      # @option opts [String] custom_logo_file An image file to use as a custom logo in embedded workflows, if available in the API subscription. (optional)
+      # @option opts [String] oauth[callback_url] The callback URL to be used for OAuth flows. (optional)
+      # @option opts [String] oauth[scopes] A comma-separated list of OAuth scopes to be granted to the app. (optional)
+      # @option opts [String<Hash>] white_labeling_options Object with elements and values serialized to a string to customize the signer page, if available in the API subscription. (optional)
+      # @option opts [Boolean] options[can_insert_everywhere] Determines if signers can "Insert Everywhere" when signing a document. (optional)
       #
       # @return [HelloSign::Resource::ApiApp] an ApiApp object
       #
@@ -101,10 +105,11 @@ def update_api_app(opts)
       end
 
       #
-      # Deletes an API App. Can only be invoked for apps you own.
+      # Deletes an ApiApp. Only available for ApiApps you own.
+      # @option opts [String] client_id The Client ID of the ApiApp you want to delete.
       #
       # @example
-      #   result = @client.delete_api_app :client_id => 'hdialuhfilaudshfa'
+      #   result = @client.delete_api_app :client_id => 'fa5c8a0b0f492d768749333ad6fcc214c111e967'
       def delete_api_app(opts)
         path = '/api_app/' + opts[:client_id]
         delete(path)

lib/hello_sign/api/embedded.rb

@@ -24,20 +24,20 @@
 
 module HelloSign
   module Api
-
     #
     # HelloSign allows you to embed the signing page on your site in an iFrame
-    # without the need for the end-user to create a HelloSign account.
-    # Take a look at our {https://app.hellosign.com/api/embeddedSigningWalkthrough embedded signing walkthrough}
+    # without the need for the signer/preparer to create a HelloSign account.
+    # Take a look at our Embedded Signing Walkthrough (https://app.hellosign.com/api/embeddedSigningWalkthrough)
     # for more information about this.
     #
     # @author [hellosign]
     #
     module Embedded
 
       #
-      # Retrieves the embedded signature request url.
-      # @option opts [String] signature_id The id of the signature to get a signature url for
+      # Retrieves the embedded signature sign_url.
+      #
+      # @option opts [String] signature_id The Signature ID to retrieve the embedded sign_url for.
       #
       # @return [HelloSign::Resource::Embedded] Returns an Embedded object
       # @example
@@ -47,11 +47,15 @@ def get_embedded_sign_url(opts)
         HelloSign::Resource::Embedded.new get("/embedded/sign_url/#{opts[:signature_id]}")
       end
       #
-      # Retrieves the edit url for an embedded template.
-      # @option opts [String] template_id The id of the template to get a edit url for
-      # @option opts [Integer] skip_signer_roles Whether editing signer roles should be skipped
-      # @option opts [Integer] skip_subject_message Whether editing subject/message should be skipped
-      # @option opts [Array<Hash>] merge_fields Merge fields that can be placed in the template
+      # Retrieves the edit_url for an embedded template.
+      # @option opts [Boolean] test_mode Indicates if this is a test Embedded Template. A boolean value is also accepted. Defaults to 0. (optional)
+      # @option opts [String] template_id The Template ID to retreive the embedded edit_url for.
+      # @option opts [Array<Hash>] cc_roles The CC roles that must be assigned when using the Embedded Template to create a SignatureRequest. (optional)
+      # @option opts [String<Array><Hash>] merge_fields List of fields that can be pre-populated by your application when using the Embedded Template to send a SignatureRequest. (optional)
+      #   * :name (String) Merge field name
+      #   * :type (String) Field type - either "text" or "checkbox"
+      # @option opts [Boolean] skip_signer_roles Removes the prompt to edit signer roles, if already provided. Defaults to 0. (optional)
+      # @option opts [Boolean] skip_subject_message Removes the prompt to edit the subject and message, if already provided. Defaults to 0. (optional)
       #
       # @return [HelloSign::Resource::Embedded] Returns an Embedded object
       # @example

lib/hello_sign/api/oauth.rb

@@ -27,31 +27,34 @@ module Api
 
     #
     # OAuth allows you to perform actions on behalf of other users after they grant you the authorization to do so.
-    # For example, you could send signature requests on behalf of your users. This page lays out the basic steps to do that.
-    # IMPORTANT
+    # For example, you could send signature requests on behalf of your users.
+    # For more information, see our OAuth API documentation (https://app.hellosign.com/api/oauthWalkthrough).
     #
-    # With OAuth, you (the app owner) will be charged for all signature requests sent on behalf of other users via your app.
+    # IMPORTANT: With some OAuth scopes, you (the app owner) will be charged for all signature requests sent on behalf of other users via your app.
     #
     # @author [hellosign]
     #
     module OAuth
 
       #
-      # Return the oath url where users can give permission for your application to perform actions on their behalf.
-      # @param  state [String] used for security and must match throughout the flow for a given user.
+      # Returns the OAuth URL where users can give permission for your application to perform actions on their behalf.
+      #
+      # @param state [String] used for security and must match throughout the flow for a given user.
       # It can be set to the value of your choice (preferably something random). You should verify it matches the expected value when validating the OAuth callback.
       # @return [type] [description]
       def oauth_url(state)
         "#{self.oauth_end_point}/oauth/authorize?response_type=code&client_id=#{self.client_id}&state=#{state}"
       end
 
       #
-      # Retrieving the OAuth token
+      # Retrieves the OAuth token
       #
-      # @option opts [String] state variable that was used when you created oauth_url for a specific user
-      # @option opts [String] code The authorization code passed to your callback when the user granted access
+      # @option opts [String] state Random value that was used when you created oauth_url for a specific user.
+      # @option opts [String] code The code passed to your callback when the user granted access.
+      # @option opts [String] client_id The API App Client ID.
+      # @option opts [String] client_secret The secret token of your API App.
       #
-      # @return [Hash] oauth data of the user
+      # @return [Hash] OAuth data of the user
       #
       # @example
       #   client = HelloSign::Client.new :api_key => '%apikey%', :client_id => 'cc91c61d00f8bb2ece1428035716b', :client_secret => '1d14434088507ffa390e6f5528465'
@@ -64,11 +67,11 @@ def get_oauth_token(opts)
       end
 
       #
-      # refresh user oauth token.
+      # Refreshes the user's OAuth token.
       #
-      # @return [Hash] refreshed oauth info
-      # @example
-      #   client = HelloSign::Client.new :api_key => '%apikey%', :client_id => 'cc91c61d00f8bb2ece1428035716b', :client_secret => '1d14434088507ffa390e6f5528465'
+      # @option opts [String] refresh_token The refresh provided when the access token has expired.
+      #
+      # @return [Hash] Refreshed OAuth info
       #
       # @example
       #   client.refresh_oauth_token :refresh_token => 'hNTI2MTFmM2VmZDQxZTZjOWRmZmFjZmVmMGMyNGFjMzI2MGI5YzgzNmE3'
@@ -79,12 +82,16 @@ def refresh_oauth_token(opts)
         post('/oauth/token', { :body => opts, :oauth_request => true })
       end
 
-
       #
-      # Create new user and get their OAuth token. The user will receive an email asking them to confirm the access being granted. Your app will not be able to perform actions on behalf of this user until they confirm.
-      # @option opts [String] email_address new user email address
+      # Create new user and get their OAuth token. The user will receive an email asking them to confirm the access being granted.
+      # Your app will not be able to perform actions on behalf of this user until they confirm.
+      #
+      # @option opts [String] email_address New user email address.
+      #
+      # @example
+      #   client.oauth_create_account :email_address => '[email protected]'
       #
-      # @return [Hash] details about new user, including oath data
+      # @return [Hash] details about new user, including OAuth data
       def oauth_create_account(opts)
         opts[:client_id] = self.client_id
         opts[:client_secret] = self.client_secret