Merge pull request #4 from urbanairship/doc_tweakings

branch for tweaking docs

Gemfile

@@ -1,4 +1,3 @@
 source 'https://rubygems.org'
 
-gemspec
-gem "unirest"
+gemspec

README.md

@@ -15,12 +15,7 @@ Version 3.0 is a major upgrade and backwards incompatible with earlier versions.
 Note: the BETA release only supports UA's ```/push/``` and ```/schedules/``` endpoints. Expanded support for UA's other endpoints will be in the forthcoming release. 
 
 ####Forthcoming Release
-To encourage the use of our SDK, which takes care of proper channel registration, support for device token registration will be removed. Support for v1 endpoints will also be removed and support for:
-
-* blackberry pin lookup, and
-* lookup and listing for device tokens
-
-will be moved from v1 to v3.
+To encourage the use of our SDK, which takes care of proper channel registration, support for device token registration will be removed. Support for v1 endpoints will also be removed and transitioned to their v3 equivalents where possible.
 
 ## Installation
 
@@ -40,7 +35,7 @@ OR install it yourself as:
 
 ## Usage
 
-Once the gem has been installed you can start sending pushes!
+Once the gem has been installed you can start sending pushes! See http://docs.urbanairship.com/topic-guides/api-examples.html for more examples.
 
 ####Broadcast to All Devices
 ```ruby

lib/urbanairship/client.rb

@@ -7,14 +7,29 @@ class Client
       attr_accessor :key, :secret
       include Urbanairship::Common
       include Urbanairship::Loggable
+
       # set default client timeout to 5 seconds
       Unirest.timeout(5)
 
+      # Initialize the Client
+      #
+      # @param [Object] key Application Key
+      # @param [Object] secret Application Secret
+      # @return [Object] Client
       def initialize(key: required('key'), secret: required('secret'))
         @key = key
         @secret = secret
       end
 
+      # Send a request to Urban Airship's API
+      #
+      # @param [Object] method HTTP Method
+      # @param [Object] body Request Body
+      # @param [Object] url Request URL
+      # @param [Object] content_type Content-Type
+      # @param [Object] version API Version
+      # @param [Object] params Parameters
+      # @return [Object] Push Response
       def send_request(method: required('method'), body: required('body'), url: required('url'),
                        content_type: nil, version: nil, params: nil)
         req_type = case method
@@ -52,10 +67,16 @@ def send_request(method: required('method'), body: required('body'), url: requir
         {'body'=>response.body, 'code'=>response.code}
       end
 
+      # Create a Push Object
+      #
+      # @return [Object] Push Object
       def create_push
         Push::Push.new(self)
       end
 
+      # Create a Scheduled Push Object
+      #
+      # @return [Object] Scheduled Push Object
       def create_scheduled_push
         Push::ScheduledPush.new(self)
       end

lib/urbanairship/common.rb

@@ -17,15 +17,16 @@ module Common
     SEGMENTS_URL = BASE_URL + '/segments/'
 
     # Helper method for required keyword args in 2.0 that is compatible with 2.1+
-    # EX:
+    # @example
     #   def say(greeting: required('greeting'))
     #     puts greeting
     #   end
     #
-    # >> say
-    # >> test.rb:3:in `required': required parameter :greeting not passed to method say (ArgumentError)
-    # >>       from test.rb:6:in `say'
-    # >>       from test.rb:18:in `<main>'
+    #   >> say
+    #   >> test.rb:3:in `required': required parameter :greeting not passed to method say (ArgumentError)
+    #   >>       from test.rb:6:in `say'
+    #   >>       from test.rb:18:in `<main>'
+    # @param [Object] arg optional argument name
     def required(arg=nil)
       method = caller_locations(1,1)[0].label
       raise ArgumentError.new("required parameter #{arg.to_sym.inspect + ' ' if arg}not passed to method #{method}")
@@ -51,8 +52,8 @@ def initialize
         @response = nil
       end
 
+      # Instantiate a ValidationFailure from a Response object
       def from_response(response)
-        """Instantiate a ValidationFailure from a Response object"""
 
         payload = response.body
         @error = payload['error']
@@ -68,6 +69,7 @@ def from_response(response)
     end
 
     class Response
+      # Parse Response Codes and trigger appropriate actions.
       def self.check_code(response_code, response)
         if response_code == 401
           raise Unauthorized, "Client is not authorized to make this request. The authorization credentials are incorrect or missing."

