trackerific 0.3.1 → 0.3.2

data/doc/_index.html

@@ -186,7 +186,7 @@
 </div>
     
     <div id="footer">
-  Generated on Mon Jun 13 14:22:51 2011 by 
+  Generated on Mon Jun 13 16:20:05 2011 by 
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.7.1 (ruby-1.9.2).
 </div>

data/doc/file.README.html

@@ -206,7 +206,7 @@ Copyright © 2011 Travis Haynes. See LICENSE.txt for further details.
 </div></div>
     
     <div id="footer">
-  Generated on Mon Jun 13 14:22:51 2011 by 
+  Generated on Mon Jun 13 16:20:05 2011 by 
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.7.1 (ruby-1.9.2).
 </div>

data/doc/index.html

@@ -206,7 +206,7 @@ Copyright © 2011 Travis Haynes. See LICENSE.txt for further details.
 </div></div>
     
     <div id="footer">
-  Generated on Mon Jun 13 14:22:51 2011 by 
+  Generated on Mon Jun 13 16:20:05 2011 by 
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.7.1 (ruby-1.9.2).
 </div>

data/doc/method_list.html

@@ -65,9 +65,9 @@
   
 
   <li class="r2 ">
-    <span class='object_link'><a href="Trackerific/USPS.html#initialize-instance_method" title="Trackerific::USPS#initialize (method)">#initialize</a></span> 
+    <span class='object_link'><a href="Trackerific/Base.html#initialize-instance_method" title="Trackerific::Base#initialize (method)">#initialize</a></span> 
     
-      <small>Trackerific::USPS</small>
+      <small>Trackerific::Base</small>
     
   </li>
   
@@ -81,14 +81,6 @@
   
 
   <li class="r2 ">
-    <span class='object_link'><a href="Trackerific/Base.html#initialize-instance_method" title="Trackerific::Base#initialize (method)">#initialize</a></span> 
-    
-      <small>Trackerific::Base</small>
-    
-  </li>
-  
-
-  <li class="r1 ">
     <span class='object_link'><a href="Trackerific/Event.html#initialize-instance_method" title="Trackerific::Event#initialize (method)">#initialize</a></span> 
     
       <small>Trackerific::Event</small>
@@ -96,7 +88,7 @@
   </li>
   
 
-  <li class="r2 ">
+  <li class="r1 ">
     <span class='object_link'><a href="Trackerific/Event.html#location-instance_method" title="Trackerific::Event#location (method)">#location</a></span> 
     
       <small>Trackerific::Event</small>
@@ -104,7 +96,7 @@
   </li>
   
 
-  <li class="r1 ">
+  <li class="r2 ">
     <span class='object_link'><a href="Trackerific/Details.html#package_id-instance_method" title="Trackerific::Details#package_id (method)">#package_id</a></span> 
     
       <small>Trackerific::Details</small>
@@ -112,32 +104,24 @@
   </li>
   
 
-  <li class="r2 ">
-    <span class='object_link'><a href="Trackerific/USPS.html#required_options-instance_method" title="Trackerific::USPS#required_options (method)">#required_options</a></span> 
-    
-      <small>Trackerific::USPS</small>
-    
-  </li>
-  
-
   <li class="r1 ">
-    <span class='object_link'><a href="Trackerific/Base.html#required_options-instance_method" title="Trackerific::Base#required_options (method)">#required_options</a></span> 
+    <span class='object_link'><a href="Trackerific/Details.html#summary-instance_method" title="Trackerific::Details#summary (method)">#summary</a></span> 
     
-      <small>Trackerific::Base</small>
+      <small>Trackerific::Details</small>
     
   </li>
   
 
   <li class="r2 ">
-    <span class='object_link'><a href="Trackerific/FedEx.html#required_options-instance_method" title="Trackerific::FedEx#required_options (method)">#required_options</a></span> 
+    <span class='object_link'><a href="Trackerific/Event.html#to_s-instance_method" title="Trackerific::Event#to_s (method)">#to_s</a></span> 
     
-      <small>Trackerific::FedEx</small>
+      <small>Trackerific::Event</small>
     
   </li>
   
 
   <li class="r1 ">
-    <span class='object_link'><a href="Trackerific/UPS.html#required_options-instance_method" title="Trackerific::UPS#required_options (method)">#required_options</a></span> 
+    <span class='object_link'><a href="Trackerific/UPS.html#track_package-instance_method" title="Trackerific::UPS#track_package (method)">#track_package</a></span> 
     
       <small>Trackerific::UPS</small>
     
@@ -145,25 +129,9 @@
   
 
   <li class="r2 ">
-    <span class='object_link'><a href="Trackerific/Details.html#summary-instance_method" title="Trackerific::Details#summary (method)">#summary</a></span> 
-    
-      <small>Trackerific::Details</small>
-    
-  </li>
-  
-
-  <li class="r1 ">
-    <span class='object_link'><a href="Trackerific/Event.html#to_s-instance_method" title="Trackerific::Event#to_s (method)">#to_s</a></span> 
-    
-      <small>Trackerific::Event</small>
-    
-  </li>
-  
-
-  <li class="r2 ">
-    <span class='object_link'><a href="Trackerific/Base.html#track_package-instance_method" title="Trackerific::Base#track_package (method)">#track_package</a></span> 
+    <span class='object_link'><a href="Trackerific/USPS.html#track_package-instance_method" title="Trackerific::USPS#track_package (method)">#track_package</a></span> 
     
-      <small>Trackerific::Base</small>
+      <small>Trackerific::USPS</small>
     
   </li>
   
@@ -177,22 +145,14 @@
   
 
   <li class="r2 ">
-    <span class='object_link'><a href="Trackerific/UPS.html#track_package-instance_method" title="Trackerific::UPS#track_package (method)">#track_package</a></span> 
+    <span class='object_link'><a href="Trackerific/Base.html#track_package-instance_method" title="Trackerific::Base#track_package (method)">#track_package</a></span> 
     
-      <small>Trackerific::UPS</small>
+      <small>Trackerific::Base</small>
     
   </li>
   
 
   <li class="r1 ">
-    <span class='object_link'><a href="Trackerific/USPS.html#track_package-instance_method" title="Trackerific::USPS#track_package (method)">#track_package</a></span> 
-    
-      <small>Trackerific::USPS</small>
-    
-  </li>
-  
-
-  <li class="r2 ">
     <span class='object_link'><a href="Trackerific.html#tracking_service-instance_method" title="Trackerific#tracking_service (method)">#tracking_service</a></span> 
     
       <small>Trackerific</small>

data/doc/top-level-namespace.html

@@ -94,7 +94,7 @@
 </div>
     
     <div id="footer">
-  Generated on Mon Jun 13 14:22:52 2011 by 
+  Generated on Mon Jun 13 16:20:06 2011 by 
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.7.1 (ruby-1.9.2).
 </div>

data/lib/fedex.rb

@@ -4,41 +4,41 @@ module Trackerific
   
   # Provides package tracking support for FedEx
   class FedEx < Base
+    # setup HTTParty
     include ::HTTParty
     format :xml
     base_uri "https://gateway.fedex.com"
     
-    # @return [Array] required options for tracking a FedEx package are :account
-    #   and :meter.
-    def required_options
-      [:account, :meter]
-    end
-    
-    # Tracks a FedEx package.
-    #
-    # A Trackerific::Error is raised when a package cannot be tracked.
-    #
+    # Tracks a FedEx package
+    # @param [String] package_id the package identifier
     # @return [Trackerific::Details] the tracking details
+    # @raise [Trackerific::Error] raised when the server returns an error (invalid credentials, tracking package, etc.)
+    # @example Track a package
+    #   fedex = Trackerific::FedEx.new :account => 'account', :meter => 'meter'
+    #   details = fedex.track_package("183689015000001")
+    # @api public
     def track_package(package_id)
       super
+      # request tracking information from FedEx via HTTParty
       http_response = self.class.post "/GatewayDC", :body => build_xml_request
