completelynovel-amazon-product-advertising-api 0.0.4 → 0.0.5

data/Rakefile

@@ -0,0 +1,12 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Generate documentation for the amazon-product-advertising-api gem.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'AmazonProductAdvertisingApi'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/amazon-product-advertising-api.gemspec

@@ -2,15 +2,15 @@
 
 Gem::Specification.new do |s|
   s.name = %q{amazon-product-advertising-api}
-  s.version = "0.0.4"
+  s.version = "0.0.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors           = ["Jon Gilbraith"]
   s.date              = %q{2009-06-11}
   s.description       = %q{A nice rubyish interface to the Amazon Product Advertising API, formerly known as the Associates Web Service and before that the Amazon E-Commerce Service.}
   s.email             = %q{jon@completelynovel.com}
-  s.files             = ["EXAMPLE.txt", "MIT-LICENSE", "README.rdoc", "amazon-product-advertising-api.gemspec", "lib/amazon_product_advertising_api", "lib/amazon_product_advertising_api/base.rb", "lib/amazon_product_advertising_api/operations", "lib/amazon_product_advertising_api/operations/base.rb", "lib/amazon_product_advertising_api/operations/browse_node.rb", "lib/amazon_product_advertising_api/operations/item.rb", "lib/amazon_product_advertising_api/support.rb", "lib/amazon_product_advertising_api.rb"]
-  s.has_rdoc          = false
+  s.files             = ["Rakefile", "EXAMPLE.txt", "MIT-LICENSE", "README.rdoc", "amazon-product-advertising-api.gemspec", "lib/amazon_product_advertising_api", "lib/amazon_product_advertising_api/base.rb", "lib/amazon_product_advertising_api/operations", "lib/amazon_product_advertising_api/operations/base.rb", "lib/amazon_product_advertising_api/operations/browse_node.rb", "lib/amazon_product_advertising_api/operations/item.rb", "lib/amazon_product_advertising_api/support.rb", "lib/amazon_product_advertising_api.rb"]
+  s.has_rdoc          = true
   s.homepage          = %q{http://github.com/completelynovel/amazon-product-advertising-api}
   s.rdoc_options      = ["--inline-source", "--charset=UTF-8"]
   s.require_paths     = ["lib"]

data/lib/amazon_product_advertising_api/base.rb

@@ -1,5 +1,13 @@
-module AmazonProductAdvertisingApi
+module AmazonProductAdvertisingApi #:nodoc:
   
+  # This is the main base class where you define your config data. Setup like so:
+  #   AmazonProductAdvertisingApi.base.access_key_id = <your Amazon AccessKeyId>
+  # There is no support for the secret key yet, so it's just your access key for now.
+  #
+  # You also setup your Associates codes for different regions here (the right one is supplied)
+  # based on what region you are requesting for.
+  #   AmazonProductAdvertisingApi.base.associate_ids.ca = <your associates CA Affiliate key>
+  #   AmazonProductAdvertisingApi.base.associate_ids.uk = <your associates UK Affiliate key>
   class Base
     
     cattr_accessor :access_key_id

data/lib/amazon_product_advertising_api/operations/base.rb

@@ -1,23 +1,43 @@
-module AmazonProductAdvertisingApi
-  module Operations
-    module Base
+module AmazonProductAdvertisingApi #:nodoc:
+  module Operations #:nodoc:
+    module Base #:nodoc:
       
+      # This is the parent class of any Operations performed.
+      #
+      # Each class should have a constant defined called REQUEST_PARAMETERS which contains the available parameters
+      # as defined in the API docs.  Each class should also override the parse method with a custom version to suit the
+      # particular pattern of XML returned for it.
+      #
+      # Subclasses should also override initialize to take any parameters the API defines as required, and follow the pattern
+      # of the region being the last parameter.
+      #
+      # Before doing that though it should call super back to this one.
       class Request
-    
+        
+        # String - Amazon API calls can be sent to any of 6 regions, so this defines which one.
+        # It'll also use this data to pick the right Associates key to use.
         attr_accessor :region
-    
+        
+        # String - The name of the Operation you want to perform, i.e. ItemSearch, ItemLookup, etc.
         attr_accessor :operation
         
+        # String - This stores the request that gets sent to Amazon (for investigation if you want to look under the covers).
         attr_accessor :request_uri
-    
+        
+        # String - This stores the raw data of the request response (again, for investigation if you want to look under the covers).
         attr_accessor :raw_data
-    
+        
+        # Hpricot - This stores the raw data of the request response should you feel the need / desire to do some parsing yourself.
         attr_accessor :hpricot_data
-    
+        
+        # Element - This is the root of the structure that the lib assembles from the data when parsed.
         attr_accessor :response
         
+        # Boolean - All responses have a field saying whether the request was valid. Note that this refers to the format of the request, etc
+        # and not errors with the request parameters, etc. I.e. a lookup for an item that doesn't exsist is still valid.
         attr_accessor :is_valid
         
+        # Array of Struct - Any errors will be added to this attribute and each has an attribute of code or message.
         attr_accessor :errors
     
         SERVICE_URLS = {
@@ -33,7 +53,8 @@ module AmazonProductAdvertisingApi
           self.response = AmazonProductAdvertisingApi::Operations::Base::Element.new
           self.errors   = []
         end
-    
+        
+        # This takes care of building request, performing it, storing the results, checking for errors then parsing the data (if the request was valid).
         def query_amazon(params)
           request_params = {}
           request_params["AWSAccessKeyId"] = AmazonProductAdvertisingApi::Base.access_key_id
@@ -67,10 +88,12 @@ module AmazonProductAdvertisingApi
           self.is_valid ? self.response : false
         end
         
+        # The parse method of a request should be overwritted by any subclasses to account for different patterns in the XML.
         def parse
           raise "This should be being overridden by it's subclass to provide custom parsing for the particular operation concerned."
         end
         
+        # Launches the request's query to Amazon (via query_amazon).
         def run
           self.query_amazon(params)
         end
@@ -88,6 +111,12 @@ module AmazonProductAdvertisingApi
         
       end
       
+      # XML data that is returned by Amazon gets built into a tree of nodes, which are made up of instances of this class.
+      # They represent the 'response element' entity within the API docs.
+      #
+      # As well as various having attributes it can also contain a collection and behave like an array.
+      #
+      # I think I might have got a bit confused with all this, will come back to this shortly to check.
       class Element
         
         include Enumerable
@@ -96,6 +125,7 @@ module AmazonProductAdvertisingApi
           @contained_elements = []
         end
         
+        # Defines a new accessor on the element and if supplied assigns that attribute a value.
         def add_element(name, value = nil)
           name = name.underscore
 
@@ -117,24 +147,29 @@ module AmazonProductAdvertisingApi
           self.instance_eval("self.#{name}")
         end
         
+        # Add an item to the element's internal collection.
         def << element
           @contained_elements << element
         end
         
+        # Iterate over the element's internal collection.
         def each(&block)
           @contained_elements.each do |element|
             yield element
           end
         end
         
+        # Return the value of the internal collection's element at the given position.
         def [] position
           @contained_elements[position]
         end
         
+        # Return the first element of the internal collection.
         def first
           @contained_elements.first
         end
         
+        # Return the number of elements in the internal collection.
         def size
           @contained_elements.size
         end

data/lib/amazon_product_advertising_api/operations/browse_node.rb

@@ -1,7 +1,8 @@
-module AmazonProductAdvertisingApi
-  module Operations
-    module BrowseNode
+module AmazonProductAdvertisingApi #:nodoc:
+  module Operations #:nodoc:
+    module BrowseNode #:nodoc:
       
+      # A class to represent the BrowseNodeLookup Operation. See AmazonProductAdvertisingApi::Operations::Base::Request for info relating to all Requests.
       class BrowseNodeLookup < AmazonProductAdvertisingApi::Operations::Base::Request
         
         REQUEST_PARAMETERS = :browse_node_id, :response_group
@@ -9,7 +10,8 @@ module AmazonProductAdvertisingApi
         REQUEST_PARAMETERS.each do |param|
           self.send(:attr_accessor, param)
         end
-
+        
+        # BrowseNodeLookup only requires a browse_node_id to be specified.
         def initialize(browse_node_id, region = :uk)
           super()
 
@@ -18,6 +20,7 @@ module AmazonProductAdvertisingApi
           self.region         = region
         end
         
+        # BrowseNode methods return xml consisting of a BrowseNodes tag with several BrowseNode tags inside.
         def parse
           self.response.add_element("BrowseNodes", AmazonProductAdvertisingApi::Operations::Base::Element.new)
 
@@ -29,7 +32,7 @@ module AmazonProductAdvertisingApi
             queue << [new_element, element.containers]
             
             queue.each do |pair|
-              current_element    = pair[0]
+              current_element  = pair[0]
               current_children = pair[1]
           
               current_children.each do |child|
@@ -51,6 +54,8 @@ module AmazonProductAdvertisingApi
         end
         
         private
+          # This simply looks at the defined parameters and creates a hash of the ones that have values assigned.
+          # Need to work out a way of doing this so I don't need to keep defining exactly the same method in each class.
           def params
             REQUEST_PARAMETERS.inject({}) do |parameters, parameter|
               parameters[parameter] = eval("self.#{parameter}") unless eval("self.#{parameter}.nil?")

data/lib/amazon_product_advertising_api/operations/item.rb

@@ -1,9 +1,11 @@
-module AmazonProductAdvertisingApi
-  module Operations
-    module Item
+module AmazonProductAdvertisingApi #:nodoc:
+  module Operations #:nodoc:
+    module Item #:nodoc:
       
+      # Gets mixed into each of the classes in AmazonProductAdvertisingApi::Operations::Item for common behaviours.
       module Common
         
+        # Item methods return xml consisting of an Items tag with several Item tags inside.
         def parse
           self.response.add_element("Items", AmazonProductAdvertisingApi::Operations::Base::Element.new)
 
@@ -38,6 +40,9 @@ module AmazonProductAdvertisingApi
         
       end
       
+      # A class to represent the ItemSearch Operation. See AmazonProductAdvertisingApi::Operations::Base::Request for info relating to all Requests.
+      #
+      # It mixes in AmazonProductAdvertisingApi::Operations::Item::Common for it's parse method.
       class ItemSearch < AmazonProductAdvertisingApi::Operations::Base::Request
         
         include Common
@@ -51,7 +56,8 @@ module AmazonProductAdvertisingApi
         REQUEST_PARAMETERS.each do |param|
           self.send(:attr_accessor, param)
         end
-
+        
+        # ItemSearch requires keywords and a search index to be specified.
         def initialize(keywords, search_index = "Books", region = :uk)
           super()
 
@@ -62,6 +68,8 @@ module AmazonProductAdvertisingApi
         end
       
         private
+          # This simply looks at the defined parameters and creates a hash of the ones that have values assigned.
+          # Need to work out a way of doing this so I don't need to keep defining exactly the same method in each class.
           def params
             REQUEST_PARAMETERS.inject({}) do |parameters, parameter|
               parameters[parameter] = eval("self.#{parameter}") unless eval("self.#{parameter}.nil?")
@@ -71,6 +79,9 @@ module AmazonProductAdvertisingApi
       
       end
       
+      # A class to represent the ItemLookup Operation. See AmazonProductAdvertisingApi::Operations::Base::Request for info relating to all Requests.
+      #
+      # It mixes in AmazonProductAdvertisingApi::Operations::Item::Common for it's parse method.
       class ItemLookup < AmazonProductAdvertisingApi::Operations::Base::Request
         
         include Common
@@ -82,6 +93,7 @@ module AmazonProductAdvertisingApi
           self.send(:attr_accessor, param)
         end
         
+        # ItemLookup only requires an item id (ASIN) to be specified.
         def initialize(item_id, region = :uk)
           super()
           
@@ -91,6 +103,8 @@ module AmazonProductAdvertisingApi
         end
       
         private
+          # This simply looks at the defined parameters and creates a hash of the ones that have values assigned.
+          # Need to work out a way of doing this so I don't need to keep defining exactly the same method in each class.
           def params
             REQUEST_PARAMETERS.inject({}) do |parameters, parameter|
               parameters[parameter] = eval("self.#{parameter}") unless eval("self.#{parameter}.nil?")
@@ -99,7 +113,12 @@ module AmazonProductAdvertisingApi
           end
           
       end
-
+      
+      # A class to represent the SimilarityLookup Operation. See AmazonProductAdvertisingApi::Operations::Base::Request for info relating to all Requests.
+      #
+      # Despite not following the same naming convention of other classes in this module, it returns data structured the same way so has been put here.
+      #
+      # It mixes in AmazonProductAdvertisingApi::Operations::Item::Common for it's parse method.
       class SimilarityLookup < AmazonProductAdvertisingApi::Operations::Base::Request
         
         include Common
@@ -110,6 +129,7 @@ module AmazonProductAdvertisingApi
           self.send(:attr_accessor, param)
         end
         
+        # SimilarityLookup only requires an item id (ASIN) to be specified.
         def initialize(item_id, region = :uk)
           super()
           
@@ -119,6 +139,8 @@ module AmazonProductAdvertisingApi
         end
       
         private
+          # This simply looks at the defined parameters and creates a hash of the ones that have values assigned.
+          # Need to work out a way of doing this so I don't need to keep defining exactly the same method in each class.
           def params
             REQUEST_PARAMETERS.inject({}) do |parameters, parameter|
               parameters[parameter] = eval("self.#{parameter}") unless eval("self.#{parameter}.nil?")

data/lib/amazon_product_advertising_api/support.rb

@@ -1,6 +1,9 @@
-module AmazonProductAdvertisingApi
+module AmazonProductAdvertisingApi #:nodoc:
   
+  # Some extensions to the Class class.
   class Class
+    
+    # Pleasant syntax for Class attribute readers.
     def cattr_reader(sym)
       class_eval(<<-EOS, __FILE__, __LINE__)
         unless defined? @@#{sym}  # unless defined? @@hair_colors
@@ -17,6 +20,7 @@ module AmazonProductAdvertisingApi
       EOS
     end
 
+    # Pleasant syntax for Class attribute writers.
     def cattr_writer(sym)
       class_eval(<<-EOS, __FILE__, __LINE__)
         unless defined? @@#{sym}                       # unless defined? @@hair_colors
@@ -29,6 +33,7 @@ module AmazonProductAdvertisingApi
       EOS
     end
 
+    # Pleasant syntax for Class attribute accessors.
     def cattr_accessor(sym)
       cattr_reader(sym)
       cattr_writer(sym)
@@ -36,8 +41,10 @@ module AmazonProductAdvertisingApi
 
   end
 
+  # Some extensions to the String class.
   class String
 
+    # Converts strings from under_score format to CamelCase
     def camelize(first_letter_in_uppercase = true)
       if first_letter_in_uppercase
         self.to_s.gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
@@ -46,6 +53,7 @@ module AmazonProductAdvertisingApi
       end
     end
 
+    # Converts strings from CamelCase format to under_score.
     def underscore
       self.to_s.gsub(/::/, '/').
         gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: completelynovel-amazon-product-advertising-api
 version: !ruby/object:Gem::Version 
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors: 
 - Jon Gilbraith
@@ -22,6 +22,7 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- Rakefile
 - EXAMPLE.txt
 - MIT-LICENSE
 - README.rdoc
@@ -34,7 +35,7 @@ files:
 - lib/amazon_product_advertising_api/operations/item.rb
 - lib/amazon_product_advertising_api/support.rb
 - lib/amazon_product_advertising_api.rb
-has_rdoc: false
+has_rdoc: true
 homepage: http://github.com/completelynovel/amazon-product-advertising-api
 post_install_message: 
 rdoc_options: