lib/usps.rb in trackerific-0.3.1 vs lib/usps.rb in trackerific-0.3.2

@@ -4,38 +4,39 @@
   require 'builder'
   require 'httparty'
   
   # Provides package tracking support for USPS.
   class USPS < Base
+    # setup HTTParty
     include HTTParty
     format :xml
+    # use the test site for Rails development, production for everything else
     base_uri defined?(Rails) ? case Rails.env
       when 'test', 'development' then 'http://testing.shippingapis.com'
       when 'production' then 'https://secure.shippingapis.com'
     end : 'https://secure.shippingapis.com'
     
-    def initialize(options = {})
-      super
-      @options = options
-    end
-    
-    # The required option for tracking a UPS package is :user_id
-    #
-    # @return [Array] the required options for tracking a UPS package.
-    def required_options
-      [:user_id]
-    end
-    
-    # Tracks a USPS package.
-    # A Trackerific::Error is raised when a package cannot be tracked.
+    # Tracks a USPS 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
+    #   usps = Trackerific::USPS.new user_id: 'user'
+    #   details = ups.track_package("EJ958083578US")
+    # @api public    
     def track_package(package_id)
       super
+      # connect to the USPS shipping API via HTTParty
       response = self.class.get('/ShippingAPITest.dll', :query => {:API => 'TrackV2', :XML => build_xml_request}.to_query)
+      # throw any HTTP errors
       response.error! unless response.code == 200
+      # raise a Trackerific::Error if there is an error in the response, or if the
+      # tracking response is malformed
       raise Trackerific::Error, response['Error']['Description'] unless response['Error'].nil?
       raise Trackerific::Error, "Tracking information not found in response from server." if response['TrackResponse'].nil?
+      # get the tracking information from the response, and convert into a
+      # Trackerific::Details
       tracking_info = response['TrackResponse']['TrackInfo']
       details = []
       tracking_info['TrackDetail'].each do |d|
         # each tracking detail is a string in this format:
         # MM DD HH:MM am/pm DESCRIPTION CITY STATE ZIP.
@@ -45,27 +46,39 @@
         d = d.split(" ")
         date = DateTime.parse(d[0..3].join(" "))
         desc = d[4..d.length].join(" ")
         details << Trackerific::Event.new(date, desc, "")
       end
+      # return the details
       Trackerific::Details.new(
         tracking_info['ID'],
         tracking_info['TrackSummary'],
         details
       )
     end
     
     protected
     
-    # Parses the response from UPS
-    # @return [Trackerific::Details]
+    # The required options for tracking a UPS package
+    # @return [Array] the required options for tracking a UPS package.
+    # @api private
+    def required_options
+      [:user_id]
+    end
+    
+    # Builds an XML request to send to USPS
+    # @return [String] the xml request
+    # @api private
     def build_xml_request
-      tracking_request = ""
-      builder = ::Builder::XmlMarkup.new(:target => tracking_request)
+      xml = ""
+      # set up the Builder
+      builder = ::Builder::XmlMarkup.new(:target => xml)
+      # build the request
       builder.TrackRequest(:USERID => @options[:user_id]) do |t|
         t.TrackID(:ID => @package_id)
       end
-      return tracking_request
+      # return the XML
+      xml
     end
     
   end
   
 end