+      # raise any HTTP errors
       http_response.error! unless http_response.code == 200
-      
+      # get the tracking information from the reply
       track_reply = http_response["FDXTrack2Reply"]
+      # raise a Trackerific::Error if there is an error in the reply
       raise Trackerific::Error, track_reply["Error"]["Message"] unless track_reply["Error"].nil?
-      
+      # get the details from the reply
       details = track_reply["Package"]
+      # convert them into Trackerific::Events
       events = []
       details["Event"].each do |e|
         date = Time.parse("#{e["Date"]} #{e["Time"]}")
         desc = e["Description"]
         addr = e["Address"]
-        # Adds event in this format:
-        # MM DD HH:MM am/pm Description City State Zip
         events << Trackerific::Event.new(date, desc, "#{addr["StateOrProvinceCode"]} #{addr["PostalCode"]}")
       end
-      
-      Details.new(
+      # Return a Trackerific::Details containing all the events
+      Trackerific::Details.new(
         details["TrackingNumber"],
         details["StatusDescription"],
         events
@@ -47,15 +47,30 @@ module Trackerific
     
     protected
     
+    # Returns an Array of required options used when creating a new instance
+    # @return [Array] required options for tracking a FedEx package are :account
+    #   and :meter
+    # @api private
+    def required_options
+      [:account, :meter]
+    end
+    
     # Builds the XML request to send to FedEx
     # @return [String] a FDXTrack2Request XML
+    # @api private
     def build_xml_request
       xml = ""
+      # the API namespace
       xmlns_api = "http://www.fedex.com/fsmapi"
+      # the XSI namespace
       xmlns_xsi = "http://www.w3.org/2001/XMLSchema-instance"
+      # the XSD namespace
       xsi_noNSL = "FDXTrack2Request.xsd"
+      # create a new Builder to generate the XML
       builder = ::Builder::XmlMarkup.new(:target => xml)
+      # add the XML header
       builder.instruct! :xml, :version => "1.0", :encoding => "UTF-8"
+      # Build, and return the request
       builder.FDXTrack2Request "xmlns:api"=>xmlns_api, "xmlns:xsi"=>xmlns_xsi, "xsi:noNamespaceSchemaLocation" => xsi_noNSL do |r|
         r.RequestHeader do |rh|
           rh.AccountNumber @options[:account]
@@ -66,7 +81,7 @@ module Trackerific
         end
         r.DetailScans true
       end
-      return xml
+      xml
     end
     
   end

data/lib/trackerific.rb

@@ -9,40 +9,71 @@ module Trackerific
   
   # Base class for Trackerific package tracking services.
   class Base
+    # Creates a new instance of Trackerific::Base with required options
+    # @api private
     def initialize(options = {})
       required = required_options
+      # make sure all the required options exist
       required.each do |k|
         raise ArgumentError.new("Missing required parameter: #{k}") unless options.has_key?(k)
       end
+      # make sure no invalid options exist
       options.each do |k, v|
         raise ArgumentError.new("Invalid parameter: #{k}") unless required.include?(k)
       end
       @options = options
     end
     
-    # Override this method if your subclass has required options.
+    # Gets the tracking information for the package from the server
+    # @param [String] package_id the package identifier
+    # @return [Trackerific::Details] the tracking details
+    # @example Override this method in your custom tracking provider to implement tracking
+    #   module Trackerific
+    #     class MyTrackingProvider < Base
+    #       def track_package
+    #         Trackerific::Details.new(
+    #           "summary of tracking events",
+    #           [Trackerific::Event.new(Time.now, "summary", "location")]
+    #         )
+    #       end
+    #     end
+    #   end
+    # @api public
+    def track_package(package_id)
+      @package_id = package_id
+    end
+    
+    protected
+    
+    # An array of options that are required to create a new instance of this class
     # @return [Array] the required options
+    # @example Override this method in your custom tracking provider to enforce some options
+    #   module Trackerific
+    #     class MyTrackingProvider < Base
+    #       def required_options
+    #         [:all, :these, :are, :required]
+    #       end
+    #     end
+    #   end
+    # @api private
     def required_options
       []
     end
     
-    # Override this method in your subclass to implement tracking a package.
-    # @return [Hash] the tracking details
-    def track_package(package_id)
-      @package_id = package_id
-    end
   end
   
   require 'usps'
   require 'fedex'
   require 'ups'
   
-  # Checks a string for a valid package identifier, and returns a Trackerific
-  # class that should be able to track the package.
-  #
-  # @param [String] the package identifier.
+  # Checks a string for a valid package tracking service
+  # @param [String] package_id the package identifier
   # @return [Trackerific::Base] the Trackerific class that can track the given
   #   package id, or nil if none found.
+  # @example Find out which service provider will track a valid FedEx number
+  #   include Trackerific
+  #   tracking_service "183689015000001" # => Trackerific::FedEx
+  # @api public
   def tracking_service(package_id)
     case package_id
       when /^.Z/, /^[HK].{10}$/ then Trackerific::UPS

data/lib/trackerific_details.rb

@@ -3,26 +3,45 @@ module Trackerific
   # a summary, and the events.
   class Details
     # Provides a new instance of Details
-    # @param [String] the package identifier
-    # @param [String] a summary of the tracking status
-    # @param [Array, Trackerific::Event] the tracking events
+    # @param [String] package_id the package identifier
+    # @param [String] summary a summary of the tracking status
+    # @param [Array, Trackerific::Event] events the tracking events
+    # @api private
     def initialize(package_id, summary, events)
       @package_id = package_id
       @summary = summary
       @events = events
     end
     
+    # Read-only string for the package identifier
+    # @example Get the id of a tracked package
+    #   details.package_id # => the package identifier
     # @return [String] the package identifier
+    # @api public
     def package_id
       @package_id
     end
     
+    # Read-only string for the summary of the package's tracking events
+    # @example Get the summary of a tracked package
+    #   details.summary # => Summary of the tracking events (i.e. Delivered)
     # @return [String] a summary of the tracking status
+    # @api public
     def summary
       @summary
     end
     
+    # Read-only string for the events for this package
+    # @example Print all the events for a tracked package
+    #   puts details.events
+    # @example Get the date the package was shipped
+    #   details.events.last.date # => a DateTime value
+    # @example A bulleted HTML list of the events (most current on top) in haml
+    #   %ul
+    #     - details.events.each do |event|
+    #       %li= event
     # @return [Array, Trackerific::Event] the tracking events
+    # @api public
     def events
       @events
     end

data/lib/trackerific_event.rb

@@ -2,32 +2,52 @@ module Trackerific
   # Provides details for a tracking event
   class Event
     # Provides a new instance of Event
-    # @param [Time] the date / time of the event
-    # @param [String] the event's description
-    # @param [String] where the event took place
+    # @param [Time] date the date / time of the event
+    # @param [String] description the event's description
+    # @param [String] location where the event took place
+    # @api private
     def initialize(date, description, location)
       @date = date
       @description = description
       @location = location
     end
     
-    # @return [Time] the date / time of the event
+    # The date and time of the event
+    # @example Get the date of an event
+    #   date = details.events.first.date
+    # @return [DateTime]
+    # @api public
     def date
       @date
     end
     
-    # @return [String] the event's description.
+    # The event's description
+    # @example Get the description of an event
+    #   description = details.events.first.description
+    # @return [String]
+    # @api public
     def description
       @description
     end
     
-    # @return [String] where the event took place (usually in City State Zip
-    #   format)
+    # Where the event took place (usually in City State Zip format)
+    # @example Get the location of an event
+    #   location = details.events.first.location
+    # @return [String]
+    # @api public
     def location
       @location
     end
     
+    # Converts the event into a string
+    # @example Get a human-readable string from an event
+    #   event = details.event.to_s
+    # @example A bulleted list of events in haml
+    #   %ul
+    #     - details.events.each do |event|
+    #     %li= event
     # @return [String] converts the event into a string
+    # @api public
     def to_s
       dte = self.date.strftime('%b %d %I:%M %P')
       des = self.description