lib/urbanairship/push/audience.rb

@@ -140,6 +140,7 @@ def location(date: required('date'), **params)
 
       private
 
+      # Clean up a UUID for use in the library
       def cleanup(uuid)
         Util.validate(uuid, 'UUID', UUID_PATTERN)
         uuid.downcase.strip

lib/urbanairship/push/payload.rb

@@ -4,6 +4,7 @@ module Payload
       require 'ext/hash'
       include Urbanairship::Common
 
+      # Notification Object for a Push Payload
       def notification(alert: nil, ios: nil, android: nil, amazon: nil,
                        blackberry: nil, wns: nil, mpns: nil, actions: nil,
                        interactive: nil)
@@ -22,6 +23,7 @@ def notification(alert: nil, ios: nil, android: nil, amazon: nil,
         payload
       end
 
+      # iOS specific portion of Push Notification Object
       def ios(alert: nil, badge: nil, sound: nil, extra: nil, expiry: nil,
               category: nil, interactive: nil, content_available: nil)
         {
@@ -36,6 +38,7 @@ def ios(alert: nil, badge: nil, sound: nil, extra: nil, expiry: nil,
         }.compact
       end
 
+      # Amazon specific portion of Push Notification Object
       def amazon(alert: nil, consolidation_key: nil, expires_after: nil,
                  extra: nil, title: nil, summary: nil, interactive: nil)
         {
@@ -49,6 +52,7 @@ def amazon(alert: nil, consolidation_key: nil, expires_after: nil,
         }.compact
       end
 
+      # Android specific portion of Push Notification Object
       def android(alert: nil, collapse_key: nil, time_to_live: nil,
                   extra: nil, delay_while_idle: nil, interactive: nil)
         {
@@ -61,10 +65,12 @@ def android(alert: nil, collapse_key: nil, time_to_live: nil,
         }.compact
       end
 
+      # BlackBerry specific portion of Push Notification Object
       def blackberry(alert: nil, body: nil, content_type: 'text/plain')
         { body: alert || body, content_type: content_type }
       end
 
+      # WNS specific portion of Push Notification Object
       def wns_payload(alert: nil, toast: nil, tile: nil, badge: nil)
         payload = {
           alert: alert,
@@ -76,6 +82,7 @@ def wns_payload(alert: nil, toast: nil, tile: nil, badge: nil)
         payload
       end
 
+      # MPNS specific portion of Push Notification Object
       def mpns_payload(alert: nil, toast: nil, tile: nil)
         payload = {
           alert: alert,
@@ -86,6 +93,7 @@ def mpns_payload(alert: nil, toast: nil, tile: nil)
         payload
       end
 
+      # Rich Message specific portion of Push Notification Object
       def message(title: required('title'), body: required('body'), content_type: nil, content_encoding: nil,
                   extra: nil, expiry: nil, icons: nil, options: nil)
         {
@@ -100,6 +108,7 @@ def message(title: required('title'), body: required('body'), content_type: nil,
         }.compact
       end
 
+      # Interactive Notification portion of Push Notification Object
       def interactive(type: required('type'), button_actions: nil)
         fail ArgumentError, 'type must not be nil' if type.nil?
         { type: type, button_actions: button_actions }.compact
@@ -109,14 +118,17 @@ def all
         'all'
       end
 
+      # Target specified device types
       def device_types(types)
         types
       end
 
+      # Expiry for a Rich Message
       def options(expiry: required('expiry'))
         { expiry: expiry }
       end
 
+      # Actions for a Push Notification Object
       def actions(add_tag: nil, remove_tag: nil, open_: nil, share: nil,
                   app_defined: nil)
         {

lib/urbanairship/push/push.rb

@@ -7,14 +7,17 @@
 module Urbanairship
   module Push
 
-    # A push notification.
+    # A Push Notification.
     class Push
       attr_writer :client, :audience, :notification, :options,
                   :device_types, :message
       attr_reader :device_types
       include Urbanairship::Common
       include Urbanairship::Loggable
 
+      # Initialize a Push Object
+      #
+      # @param [Object] client
       def initialize(client)
         @client = client
       end
@@ -29,7 +32,8 @@ def payload
         }.compact
       end
 
-      # Send the notification.
+      # Send the Push Object
+      #
       # @raise [AirshipFailure] if the request failed
       # @raise [Unauthorized] if authentication failed
       # @raise [Forbidden] if app does not have entitlement
@@ -55,6 +59,9 @@ class ScheduledPush
       include Urbanairship::Common
       include Urbanairship::Loggable
 
+      # Initialize a Scheduled Push Object
+      #
+      # @param [Object] client
       def initialize(client)
         @client = client
       end
@@ -67,7 +74,8 @@ def payload
         }.compact
       end
 
-      # Schedule the notification
+      # Schedule the Push Notification
+      #
       # @raise [AirshipFailure] if the request failed
       # @raise [Unauthorized] if authentication failed
       # @raise [Forbidden] if app does not have entitlement
@@ -86,6 +94,11 @@ def send_push
         pr
       end
 
+      # Build a Scheduled Push Notification object its existing Scheduled Push URL
+      #
+      # @param [Object] client The Client
+      # @param [Object] url The existing Scheduled Push URL
+      # @return [Object] Scheduled Push Object
       def self.from_url(client: required('client'), url: required('url'))
         scheduled_push = ScheduledPush.new(client)
         response_body = client.send_request(
@@ -110,6 +123,9 @@ def self.from_url(client: required('client'), url: required('url'))
         scheduled_push
       end
 
+      # Cancel the Scheduled Push
+      #
+      # @return [Object] Push Response
       def cancel
         fail ArgumentError,
              'Cannot cancel ScheduledPush without a url.' if @url.nil?
@@ -126,6 +142,9 @@ def cancel
         pr
       end
 
+      # Update the Scheduled Push
+      #
+      # @return [Object]
       def update
         fail ArgumentError,
              'Cannot update a ScheduledPush without a url.' if @url.nil?
@@ -156,6 +175,9 @@ def initialize(http_response_body: nil, http_response_code: nil)
         @status_code = http_response_code
       end
 
+      # String Formatting of the PushResponse
+      #
+      # @return [Object] String Formatted PushResponse
       def format
         base = "Received [#{@status_code}] response code. \nHeaders: \tBody:\n"
         payload.each do |key, value|

lib/urbanairship/push/schedule.rb

@@ -3,10 +3,12 @@
 module Urbanairship
   module Push
     module Schedule
+      # Select a date and time for Scheduled Push
       def scheduled_time(datetime)
         payload(:scheduled_time, datetime)
       end
 
+      # Select a local date and time for Scheduled Push
       def local_scheduled_time(datetime)
         payload(:local_scheduled_time, datetime)
       end

spec/lib/urbanairship/push/push_spec.rb

@@ -5,7 +5,6 @@
 require 'urbanairship/push/push'
 
 describe Urbanairship::Push do
-  # Equivalent to Python's `import Urbanairship as UA`
   UA = Urbanairship
 
   let(:some_expiry) { 10_080 }
@@ -190,7 +189,7 @@ def expect_payload_to_have(additional_structure)
 
         scheduled_push = UA::Push::ScheduledPush.new(airship)
         scheduled_push.push = a_push
-        scheduled_push.schedule = UA.scheduled_time(DateTime.now)
+        scheduled_push.schedule = UA.scheduled_time(Time.now)
         scheduled_push.send_push
 
         expect(scheduled_push.url)
@@ -270,7 +269,7 @@ def expect_payload_to_have(additional_structure)
     end
 
     describe '#payload' do
-      let(:a_time)         { DateTime.new(2013, 1, 1, 12, 56) }
+      let(:a_time)         { Time.new(2013, 1, 1, 12, 56) }
       let(:a_time_in_text) { '2013-01-01T12:56:00' }
       let(:a_name)         { 'This Schedule' }
       let(:scheduled_push) {

spec/lib/urbanairship/push/scheduled_spec.rb

@@ -5,7 +5,7 @@
 describe Urbanairship do
   UA = Urbanairship
 
-  let(:a_time) { DateTime.new(2013, 1, 1, 12, 56) }
+  let(:a_time) { Time.new(2013, 1, 1, 12, 56) }
   let(:a_time_in_text) { '2013-01-01T12:56:00' }
 
   describe '#scheduled_time' do

spec/spec_helper.rb

@@ -1,4 +1 @@
 $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
-# TODO: Remove from here:
-require 'urbanairship'
-require 'pry'