flickrmocks 0.9.0 → 0.9.1

data/lib/flickr_mocks/api/api.rb

@@ -17,6 +17,7 @@ module FlickrMocks
       :tag_mode => 'any',
       :possible_tag_modes => ['any','all'],
       :possible_sizes => [:square, :thumbnail, :small, :medium, :medium_640, :large, :original],
+      :usable_licenses => [4,5,6,7]
     }
 
     class << self
@@ -33,10 +34,13 @@ module FlickrMocks
     #  Api.photos(:search_terms => 'france') 
     # Options hash accepts:
     #   :search_terms : string with comma separated list of terms 'france,lyon'
-    #   :owner_id : pptional string containing the id for the owner of the photo.
-    #   :per_page : optional string containing the maximum number of photos returned in a single page. The default value is '200'
-    #   :page : optional string containing the page for search results to be returned. The default is '1'
-    #   :tag_mode : optionsl string containing either 'any' or 'all'. Affects the interpretation of the search terms to the FlickRaw API.
+    #   :owner_id : optional string containing the id for the owner of the photo.
+    #   :per_page : optional string containing the maximum number of photos
+    #                returned in a single page. The default value is '200'
+    #   :page : optional string containing the page for search results to be
+    #            returned. The default is '1'
+    #   :tag_mode : optionsl string containing either 'any' or 'all'. Affects the
+    #                interpretation of the search terms to the FlickRaw API.
     def self.photos(options)
       raise ArgumentError.new("Expecting a Hash argument.") unless options.is_a?(Hash)
       photos = Api::Flickr.photos(options)
@@ -48,7 +52,8 @@ module FlickrMocks
     #  Api.photo_details(:photo_id => '1234'
     # Options hash accepts:
     #   :photo_id : required string that contains the id for the photo
-    #   :secret  : optional string that contains the flickr secret for photo. When provided query is slightly faster
+    #   :secret  : optional string that contains the flickr secret for photo.
+    #               When provided query is slightly faster
     def self.photo_details(options)
       raise ArgumentError.new("Expecting a Hash argument.") unless options.is_a?(Hash)
       photo = Api::Flickr.photo(options)
@@ -61,7 +66,8 @@ module FlickrMocks
     #  Api.photo(:photo_id => '1234')
     # Options hash accepts:
     #   :photo_id : required string that contains the id for the photo
-    #   :secret  : optional string that contains the flickr secret for photo. When provided query is slightly faster
+    #   :secret  : optional string that contains the flickr secret for photo.
+    #               When provided query is slightly faster
     def self.photo(options)
       raise ArgumentError.new("Expecting a Hash argument") unless options.is_a?(Hash)
       Models::Photo.new Api::Flickr.photo(options)
@@ -72,7 +78,8 @@ module FlickrMocks
     #  Api.photo_sizes(:photo_id => '1234')
     # Options hash accepts:
     #   :photo_id : required string that contains the id for the photo
-    #   :secret  : optional string that contains the flickr secret for photo. When provided query is slightly faster
+    #   :secret  : optional string that contains the flickr secret for photo.
+    #               When provided query is slightly faster
     def self.photo_sizes(options)
       raise ArgumentError.new("Expecting a Hash argument") unless options.is_a?(Hash)
       Models::PhotoSizes.new Api::Flickr.photo_sizes(options)
@@ -83,8 +90,10 @@ module FlickrMocks
     #  Api.interesting_photos(:date => '2000-01-01'
     # Options hash accepts:
     #  :date : string with date in the format yyyy-mm-dd
-    #  :per_page : optional string containing the maximum number of photos returned in a single page. The default value is '200'
-    #  :page : optional string containing the page for search results to be returned. The default is '1'
+    #  :per_page : optional string containing the maximum number of photos
+    #               returned in a single page. The default value is '200'
+    #  :page : optional string containing the page for search results to be
+    #           returned. The default is '1'
     def self.interesting_photos(options)
       raise ArgumentError.new("Expecting a Hash argument") unless options.is_a?(Hash)
       photos = Api::Flickr.interestingness(options)
@@ -95,8 +104,10 @@ module FlickrMocks
     # Sample usage:
     #  Api.commons_institutions({})
     # Options hash accepts:
-    #  :per_page : optional string containing the maximum number of photos returned in a single page. The default value is '200'
-    #  :page : optional string containing the page for search results to be returned. The default is '1'
+    #  :per_page : optional string containing the maximum number of photos returned
+    #               in a single page. The default value is '200'
+    #  :page : optional string containing the page for search results to be returned.
+    #           The default is '1'
     def self.commons_institutions(options)
       raise ArgumentError.new("Expecting a Hash argument") unless options.is_a?(Hash)
       institutions = Api::Flickr.commons_institutions

data/lib/flickr_mocks/api/flickr.rb

@@ -9,9 +9,12 @@ module FlickrMocks
       # Options hash accepts:
       #  :search_terms : string with comma separated list of terms 'france,lyon'
       #  :owner_id : pptional string containing the id for the owner of the photo.
-      #  :per_page : optional string containing the maximum number of photos returned in a single page. The default value is '200'
-      #  :page : optional string containing the page for search results to be returned. The default is '1'
-      #  :tag_mode : optionsl string containing either 'any' or 'all'. Affects the interpretation of the search terms to the FlickRaw API.
+      #  :per_page : optional string containing the maximum number of photos
+      #  returned in a single page. The default value is '200'
+      #  :page : optional string containing the page for search
+      #           results to be returned. The default is '1'
+      #  :tag_mode : optionsl string containing either 'any' or 'all'.
+      #               Affects the interpretation of the search terms to the FlickRaw API.
       def self.photos(options)
         flickr.photos.search Api::Options.search(options)
       end
@@ -22,7 +25,8 @@ module FlickrMocks
       #
       # Options hash accepts:
       #  :photo_id : required string that contains the id for the photo
