Finished Graph API and started on GraphCollection documentation

Also added YARD to the development group in Gemfile.

Gemfile

@@ -1,5 +1,9 @@
 source :rubygems
 
+group :development do
+  gem "yard"
+end
+
 group :development, :test do
   gem "typhoeus"
 

lib/koala/api/graph_api.rb

@@ -98,7 +98,7 @@ def delete_object(id, options = {})
       # @param args any additional arguments
       # @param options (see #get_object)
       # 
-      # @return [Koala::Facebook::API::GraphCollection] an array of object hashes 
+      # @return [Koala::Facebook::API::GraphCollection] an array of object hashes (in most cases)
       def get_connections(id, connection_name, args = {}, options = {})
         # Fetchs the connections for given object.
         graph_call("#{id}/#{connection_name}", args, "get", options)
@@ -350,14 +350,45 @@ def set_app_restrictions(app_id, restrictions_hash, args = {}, options = {})
         graph_call(app_id, args.merge(:restrictions => MultiJson.encode(restrictions_hash)), "post", options)
       end
 
-      # GraphCollection support
+      # Certain calls such as {#get_connections} return an array of results which you can page through
+      # forwards and backwards (to see more feed stories, search results, etc.).
+      # Those methods use get_page to request another set of results from Facebook.
+      # 
+      # @note You'll rarely need to use this method unless you're using Sinatra or another non-Rails framework
+      #       (see {Koala::Facebook::GraphCollection GraphCollection} for more information).    
+      #
+      # @param params an array of arguments to graph_call
+      #               as returned by {Koala::Facebook::GraphCollection.parse_page_url}.
+      #
+      # @return Koala::Facebook::GraphCollection the appropriate page of results (an empty array if there are none)
       def get_page(params)
-        # Pages through a set of results stored in a GraphCollection
-        # Used for connections and search results
         graph_call(*params)
       end
 
-      # Batch API
+      # Execute a set of Graph API calls as a batch. 
+      # See {SITE} for more information and examples.
+      # Also see {Koala::Facebook::GraphBatchAPI GraphBatchAPI} for 
+      # more information on batch request arguments.
+      # 
+      # @param http_options HTTP options for the entire request.
+      #
+      # @yield batch_api [Koala::Facebook::GraphBatchAPI] an API subclass
+      #                  whose requests will be queued and executed together at the end of the block
+      #
+      # @raise [Koala::Facebook::APIError] only if there is a problem with the overall batch request
+      #                                    (e.g. connectivity failure, an operation with a missing dependency).
+      #                                    Individual calls that error out will be represented as an unraised
+      #                                    APIError in the appropriate spot in the results array.
+      #
+      # @example
+      #         results = @api.batch do |batch_api|
+      #          batch_api.get_object('me')
+      #          batch_api.get_object(KoalaTest.user1)
+      #         end
+      #         # => [{"id" => my_id, ...}, {"id"" => koppel_id, ...}]
+      #
+      # @return an array of results from your batch calls (as if you'd made them individually), 
+      #         arranged in the same order they're made.
       def batch(http_options = {}, &block)
         batch_client = GraphBatchAPI.new(access_token, self)
         if block

lib/koala/api/graph_collection.rb

@@ -1,30 +1,42 @@
 module Koala
   module Facebook
     class API
-      class GraphCollection < Array
-        # This class is a light wrapper for collections returned
-        # from the Graph API.
-        #
-        # It extends Array to allow direct access to the data colleciton
-        # which should allow it to drop in seamlessly.
-        #
-        # It also allows access to paging information and the
-        # ability to get the next/previous page in the collection
-        # by calling next_page or previous_page.
-        attr_reader :paging, :api, :raw_response
-
-        def self.evaluate(response, api)
-          # turn the response into a GraphCollection if it's pageable; if not, return the original response
-          response.is_a?(Hash) && response["data"].is_a?(Array) ? self.new(response, api) : response
-        end
+      # A light wrapper for collections returned from the Graph API.
+      # It extends Array to allow you to page backward and forward through
+      # result sets, and providing easy access to paging information.
+      class GraphCollection < Array        
+
+        # The raw paging information from Facebook (next/previous URLs).
+        attr_reader :paging
+        # [Koala::Facebook::GraphAPI] the api used to make requests.
+        attr_reader :api
+        # The entire raw response from Facebook.
+        attr_reader :raw_response
 
+        # Initialize the Graph Collection array and store various useful information.
+        # 
+        # @param response the response from Facebook (a hash whose "data" key is an array)
+        # @param api the Graph {Koala::Facebook::API API} instance to use to make calls
+        #            (usually the API that made the original call).
+        #
+        # @return [Koala::Facebook::GraphCollection] an initialized GraphCollection 
+        #         whose paging, raw_response, and api attributes are populated.
         def initialize(response, api)
           super response["data"]
           @paging = response["paging"]
           @raw_response = response
           @api = api
         end
 
+        # @private
+        # Turn the response into a GraphCollection if they're pageable; 
+        # if not, return the original response.
+        # The Ads API (uniquely so far) returns a hash rather than an array when queried
+        # with get_connections. 
+        def self.evaluate(response, api)
+          response.is_a?(Hash) && response["data"].is_a?(Array) ? self.new(response, api) : response
+        end
+
         # defines methods for NEXT and PREVIOUS pages
         %w{next previous}.each do |this|