lib/zendesk_api/collection.rb in zendesk_api-0.1.7 vs lib/zendesk_api/collection.rb in zendesk_api-0.1.8

@@ -1,26 +1,28 @@
 require 'zendesk_api/resource'
-require 'zendesk_api/resources/misc'
-require 'zendesk_api/resources/ticket'
-require 'zendesk_api/resources/user'
+require 'zendesk_api/resources'
 
 module ZendeskAPI
   # Represents a collection of resources. Lazily loaded, resources aren't
   # actually fetched until explicitly needed (e.g. #each, {#fetch}).
   class Collection
     include ZendeskAPI::Sideloading
 
+    # Options passed in that are automatically converted from an array to a comma-separated list.
     SPECIALLY_JOINED_PARAMS = [:ids, :only]
 
     include Rescue
 
     # @return [ZendeskAPI::Association] The class association
     attr_reader :association
 
     # @return [Faraday::Response] The last response
     attr_reader :response
 
+    # @return [Hash] query options
+    attr_reader :options
+
     # Creates a new Collection instance. Does not fetch resources.
     # Additional options are: verb (default: GET), path (default: resource param), page, per_page.
     # @param [Client] client The {Client} to use.
     # @param [String] resource The resource being collected.
     # @param [Hash] options Any additional options to be passed in.
@@ -115,14 +117,19 @@
       end
 
       self
     end
 
+    # Adds an item (or items) to the list of side-loaded resources to request
+    # @option sideloads [Symbol or String] The item(s) to sideload
     def include(*sideloads)
       self.tap { @includes.concat(sideloads.map(&:to_s)) }
     end
 
+    # Adds an item to this collection
+    # @option item [ZendeskAPI::Data] the resource to add
+    # @raise [ArgumentError] if the resource doesn't belong in this collection
     def <<(item)
       fetch
       if item.is_a?(Resource)
         if item.is_a?(@resource_class)
           @resources << item
@@ -133,10 +140,11 @@
         item.merge!(:association => @association) if item.is_a?(Hash)
         @resources << @resource_class.new(@client, item)
       end
     end
 
+    # The API path to this collection
     def path
       @association.generate_path(:with_parent => true)
     end
 
     # Executes actual GET from API and loads resources into proper class.
@@ -176,22 +184,10 @@
       set_includes(@resources, @includes, body)
 
       @resources
     end
 
-    def set_page_and_count(body)
-      @count = (body["count"] || @resources.size).to_i
-      @next_page, @prev_page = body["next_page"], body["previous_page"]
-
-      if @next_page =~ /page=(\d+)/
-        @options["page"] = $1.to_i - 1
-      elsif @prev_page =~ /page=(\d+)/
-        @options["page"] = $1.to_i + 1
-      end
-    end
-
-
     rescue_client_error :fetch, :with => lambda { Array.new }
 
     # Alias for fetch(false)
     def to_a
       fetch
@@ -216,16 +212,19 @@
 
         self.next
       end
     end
 
+    # Replaces the current (loaded or not) resources with the passed in collection
+    # @option collection [Array] The collection to replace this one with
+    # @raise [ArgumentError] if any resources passed in don't belong in this collection
     def replace(collection)
       raise "this collection is for #{@resource_class}" if collection.any?{|r| !r.is_a?(@resource_class) }
       @resources = collection
     end
 
-    # Find the next page. Does one of three things: 
+    # Find the next page. Does one of three things:
     # * If there is already a page number in the options hash, it increases it and invalidates the cache, returning the new page number.
     # * If there is a next_page url cached, it executes a fetch on that url and returns the results.
     # * Otherwise, returns an empty array.
     def next
       if @options["page"]
@@ -263,10 +262,11 @@
       @count = nil
       @next_page = nil
       @prev_page = nil
     end
 
+    # @private
     def to_ary; nil; end
 
     # Sends methods to underlying array of resources.
     def method_missing(name, *args, &block)
       methods = @resource_class.singleton_methods(false).map(&:to_sym)
@@ -281,14 +281,29 @@
         self.class.new(@client, @resource_class, @options.merge(opts))
       end
     end
 
     alias :orig_to_s :to_s
+
+    # @private
     def to_s
       if @resources
         @resources.inspect
       else
         orig_to_s
+      end
+    end
+
+    private
+
+    def set_page_and_count(body)
+      @count = (body["count"] || @resources.size).to_i
+      @next_page, @prev_page = body["next_page"], body["previous_page"]
+
+      if @next_page =~ /page=(\d+)/
+        @options["page"] = $1.to_i - 1
+      elsif @prev_page =~ /page=(\d+)/
+        @options["page"] = $1.to_i + 1
       end
     end
   end
 end