-      #  :secret  : optional string that contains the flickr secret for photo. When provided query is slightly faster
+      #  :secret  : optional string that contains the flickr secret for photo.
+      #              When provided query is slightly faster
       def self.photo(options)
         flickr.photos.getInfo Api::Options.photo(options)
       end
@@ -33,7 +37,8 @@ module FlickrMocks
       #
       # Options hash accepts:
       #  :photo_id : required string that contains the id for the photo
-      #  :secret  : optional string that contains the flickr secret for photo. When provided query is slightly faster
+      #  :secret  : optional string that contains the flickr secret for photo.
+      #              When provided query is slightly faster
       def self.photo_sizes(options)
         flickr.photos.getSizes Api::Options.photo(options)
       end

data/lib/flickr_mocks/api/options.rb

@@ -8,11 +8,16 @@ module FlickrMocks
       #   self.search(:search_terms => 'iran', :tag_mode => 'any')
       #
       # Accepted options include:
-      #  :search_terms : comma string containing the flickr search tags. Sample string 'lyon,france"
-      #  :owner_id : id for the photo. (either :owner_id or :search_terms must be specified
-      #  :per_page : optional string containing the maximum number of items to return for a given page
-      #  :page : optional string containing page number for the results. When page number is <= 0, it returns 1.
-      #  :tag_mode : optional string containing how the tags for :search_terms should be interpreted. Can be either 'any' or 'all'
+      #  :search_terms : comma string containing the flickr search tags. Sample
+      #                   string 'lyon,france"
+      #  :owner_id : id for the photo. (either :owner_id or :search_terms
+      #               must be specified
+      #  :per_page : optional string containing the maximum number of items to
+      #               return for a given page
+      #  :page : optional string containing page number for the results. When
+      #           page number is <= 0, it returns 1.
+      #  :tag_mode : optional string containing how the tags for :search_terms
+      #               should be interpreted. Can be either 'any' or 'all'
       def self.search(params)
         return {
           :tags => Api::Sanitize.tags(params[:search_terms]),
@@ -27,14 +32,18 @@ module FlickrMocks
       end
 
       
-      # returns parameter hash that is supplied for a interesting photo search. Sample usage:
+      # returns parameter hash that is supplied for a interesting photo search.
+      # Sample usage:
       #
       #   self.interesting(:date => '2010-10-10')
       #
       # Accepted options include:
-      #  :date : string of format 'YYYY-MM-DD'. Photos of this date are retrieved. If none supplied, yesterday's date is used.
-      #  :per_page : optional string containing the maximum number of items to return for a given page
-      #  :page : optional string containing page number for the results. When page number is <= 0, it returns 1.
+      #  :date : string of format 'YYYY-MM-DD'. Photos of this date are retrieved.
+      #           If none supplied, yesterday's date is used.
+      #  :per_page : optional string containing the maximum number of items to
+      #               return for a given page
+      #  :page : optional string containing page number for the results. When page
+      #           number is <= 0, it returns 1.
       #
       def self.interesting(params)
         return {
@@ -51,9 +60,12 @@ module FlickrMocks
       #
       # Accepted options include:
       #  :photo_id : string containing photo_id of the photo.
-      #  :id : string containing photo id of the photo. It is an alias for :photo_id. If both are present :photo_id takes precedance.
-      #  :secret : optional string containing the secret for the photo. If supplied the query is slightly faster.
-      #  :photo_secret : optional string containing the secret for the photo. It is an alias for :secret. If both supplied, :secret takes precedance.
+      #  :id : string containing photo id of the photo. It is an alias for :photo_id.
+      #         If both are present :photo_id takes precedance.
+      #  :secret : optional string containing the secret for the photo. If supplied
+      #             the query is slightly faster.
+      #  :photo_secret : optional string containing the secret for the photo. It
+      #                   is an alias for :secret. If both supplied, :secret takes precedance.
       def self.photo(params)
         {
           :photo_id => params[:photo_id] || params[:id] || nil,
@@ -61,14 +73,17 @@ module FlickrMocks
         }
       end
 
-      # returns parameter hash used for searching for photos of a given author.  Sample usage:
+      # returns parameter hash used for searching for photos of a given author.
+      # Sample usage:
       #
       #   self.search(:owner_id => '1234')
       #
       # Accepted options include:
       #  :owner_id : id for the photo. (either :owner_id or :search_terms must be specified
-      #  :per_page : optional string containing the maximum number of items to return for a given page
-      #  :page : optional string containing page number for the results. When page number is <= 0, it returns 1.
+      #  :per_page : optional string containing the maximum number of items to return
+      #               for a given page
+      #  :page : optional string containing page number for the results. When
+      #           page number is <= 0, it returns 1.
       def self.author(params)
         options = Api::Options.search(params)
         options.delete :tags

data/lib/flickr_mocks/api/sanitize.rb

@@ -3,7 +3,8 @@ module FlickrMocks
     # helper methods that help to clean up user supplied values. Module is
     # used internally.
     module Sanitize
-      # returns a lowercase stripped version of the supplied comma separated string. Sample usage:
+      # returns a lowercase stripped version of the supplied comma separated string.
+      # Sample usage:
       #
       #  Api.sanitize_tags('Shiraz  , HeLLo goodbye, wow')
       #  returns 'shiraz,hello goodbye,wow'
@@ -18,8 +19,8 @@ module FlickrMocks
         end
       end
 
-      # returns lowercase stripped version of the supplied string stored in the :search_terms key of the
-      # supplied hash. Sample usage:
+      # returns lowercase stripped version of the supplied string stored in the
+      # :search_terms key of the supplied hash. Sample usage:
       #
       #  self.sanitize_tags(:search_terms => 'Shiraz  , HeLLo goodbye, wow')
       #  returns 'shiraz,hello goodbye,wow'
@@ -62,7 +63,8 @@ module FlickrMocks
       end
 
       # returns the page number. Ensures that return value is string containing an integer
-      # greater than 0. When nonsensical page supplied, default page '1' is returned. Sample usage:
+      # greater than 0. When nonsensical page supplied, default page '1' is returned.
+      # Sample usage:
       #
       #   self.page('20')
       #   returns '20'
@@ -79,7 +81,8 @@ module FlickrMocks
         end
       end
 
-      # returns the page number contained in the :page key of the supplied hash. Sample usage:
+      # returns the page number contained in the :page key of the supplied hash.
+      # Sample usage:
       #
       #  self.page(:page => '20')
       #  returns '20'
@@ -104,7 +107,8 @@ module FlickrMocks
         end
       end
 
-      # returns tag_mode contained in the :tag_mode key of the supplied hash. Sample usage:
+      # returns tag_mode contained in the :tag_mode key of the supplied hash.
+      # Sample usage:
       #
       #   self.tag_mode(:tag_mode => 'any')
       #   returns 'any'

data/lib/flickr_mocks/models/commons_institution.rb

@@ -42,8 +42,7 @@ module FlickrMocks
         @delegated_to_object == other.instance_eval('@delegated_to_object')
       end
 
-      # customizes the cloning behavior of the object. Internal state of cloned object
-      # will not point to original object. 
+      # compares value for internal state rather than object_id
       def initialize_copy(orig) 
         super
         @delegated_to_object = @delegated_to_object.clone

data/lib/flickr_mocks/models/commons_institutions.rb

@@ -6,6 +6,7 @@ module FlickrMocks
 
       class << self
         attr_writer :defaults
+        # returns defaults hash for the class
         def defaults
           @defaults ||= FlickrMocks::Models::Helpers.paging_defaults().clone
           @defaults
@@ -28,43 +29,46 @@ module FlickrMocks
         Api::Sanitize.page(options[:current_page] || options[:page])
       end
 
-      # returns the default value stored in the
+      # returns the default value for a given symbol. The recognized defaults are:
+      #  :per_page
+      #  :current_page
+      #  :max_entries
       def default(value)
         CommonsInstitutions.defaults[value.to_s.to_sym]
       end
 
+      # compares value for internal state rather than object_id
       def ==(other)
         per_page == other.per_page and
           current_page == other.current_page and
           @delegated_to_object == other.instance_eval('@delegated_to_object')
       end
 
-      def initialize_copy(orig)
-        super
-        @delegated_to_object = @delegated_to_object.clone
-      end
-
+      # returns the list of methods that are delegated by object
       def delegated_instance_methods
         FlickrMocks::Models::Helpers.array_accessor_methods
       end
 
+      # delegates methods that are returned by delegated instance method
       def method_missing(id,*args,&block)
         return @delegated_to_object.send(id,*args,&block) if delegated_instance_methods.include?(id)
         super
       end
 
       alias :old_respond_to? :respond_to?
+      # returns true for delegated and regular methods
       def respond_to?(method,type=false)
         return true if delegated_instance_methods.include?(method)
         old_respond_to?(method,type)
       end
 
       alias :old_methods :methods
+      # returns delegated methods as well as regular methods
       def methods
         delegated_instance_methods + old_methods
       end
 
-      # custom cloning methods
+      # custom cloning method that does a deep copy of the object's internal state
       def initialize_copy(orig)
         super
         @delegated_to_object = @delegated_to_object.map do |institution|
@@ -72,20 +76,25 @@ module FlickrMocks
         end
       end
 
+      # returns total number of institutions
       def total_entries
         @delegated_to_object.size
       end
 
+      # returns raw FlickRaw response for a commons institutions query
       def institutions
         @delegated_to_object
       end
 
+      # returns a collection of institutions that can be used directly for WillPaginate.
       def collection
         ::WillPaginate::Collection.create(current_page, per_page, total_entries) do |obj|
           start = (current_page-1)*per_page
           obj.replace(institutions[start, per_page])
         end
       end
+
+      
       private
       def delegated_to_object=(object)
         raise ArgumentError, "FlickRaw::ResponseList expected" unless object.class == FlickRaw::ResponseList

data/lib/flickr_mocks/models/photo.rb

@@ -7,40 +7,47 @@ module FlickrMocks
         @extended_photo = photo.methods.include?(:originalsecret)
       end
 
-      # Return urls for various sizes
+      # Return url for square sized photo
       def square
         FlickRaw.url_s self
       end
 
+      # returns url for original sized photo
       def original
         respond_to?(:originalsecret) ? FlickRaw.url_o(self) : nil
       end
 
+      # returns url for thumbnail sized photo
       def thumbnail
         FlickRaw.url_t self
       end
 
+      # returns url for small sized photo
       def small
         FlickRaw.url_m self
       end
 
+      # returns url for medium sized photo
       def medium
         FlickRaw.url self
       end
 
+      # returns url for large sized photo
       def large
         FlickRaw.url_b self
       end
 
+      # returns url for medium 640 sized photo
       def medium_640
         FlickRaw.url_z self
       end
 
+      # return url for copyright owner of photo
       def owner_url
         FlickRaw.url_photopage self
       end
 
-
+      # returns Flickr id for owner of photo
       def owner_id
         case owner
         when String then owner
@@ -50,28 +57,34 @@ module FlickrMocks
         end
       end
 
+      # returns Flickr id for photo
       def photo_id
         id
       end
 
+      # returns true if photo license can be used for commercial purposes
       def usable?
-        license.to_i > 3
+        FlickrMocks::Api.default(:usable_licenses).include?(license.to_i)
       end
 
+      # compares two objects by value rather than object_id
       def ==(other)
         @delegated_to_object == other.instance_eval('@delegated_to_object')
       end
 
+      # compares value for internal state rather than object_id
       def initialize_copy(orig)
         super
         @delegated_to_object = @delegated_to_object.clone
       end
-
+      
+      # returns the list of methods that are delegated by object
       def delegated_instance_methods
         @delegated_instance_methods
       end
 
-
+      # delegates methods that are returned by delegated instance method as well as method
+      # :'method 640'
       def method_missing(id,*args,&block)
         return @delegated_to_object.send(id,*args,&block) if delegated_instance_methods.include?(id)
         return medium_640 if id.to_sym == :'medium 640'
@@ -79,6 +92,7 @@ module FlickrMocks
       end
 
       alias :old_respond_to? :respond_to?
+      # returns true for delegated and regular methods
       def respond_to?(method,type=false)
         return true if method.to_sym == :'medium 640'
         return true if delegated_instance_methods.include?(method)
@@ -86,6 +100,7 @@ module FlickrMocks
       end
 
       alias :old_methods :methods
+      # returns delegated methods as well as regular methods
       def methods
         delegated_instance_methods + old_methods
       end

data/lib/flickr_mocks/models/photo_details.rb

@@ -9,36 +9,49 @@ module FlickrMocks
         raise ArgumentError 'owner id for photo did not match owner id for at least one size' unless valid_owner_for_dimensions?
       end
 
+      # returns the name of the author for the photo. When owner_name is not available
+      #  owner_username is returned.
       def author
         owner_name.empty? ? owner_username : owner_name
       end
 
+      # returns the owner name for the photo.
       def owner_name
         self.owner.realname
       end
-    
+
+      # returns the owner username for the photo
       def owner_username
         self.owner.username
       end
-    
+
+      # returns the array of PhotoSize objects available for the given photo
       def dimensions
         @dimensions
       end
 
-      def photo
-        @delegated_to_object
-      end
-
+      # returns the list of acceptable sizes for a photo. Not every photo will have
+      # all of these sizes.
       def possible_sizes
         FlickrMocks::Models::Helpers.possible_sizes
       end
 
+      # returns the raw FlicrkRaw response for the photo from flickr
+      def photo
+        @delegated_to_object
+      end
+
+      # compares the complete internal state of two PhotoDetails objects rather than simply
+      # comparing object_id's
       def ==(other)
         return false unless other.class == PhotoDetails
         (dimensions == other.dimensions) && (@delegated_to_object == other.instance_eval('@delegated_to_object'))
       end
 
       # metaprogramming methods
+
+      # delegates methods that are returned by delegated instance method. It also
+      # delegates array methods to the @dimensions object
       def method_missing(id,*args,&block)
         return dimensions.sizes.send(id,*args,&block) if array_accessor_methods.include?(id)
         return @delegated_to_object.send(id,*args,&block) if delegated_instance_methods.include?(id)
@@ -46,20 +59,23 @@ module FlickrMocks
       end
 
       alias :old_respond_to? :respond_to?
+      # returns true for delegated and regular methods
       def respond_to?(method,type=false)
         delegated_instance_methods.include?(method) || old_respond_to?(method)
       end
 
       alias :old_methods :methods
+      # returns delegated methods as well as regular methods
       def methods
         delegated_instance_methods + old_methods
       end
 
+      # returns list of methods that are delegated to other objects
       def delegated_instance_methods
         @delegated_to_object.delegated_instance_methods + array_accessor_methods + [:owner_id] + possible_sizes
       end
 
-      # custom cloning methods
+      # compares value for internal state rather than object_id
       def initialize_copy(orig)
         super
         @dimensions = @dimensions.clone

data/lib/flickr_mocks/models/photo_dimensions.rb

@@ -15,29 +15,42 @@ module FlickrMocks
         self.delegated_to_object = data
       end
 
+      # returns array of symbols for the sizes available for a given photo
       def available_sizes
         map do |dimension|
           dimension.size
         end
       end
 
+      # returns array of symbols for possible sizes of a given photo. Not every photo
+      # will have all of the returned sizes.
+      def possible_sizes
+        FlickrMocks::Models::Helpers.possible_sizes
+      end
+      
+      # returns the array of OpenStruct objects available for the given photo size
       def dimensions
         @delegated_to_object
       end
 
+      # returns a collection of photo sizes that can be used directly for WillPaginate.
       def collection
         @collection ||= ::WillPaginate::Collection.create(1, available_sizes.length, available_sizes.length) do |obj|
           obj.replace(dimensions)
         end
         @collection
       end
-    
+
+      # returns a string that encodes the size, width and height for the photo.
+      # Sample string returned would be:
+      #  "small:100x200,large:300x500"   --> ie small photo, width of 100 and lenght of 200 
       def to_s
         dimensions.map do  |dimension|
           [dimension.size,[dimension.width,dimension.height].join('x')].join(':')
         end.join(',')
       end
 
+      # compares value for internal state rather than object_id
       def ==(other)
         return false unless other.class.should == self.class
         to_s == other.to_s
@@ -45,10 +58,13 @@ module FlickrMocks
 
       # metaprogramming methods
       alias :old_respond_to? :respond_to?
+      
+      # returns true for delegated and regular methods
       def respond_to?(method)
         valid_size?(method) || delegated_instance_methods.include?(method) || old_respond_to?(method)
       end
 
+      # delegates methods that are returned by delegated instance method
       def method_missing(id,*args,&block)
         return get_size(id,*args,&block) if  valid_size?(id)
         return dimensions.send(id,*args,&block) if delegated_instance_methods.include?(id)
@@ -56,15 +72,17 @@ module FlickrMocks
       end
 
       alias :old_methods :methods
+      # returns delegated methods as well as regular methods
       def methods
         available_sizes + delegated_instance_methods + old_methods
       end
 
+      # returns the list of methods that are delegated by object
       def delegated_instance_methods
         Models::Helpers.array_accessor_methods
       end
     
-      # custom cloning methods
+      # compares value for internal state rather than object_id
       def initialize_copy(other)
         super
         @delegated_to_object = @delegated_to_object.map do |object|
@@ -72,9 +90,7 @@ module FlickrMocks
         end
       end
 
-      def possible_sizes
-        FlickrMocks::Models::Helpers.possible_sizes
-      end
+
       private
       def delegated_to_object=(data)
         raise(ArgumentError, "Invalid #{data} must respond to :to_s") unless data.respond_to?(:to_s)

data/lib/flickr_mocks/models/photo_search.rb

@@ -3,34 +3,38 @@ module FlickrMocks
     class PhotoSearch
       attr_reader :search_terms,:page,:date
 
-      @defaults =  {
-        :page => 1
-      }
-    
       @delegated_instance_methods = [:current_page, :per_page, :total_entries, :capped_entries,:perpage, :capped?,
         :max_entries, :collection]
 
       class << self
-        attr_accessor :defaults
         attr_accessor :delegated_instance_methods
       end
 
       def initialize(data,options={})
         self.delegated_to_object = data
-        self.search_terms = extract_search_terms(options)
-        self.page = extract_page(options)
-        self.date = extract_date(options)
+        @search_terms = extract_search_terms(options)
+        @page = extract_page(options).to_i
+        @date = extract_date(options)
       end
 
 
-      # returns the string stored in the :search_terms tag. The string is stripped
-      # of spurious spaces and is made to be lower case.
-      def extract_search_terms(params)
-        Api::Sanitize.tags(params[:search_terms])
+      # returns the string stored in the :search_terms key for the supplied 
+      # options hash.
+      # The string is stripped of non-required spaces and is made to be lower case.
+      # Sample usage:
+      #
+      #  extract_search_terms(:search_terms => 'Lyon , France'  --> 'lyon,france'
+      def extract_search_terms(options)
+        Api::Sanitize.tags(options[:search_terms])
       end
 
-      def extract_date(params)
-        date = params[:date]
+      # returns the date stored in the :date key for the supplied options hash.
+      # Values other than nil and strings of format 'YYYY-MM-DD' will raise an
+      # argument error. Sample usage:
+      #
+      #  extract_date(:date => '2010-10-10')    --> '2010-10-10'
+      def extract_date(options)
+        date = options[:date]
         case date
         when NilClass
           nil
@@ -41,30 +45,34 @@ module FlickrMocks
         end
       end
 
-      def extract_page(params)
-        Api::Sanitize.page(params[:page])
+      # returns the sanitized version of the value stored in the :page key for the
+      # supplied options hash. 
+      def extract_page(options)
+        Api::Sanitize.page(options[:page])
       end
 
-      # returns the default class instance value corresponding to the supplied key.
-      def default(value)
-        PhotoSearch.defaults[value.to_sym]
-      end
 
-      # returns the list of photo objects returned by search
+      # returns Photos object that contains information regarding the photos returned
+      # from Flickr
       def photos
         @delegated_to_object
       end
-    
+
+      # returns the total number of results available from Flickr for the given photo.
+      # note flickr only returns 4,000 maximum for a given query.
       def total_results
         total_entries
       end
 
+      # returns hash of parameters that were used for performing the query.
       def url_params
         { :search_terms => search_terms,
-          :date => (date.nil? && search_terms.empty?) ? Api::Helpers.date : date
+          :date => (date.nil? && (search_terms.nil? || search_terms.empty?)) ? Api::Helpers.date : date
         }.keep_if do |k,v|  !(v.nil? || v.to_s.empty?) end
       end
 
+      # compares the complete internal state of two PhotoDetails objects rather than simply
+      # comparing object_id's
       def ==(other)
         return false unless other.class == self.class
         (photos == other.photos) && [:search_terms,:page,:date].inject(true) do |state,method|
@@ -73,6 +81,9 @@ module FlickrMocks
       end
 
       # metaprogramming methods
+
+      # delegates methods that are returned by delegated instance method. It also
+      # delegates array methods to the @dimensions object
       def method_missing(id,*args,&block)
         return photos.photos.send(id,*args,&block)  if delegated_array_accessor_methods.include?(id)
         return photos.send(id,*args,&block) if delegated_instance_methods.include?(id)
@@ -80,21 +91,24 @@ module FlickrMocks
       end
 
       alias :old_respond_to? :respond_to?
+      # returns true for delegated and regular methods
       def respond_to?(method)
         delegated_instance_methods.include?(method) || old_respond_to?(method)
       end
 
       alias :old_methods :methods
+      # returns delegated methods as well as regular methods
       def methods
         delegated_instance_methods  + old_methods
       end
 
+      # returns list of methods that are delegated to other objects
       def delegated_instance_methods
         PhotoSearch.delegated_instance_methods + delegated_array_accessor_methods
       end
 
 
-      # custom cloning methods
+      # compares value for internal state rather than object_id
       def initialize_copy(other)
         super
         @delegated_to_object = @delegated_to_object.clone
@@ -111,28 +125,6 @@ module FlickrMocks
       
       end
 
-      def search_terms=(terms=nil)
-        terms ||= ''
-        raise ArgumentError, "Expecting String but got #{terms.class}" unless terms.is_a?(String)
-        @search_terms = terms
-      end
-
-      def page=(page=nil)
-        page ||= default(:page)
-        raise ArgumentError, "Expecting Fixnum but got #{page.class}" unless page.is_a?(Fixnum) or page.is_a?(String)
-        @page = page.to_i
-      end
-
-      def date=(date=nil)
-        raise ArgumentError, "Expecting String but got #{date.class}" unless date.is_a?(String) or date.nil?
-        begin
-          Chronic.parse(date) unless date.nil?
-        rescue
-          raise ArgumentError, "#{date} string can not be converted to Time object"
-        end
-        @date = date
-      end
-
       def delegated_array_accessor_methods
         FlickrMocks::Models::Helpers.array_accessor_methods
       end

data/lib/flickr_mocks/models/photo_size.rb

@@ -5,44 +5,55 @@ module FlickrMocks
         self.delegated_to_object= object
       end
 
+      # returns the string that contains the photo's size
       def size
         label.to_s.downcase.sub(/\s+/,'_')
       end
 
+      # returns the flickr id for the given photo
       def id
         source.split('/')[-1].split('_')[0]
       end
 
+      # returns the flickr secret for the given photo
       def secret
         source.split('/')[-1].split('_')[1]
       end
 
+      # compares the complete internal state of two PhotoDetails objects rather than simply
+      # comparing object_id's
       def ==(other)
         @delegated_to_object == other.instance_eval('@delegated_to_object')
       end
 
       # metaprogramming methods
+     
+      # returns list of methods that are delegated to other objects
       def delegated_instance_methods
         @delegated_to_object.methods(false).push(:flickr_type)
       end
 
+     # delegates methods that are returned by delegated instance method. It also
+      # delegates array methods to the @dimensions object
       def method_missing(id,*args,&block)
         return @delegated_to_object.send(id,*args,&block) if delegated_instance_methods.include?(id)
         super
       end
 
       alias :old_respond_to? :respond_to?
+      # returns true for delegated and regular methods
       def respond_to?(method,type=false)
         return true if delegated_instance_methods.include?(method)
         old_respond_to?(method,type)
       end
 
       alias :old_methods :methods
+      # returns delegated methods as well as regular methods
       def methods
         delegated_instance_methods + old_methods
       end
 
-      # cloning and copying methods
+      # compares value for internal state rather than object_id
       def initialize_copy(orig)
         super
         @delegated_to_object = @delegated_to_object.clone

data/lib/flickr_mocks/models/photo_sizes.rb

@@ -5,18 +5,22 @@ module FlickrMocks
         self.delegated_to_object= object
       end
 
+      # returns the flickr id for the stored photo
       def id
         @delegated_to_object.first.id
       end
 
+      # returns the flickr secret for the stored photo
       def secret
         @delegated_to_object.first.secret
       end
 
+      # returns array of PhotoSize objects available for the given photo
       def sizes
         @delegated_to_object
       end
 
+      # returns an array of symbols for the available sizes for the given photo
       def available_sizes
         @available_sizes ||= sizes.map do |size|
           size.size.to_sym
@@ -24,6 +28,7 @@ module FlickrMocks
         @available_sizes
       end
 
+      # returns a collection of sizes that can be used directly for WillPaginate.
       def collection
         @collection ||= ::WillPaginate::Collection.create(1, sizes.length, sizes.length) do |obj|
           obj.replace(sizes)
@@ -31,28 +36,38 @@ module FlickrMocks
         @collection
       end
 
-
+      # returns a string that encodes the name, width and height for all dimensions
+      # available for the photo. Sample return string is:
+      #
+      #  "square:75x75,thumbnail:67x100,small:161x240,medium:335x500"
       def to_s
         PhotoDimensions.new(@delegated_to_object.map do |size|
             "#{size.size}:#{size.width}x#{size.height}"
           end.join(',')).to_s
       end
 
+      # compares the complete internal state of two PhotoDetails objects rather than simply
+      # comparing object_id's
       def ==(other)
         return false unless self.class == other.class
         @delegated_to_object == other.instance_eval('@delegated_to_object')
       end
 
+      # returns an array that contains the symbol names for the possible sizes
+      # that a photo can have. Please note that not all sizes are available for
+      # every photo.
       def possible_sizes
         Models::Helpers.possible_sizes
       end
 
       # metaprogramming methods
       alias :old_methods :methods
+      # returns delegated methods as well as regular methods
       def methods
         delegated_instance_methods + old_methods
       end
 
+      # delegates methods that are returned by delegated instance method.
       def method_missing(id,*args,&block)
         return @delegated_to_object.send(id,*args,&block) if  delegated_instance_methods.include?(id)
         return nil if possible_sizes.include?(name)
@@ -60,15 +75,17 @@ module FlickrMocks
       end
 
       alias :old_respond_to? :respond_to?
+      # returns true for delegated and regular methods
       def respond_to?(method)
         old_respond_to?(method) || delegated_instance_methods.include?(method)
       end
 
+      # returns true for delegated and regular methods
       def delegated_instance_methods
         possible_sizes + FlickrMocks::Models::Helpers.array_accessor_methods
       end
 
-      # cloning methods
+      # compares value for internal state rather than object_id
       def initialize_copy(orig)
         super
         @delegated_to_object = @delegated_to_object.map do |data|
@@ -76,7 +93,6 @@ module FlickrMocks
         end
       end
 
-
       private
 
       def delegated_to_object=(data)

data/lib/flickr_mocks/models/photos.rb

@@ -8,6 +8,12 @@ module FlickrMocks
 
       class << self
         attr_writer :defaults
+        # returns a hash that contains the class defaults. The recognized
+        # default values include:
+        #
+        #  :max_entries
+        #  :per_page
+        #  :current_page 
         def defaults
           @defaults ||= FlickrMocks::Models::Helpers.paging_defaults().clone
           @defaults
@@ -23,31 +29,42 @@ module FlickrMocks
         self.photos =  data.photo
       end
 
+      # returns the default class value for the supplied symbol. 
       def default(value)
         Photos.defaults[value.to_s.to_sym]
       end
 
+      # returns the total number of entries that were returned from Flickr. Flickr
+      # caps the total number of returned photos to 4,000.
       def capped_entries
         total_entries > max_entries ? max_entries : total_entries
       end
 
+      # returns true when the number of photos returned by Flickr is less than the total
+      # number of photos available on Flickr for the given results.
       def capped?
         max_entries < total_entries ? true : false
       end
 
+      # returns 4,000, the default maximum number of entries returned by Flickr for
+      # any given query.
       def max_entries
         default(:max_entries)
       end
 
+      # returns the number of pages that can be retrieved from Flickr for the given
+      # query.
       def pages
         max_pages = default(:max_entries)/perpage
         total_pages > max_pages ? max_pages : total_pages
       end
 
+      # returns only the photos with a license that can be used for commercial purposes
       def usable_photos
         photos.clone.keep_if(&:usable?)
       end
 
+      # returns a collection of photos that can be used directly with WillPaginate.
       def collection(usable=nil)
         case usable
         when true
@@ -62,7 +79,8 @@ module FlickrMocks
         end
       end
 
-
+      # compares the complete internal state of two PhotoDetails objects rather than simply
+      # comparing object_ids
       def ==(other)
         return false unless other.class == Photos
         return false unless [:current_page,:per_page,:total_entries,:total_pages].inject(true) do |state,method|
@@ -73,26 +91,31 @@ module FlickrMocks
 
 
       # metaprogramming methods
+     
+      # delegates methods that are returned by delegated instance method.
       def method_missing(id,*args,&block)
         return photos.send(id,*args,&block) if  delegated_instance_methods.include?(id)
         super
       end
 
       alias :old_respond_to? :respond_to?
+      # returns true for delegated and regular methods
       def respond_to?(method)
         old_respond_to?(method) || delegated_instance_methods.include?(method)
       end
 
       alias :old_methods :methods
+      # returns delegated methods as well as regular methods
       def methods
         delegated_instance_methods + old_methods
       end
 
+      # returns true for delegated and regular methods
       def delegated_instance_methods
         FlickrMocks::Models::Helpers.array_accessor_methods
       end
 
-      # custom cloning methods
+      # compares value for internal state rather than object_id
       def initialize_copy(orig)
         super
         @photos = @photos.map do |photo|

data/lib/flickr_mocks/stubs.rb

@@ -13,7 +13,6 @@ module FlickrMocks
       #  Api.interesting_photos
       #  Api.commons_institutions
       def self.all
-        # [:VERSION, :Stubs, :Helpers, :Fixtures, :Models, :Api, :CustomClone, :CustomCompare, :CustomMarshal]
         [:photos,:photo_details,:photo,:photo_sizes,
           :interesting_photos,:commons_institutions].each do |method|
           self.send(method)
@@ -26,11 +25,14 @@ module FlickrMocks
       # The return value for Api.photos hash depends on the
       # the options hash:
       #
-      #   :search_terms => 'garbage' (returns empy list of photos)
-      #   :owner_id => 'garbage' (returns empty list of photos)
-      #   :owner_id => '<valid_id>' (returns list of photos that contain same author photos; valid_id is any string other than garbage)
-      #   :search_terms => '<valid_tag>' (returns list of photos with different author photos (if :owner_id must be nil); valid_tag is any string other than 'garbage')
-      #   :search_terms => nil and :owner_id => nil (raises FlickRaw::FailedResponse error)
+      #   :search_terms => 'garbage'           --> returns empy list of photos
+      #   :owner_id => 'garbage'               --> returns empty list of photos
+      #   :owner_id => '<valid_id>'            --> returns list of photos that contain same author photos;
+      #                                             valid_id is any string other than garbage
+      #   :search_terms => '<valid_tag>'       --> returns list of photos with different author photos
+      #                                              only if :owner_id  nil); valid_tag is any
+      #                                              string other than 'garbage'
+      #   (:search_terms && :owner_id) => nil  --> raises FlickRaw::FailedResponse error
       def self.photos
         lambda {::FlickrMocks::Api.stub(:photos) do |params|
             ::FlickrMocks::Stubs::Flickr.search
@@ -48,9 +50,10 @@ module FlickrMocks
       # The return value for Api.photo_details stub depends on the
       # state of the supplied options hash:
       #
-      #   :photo_id or :id => 'garbage' (raises FlickRaw::FailedResponse error)
-      #   :photo_id or :id => nil (raises FlickRaw::FailedResponse error)
-      #   :photo_id or :id => <valid_id> (returns a photo fixture with detailed information; valid_id can be any string other than 'garbage' )
+      #   (:photo_id || :id) => 'garbage'  --> raises FlickRaw::FailedResponse error
+      #   (:photo_id || :id) => nil        --> raises FlickRaw::FailedResponse error
+      #   (:photo_id || :id) => <valid_id> --> returns a photo fixture with detailed information;
+      #                                         valid_id can be any string other than 'garbage'
       def self.photo_details
         lambda {::FlickrMocks::Api.stub(:photo_details) do |params|
             ::FlickrMocks::Stubs::Flickr.getInfo
@@ -69,9 +72,10 @@ module FlickrMocks
       # The stub returns an object of class Models::Photo. The return value for the Api.photo
       # stub depends on the supplied options:
       #
-      #   :photo_id or :id => 'garbage' (raises Invaid ID error)
-      #   :photo_id or :id => nil (raises invalid ID error)
-      #   :photo_id or :id => <valid_id> (returns a photo fixture with detailed information; valid_id is any string other than 'garbage')
+      #   (:photo_id || :id) => 'garbage'  --> raises Invaid ID error
+      #   (:photo_id || :id) => nil        --> raises invalid ID error
+      #   (:photo_id || :id) => <valid_id> --> returns a photo fixture with detailed information;
+      #                                         valid_id is any string other than 'garbage'
       def self.photo
         lambda{::FlickrMocks::Api.stub(:photo) do |params|
             ::FlickrMocks::Stubs::Flickr.getInfo
@@ -88,9 +92,10 @@ module FlickrMocks
       # The stub returns an object of class Models::PhotoSizes.
       # The return value of Api.photo_sizes stub depends on the supplied options:
       #
-      #   :photo_id or :id => 'garbage' (raises FlickRaw::FailedResponse error)
-      #   :photo_id or :id => nil (raises FlickRaw::FailedResponse error)
-      #   :photo_id or :id => <valid_id> (returns list of photo sizes; valid_id is any string other than 'garbage')
+      #   (:photo_id || :id) => 'garbage'  --> raises FlickRaw::FailedResponse error
+      #   (:photo_id || :id) => nil        --> raises FlickRaw::FailedResponse error
+      #   (:photo_id || :id) => <valid_id> --> returns list of photo sizes; valid_id is
+      #                                         any string other than 'garbage'
       def self.photo_sizes  
          lambda {::FlickrMocks::Api.stub(:photo_sizes) do |params|
             ::FlickrMocks::Stubs::Flickr.getSizes
@@ -108,9 +113,10 @@ module FlickrMocks
       # The return value for Api.interesting_photos stub depends on the supplied
       # options hash:
       # 
-      #  :date => '2000-01-01' (returns empy list of photos)
-      #  :date => 'garbage' (raises an error)
-      #  :date => <valid_id> (returns interesting list of photos; date is any string other than 'garbage' and '2001-01-01')
+      #  :date => '2000-01-01' --> returns empty list of photos
+      #  :date => 'garbage'    --> raises an error
+      #  :date => <valid_id>   --> returns interesting list of photos; date is any string
+      #                            other than 'garbage' and '2001-01-01'
       def self.interesting_photos
          lambda {::FlickrMocks::Api.stub(:interesting_photos) do |params|
             ::FlickrMocks::Stubs::Flickr.interestingness
@@ -157,10 +163,11 @@ module FlickrMocks
       # are stubbed. The return value for the flickr.photos.search depends on
       # the supplied options hash:
       #
-      #   :tags => 'garbage' (returns empy list of photos)
-      #   :user_id => 'garbage' (returns empty list of photos)
-      #   :user_id => '<valid_id>' (returns list of photos that contain same author photos)
-      #   :tags => '<valid_tag>' (returns list of photos with different author photos; only if valid author id is not provided)
+      #   :tags => 'garbage'       --> returns empy list of photos
+      #   :user_id => 'garbage'    --> returns empty list of photos
+      #   :user_id => '<valid_id>' --> returns list of photos that contain same author photos
+      #   :tags => '<valid_tag>'   --> returns list of photos with different author photos
+           #                            only if valid author id is not provided
       def self.search
         fixtures = Fixtures.instance
         lambda { flickr.photos.stub(:search) do |params|
@@ -189,9 +196,9 @@ module FlickrMocks
       # are stubbed. The return value for the flickr.photos.getInfo stub depends on
       # the supplied options hash:
       #
-      #   :photo_id => 'garbage' (raises Invaid ID error)
-      #   :photo_id => nil (raises invalid ID error)
-      #   :photo_id => <valid_id> (returns a photo fixture with detailed information)
+      #   :photo_id => 'garbage'   --> raises Invaid ID error
+      #   :photo_id => nil         --> raises invalid ID error
+      #   :photo_id => <valid_id>  --> returns a photo fixture with detailed information
       def self.getInfo
         lambda {
           flickr.photos.stub(:getInfo) do |params|
@@ -218,9 +225,9 @@ module FlickrMocks
       # are stubbed. The return value for the flickr.photos.getSizes stub depends
       # on the supplied options hash:
       #
-      #  :photo_id => nil (raises FlickRaw::FailedResponse error)
-      #  :photo_id => 'garbage' (raises FlickRaw::FailedResponse error)
-      #  :photo_id => '<valid_id>' (returns a list of photo sizes)
+      #  :photo_id => nil          --> raises FlickRaw::FailedResponse error)
+      #  :photo_id => 'garbage'    --> raises FlickRaw::FailedResponse error)
+      #  :photo_id => '<valid_id>' --> returns a list of photo sizes)
       def self.getSizes
         lambda {
           flickr.photos.stub(:getSizes) do |params|
@@ -247,9 +254,9 @@ module FlickrMocks
       # are stubbed. The return value for the flickr.interesting.getList stub depends
       # on the supplied options hash.
       #
-      #  :date => '2000-01-01' (returns empy list of photos)
-      #  :date => 'garbage' (raises an error)
-      #  :date => <valid_id> (returns interesting list of photos)
+      #  :date => '2000-01-01'   --> returns empy list of photos
+      #  :date => 'garbage'      --> raises an error
+      #  :date => <valid_id>     --> returns interesting list of photos
       def self.interestingness
         lambda {
           flickr.interestingness.stub(:getList) do |params|

data/lib/flickr_mocks/version.rb

@@ -1,7 +1,7 @@
 
 module FlickrMocks
   # version for FlickrMocks gem
-  VERSION = '0.9.0'
+  VERSION = '0.9.1'
 
   # returns the version for FlickrMocks gem
   def self.version

data/spec/api/api_spec.rb

@@ -24,7 +24,9 @@ describe APP::Api do
       it "returns has with expected set of keys" do
         klass.defaults.keys.sort.should  == [:page,:per_page,:license,:media,
                                                         :max_entries,:extras,:tag_mode,
-                                                        :possible_sizes,:possible_tag_modes].sort
+                                                        :possible_sizes,:possible_tag_modes,
+                                                        :usable_licenses
+                                                        ].sort
 
 
       end

data/spec/models/photo_search_spec.rb

@@ -10,13 +10,6 @@ describe APP::Models::PhotoSearch do
   subject { klass.new fixtures.photos,options }
 
   context "class instance variables" do
-    specify {klass.should respond_to(:defaults)}
-    context "defaults" do
-      it "returns expected set of defaults" do
-        klass.defaults.should == {:page => 1}
-      end
-    end
-
     specify {klass.should respond_to(:delegated_instance_methods)}
     it "returns expected set of methods" do
       klass.delegated_instance_methods.sort.should == [:current_page, :per_page,
@@ -124,7 +117,7 @@ describe APP::Models::PhotoSearch do
       end
 
       it "returns empty string when no search_terms supplied during initialization" do
-        klass.new(fixtures.photos,{}).search_terms.should be_empty
+        klass.new(fixtures.photos,{}).search_terms.should be_nil
       end
     end
 

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 9
-  - 0
-  version: 0.9.0
+  - 1
+  version: 0.9.1
 platform: ruby
 authors: 
 - Takaltoo
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-25 00:00:00 -08:00
+date: 2010-12-27 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency