parse-stack 1.5.1 → 1.5.2

data/lib/parse/model/pointer.rb

@@ -7,37 +7,97 @@ require 'active_support/inflector'
 require 'active_support/core_ext'
 require 'active_model_serializers'
 require_relative 'model'
-require 'active_model_serializers'
 module Parse
 
-    # A Parse Pointer is the superclass of Parse::Object types. A pointer can be considered
-    # a type of Parse::Object in which only the class name and id is known. In most cases,
-    # you may not see Parse::Pointer object be used if you have defined all your Parse::Object subclasses
-    # based on your Parse application tables - however they are used for when a class is found that cannot be
-    # associated with a defined ruby class or used when specifically saving Parse relation types.
+    # The Pointer class represents the pointer type in Parse and is the superclass
+    # of Parse::Object types. A pointer can be considered a type of Parse::Object
+    # in which only the class name and id is known. In most cases, you may not
+    # deal with Parse::Pointer objects directly if you have defined all your
+    # Parse::Object subclasses.
+    #
+    # A `Parse::Pointer` only contains data about the specific Parse class and
+    # the `id` for the object. Therefore, creating an instance of any
+    # Parse::Object subclass with only the `:id` field set will be
+    # considered in "pointer" state even though its specific class is not
+    # `Parse::Pointer` type. The only case that you may have a Parse::Pointer
+    # is in the case where an object was received for one of your classes and
+    # the framework has no registered class handler for it.
+    # Assume you have the tables `Post`, `Comment` and `Author` defined in your
+    # remote Parse database, but have only defined `Post` and `Commentary`
+    # locally.
+    # @example
+    #   class Post < Parse::Object
+    #   end
+    #
+    #   class Commentary < Parse::Object
+    # 	  belongs_to :post
+    # 	  belongs_to :author
+    #   end
+    #
+    #   comment = Commentary.first
+    #   comment.post? # true because it is non-nil
+    #   comment.artist? # true because it is non-nil
+    #
+    #   # both are true because they are in a Pointer state
+    #   comment.post.pointer? # true
+    #   comment.author.pointer? # true
+    #
+    #   # we have defined a Post class handler
+    #   comment.post # <Post @parse_class="Post", @id="xdqcCqfngz">
+    #
+    #   # we have not defined an Author class handler
+    #   comment.author # <Parse::Pointer @parse_class="Author", @id="hZLbW6ofKC">
+    #
+    #
+    #   comment.post.fetch # fetch the relation
+    #   comment.post.pointer? # false, it is now a full object.
+    #
+    # The effect is that for any unknown classes that the framework encounters,
+    # it will generate Parse::Pointer instances until you define those classes
+    # with valid properties and associations. While this might be ok for some
+    # classes you do not use, we still recommend defining all your Parse classes
+    # locally in the framework.
+    #
+    # Once you have a subclass, you may also create a Parse::Pointer object using
+    # the _pointer_ method.
+    # @example
+    #   Parse::User.pointer("123456") # => Parse::Pointer for "_User" class
+    #
+    # @see Parse::Object
     class Pointer < Model
       ATTRIBUTES = { __type: :string, className: :string, objectId: :string}.freeze
-      attr_accessor :parse_class, :id
+      # @return [String] the name of the Parse class for this pointer.
+      attr_accessor :parse_class
+      # @return [String] the objectId field
+      attr_accessor :id
 
-      def __type; "Pointer"; end;
+      # @return [Model::TYPE_POINTER]
+      def __type; Parse::Model::TYPE_POINTER; end;
       alias_method :className, :parse_class
       # A Parse object as a className field and objectId. In ruby, we will use the
       # id attribute method, but for usability, we will also alias it to objectId
       alias_method :objectId, :id
 
+      # A Parse pointer only requires the name of the remote Parse collection name,
+      # and the `objectId` of the record.
+      # @param table [String] The Parse class name in the Parse database.
+      # @param oid [String] The objectId
       def initialize(table, oid)
         @parse_class = table.to_s
         @id = oid.to_s
       end
 
+      # @return [String] the name of the collection for this Pointer.
       def parse_class
         @parse_class
       end
 
+      # @return [Hash]
       def attributes
         ATTRIBUTES
       end
 
+      # @return [Hash] serialized JSON structure
       def json_hash
         JSON.parse to_json
       end
@@ -45,32 +105,44 @@ module Parse
       # Create a new pointer with the current class name and id. While this may not make sense
       # for a pointer instance, Parse::Object subclasses use this inherited method to turn themselves into
       # pointer objects.
+      # @example
+      #  user = Parse::User.first
+      #  user.pointer # => Parse::Pointer("_User", user.id)
+      #
+      # @return [Pointer] a new Pointer for this object.
+      # @see Parse::Object
       def pointer
         Pointer.new parse_class, @id
       end
 
-      # determines if an object (or subclass) is a pointer type. A pointer is determined
-      # if we have a parse class and an id, but no timestamps, then we probably are a pointer.
+      # Whether this instance is in pointer state. A pointer is determined
+      # if we have a parse class and an id, but no created_at or updated_at fields.
+      # @return [Boolean] true if instance is in pointer state.
       def pointer?
         present? && @created_at.blank? && @updated_at.blank?
       end
 
-      # boolean whether this object has data and is not a pointer. Because of some autofetching
+      # Returns true if the data for this instance has been fetched. Because of some autofetching
       # mechanisms, this is useful to know whether the object already has data without actually causing
       # a fetch of the data.
+      # @return [Boolean] true if not in pointer state.
       def fetched?
         present? && pointer? == false
       end
 
       # This method is a general implementation that gets overriden by Parse::Object subclass.
       # Given the class name and the id, we will go to Parse and fetch the actual record, returning the
-      # JSON object. Note that the subclass implementation does something a bit different.
+      # JSON object.
+      # @return [Parse::Object] the fetched Parse::Object, nil otherwise.
       def fetch
         response = client.fetch_object(parse_class, id)
         return nil if response.error?
         response.result
       end
 
+      # Two Parse::Pointers (or Parse::Objects) are equal if both of them have
+      # the same Parse class and the same id.
+      # @return [Boolean]
       def ==(o)
         return false unless o.is_a?(Pointer)
         #only equal if the Parse class and object ID are the same.
@@ -78,6 +150,7 @@ module Parse
       end
       alias_method :eql?, :==
 
+      # @return [Boolean] true if instance has a Parse class and an id.
       def present?
         parse_class.present? && @id.present?
       end
@@ -87,14 +160,22 @@ end
 
 # extensions
 class Array
+  # This method maps all the ids (String) of all Parse::Objects in the array.
+  # @return [Array<String>] an array of strings of ids.
   def objectIds
-    map { |m| m.is_?(Parse::Pointer) ? m.id : nil }.reject { |r| r.nil? }
+    map { |m| m.is_?(Parse::Pointer) ? m.id : nil }.compact
   end
 
+  # Filter all objects in the array that do not inherit from Parse::Pointer or
+  # Parse::Object.
+  # @return [Array<Parse::Object,Parse::Pointer>] an array of Parse::Objects.
   def valid_parse_objects
     select { |s| s.is_a?(Parse::Pointer) }
   end
 
+  # Convert all potential objects in the array to a list of Parse::Pointer instances.
+  # The array can contain a mixture of objects types including JSON Parse-like hashes.
+  # @return [Array<Parse::Pointer>] an array of Parse::Pointer objects.
   def parse_pointers(table = nil)
     self.map do |m|
       #if its an exact Parse::Pointer

data/lib/parse/model/push.rb

@@ -5,19 +5,82 @@ require_relative '../query.rb'
 require_relative '../client.rb'
 require 'active_model_serializers'
 module Parse
-
+  # This class represents the API to send push notification to devices that are
+  # available in the Installation table. Push notifications are implemented
+  # through the `Parse::Push` class. To send push notifications through the
+  # REST API, you must enable `REST push enabled?` option in the `Push
+  # Notification Settings` section of the `Settings` page in your Parse
+  # application. Push notifications targeting uses the Installation Parse
+  # class to determine which devices receive the notification. You can provide
+  # any query constraint, similar to using `Parse::Query`, in order to target
+  # the specific set of devices you want given the columns you have configured
+  # in your `Installation` class. The `Parse::Push` class supports many other
+  # options not listed here.
+  # @example
+  #
+  #   push = Parse::Push.new
+  #   push.send( "Hello World!") # to everyone
+  #
+  #   # simple channel push
+  #   push = Parse::Push.new
+  #   push.channels = ["addicted2salsa"]
+  #   push.send "You are subscribed to Addicted2Salsa!"
+  #
+  #   # advanced targeting
+  #   push = Parse::Push.new( {..where query constraints..} )
+  #   # or use `where()`
+  #   push.where :device_type.in => ['ios','android'], :location.near => some_geopoint
+  #   push.alert = "Hello World!"
+  #   push.sound = "soundfile.caf"
+  #
+  #   # additional payload data
+  #   push.data = { uri: "app://deep_link_path" }
+  #
+  #   # Send the push
+  #   push.send
+  #
+  #
   class Push
     include Client::Connectable
-    attr_accessor :query, :alert, :badge, :sound, :title, :data
-    attr_accessor :expiration_time, :expiration_interval, :push_time, :channels
+
+    # @!attribute [rw] query
+    # Sending a push notification is done by performing a query against the Installation
+    # collection with a Parse::Query. This query contains the constraints that will be
+    # sent to Parse with the push payload.
+    #   @return [Parse::Query] the query containing Installation constraints.
+
+    # @!attribute [rw] alert
+    #   @return [String]
+    # @!attribute [rw] badge
+    #   @return [Integer]
+    # @!attribute [rw] sound
+    #   @return [String] the name of the sound file
+    # @!attribute [rw] title
+    #   @return [String]
+    # @!attribute [rw] data
+    #   @return [Hash] specific payload data.
+    # @!attribute [rw] expiration_time
+    #   @return [Parse::Date]
+    # @!attribute [rw] expiration_interval
+    #   @return [Integer]
+    # @!attribute [rw] push_time
+    #   @return [Parse::Date]
+    # @!attribute [rw] channels
+    #   @return [Array] an array of strings for subscribed channels.
+    attr_accessor :query, :alert, :badge, :sound, :title, :data,
+    :expiration_time, :expiration_interval, :push_time, :channels
 
     alias_method :message, :alert
     alias_method :message=, :alert=
 
+    # Send a push notification using a push notification hash
+    # @param payload [Hash] a push notification hash payload
     def self.send(payload)
       client.push payload.as_json
     end
 
+    # Initialize a new push notification request.
+    # @param constraints [Hash] a set of query constraints
     def initialize(constraints = {})
       self.where constraints
     end
@@ -26,6 +89,8 @@ module Parse
       @query ||= Parse::Query.new(Parse::Model::CLASS_INSTALLATION)
     end
 
+    # @!attribute [rw] where
+    #   @return [Hash] a hash of 'where' query constraints
     def where=(where_clausees)
       query.where where_clauses
     end
@@ -37,7 +102,7 @@ module Parse
     end
 
     def channels=(list)
-      @channels = [list].flatten
+      @channels = Array.wrap(list)
     end
 
     def data=(h)
@@ -48,14 +113,19 @@ module Parse
       end
     end
 
+    # @return [Hash] a JSON encoded hash.
     def as_json(*args)
       payload.as_json
     end
 
+    # @return [String] a JSON encoded string.
     def to_json(*args)
       as_json.to_json
     end
 
+    # This method takes all the parameters of the instance and creates a proper
+    # hash structure, required by Parse, in order to process the push notification.
+    # @return [Hash] the prepared push payload to be used in the request.
     def payload
       msg = {
         data: {
@@ -91,6 +161,8 @@ module Parse
       msg
     end
 
+    # helper method to send a message
+    # @param message [String] the message to send
     def send(message = nil)
       @alert = message if message.is_a?(String)
       @data = message if message.is_a?(Hash)

data/lib/parse/query.rb

@@ -12,27 +12,131 @@ require 'active_support/inflector'
 require 'active_support/core_ext'
 
 module Parse
-  # This is the main engine behind making Parse queries on tables. It takes
-  # a set of constraints and generatse the proper hash parameters that are passed
-  # to a client :get request in order to retrive the results.
-  # The design of querying is based on ruby DataMapper orm where we define
-  # symbols with specific methos attached to values.
-  # At the core of each item is a Parse::Operation. An operation is
+  # The {Parse::Query} class provides the lower-level querying interface for
+  # your Parse collections by utilizing the {http://parseplatform.github.io/docs/rest/guide/#queries
+  # REST Querying interface}. This is the main engine behind making Parse queries
+  # on remote collections. It takes a set of constraints and generates the
+  # proper hash parameters that are passed to an API request in order to retrive
+  # matching results. The querying design pattern is inspired from
+  # {http://datamapper.org/ DataMapper} where symbols are overloaded with
+  # specific methods with attached values.
+  #
+  # At the core of each item is a {Parse::Operation}. An operation is
   # made up of a field name and an operator. Therefore calling
   # something like :name.eq, defines an equality operator on the field
-  # name. Using Parse::Operations with values, we can build different types of
-  # constraints - as Parse::Constraint
-
+  # name. Using {Parse::Operation}s with values, we can build different types of
+  # constraints, known as {Parse::Constraint}s.
+  #
+  # This component can be used on its own without defining your models as all
+  # results are provided in hash form.
+  #
+  # *Field-Formatter*
+  #
+  # By convention in Ruby (see
+  # {https://github.com/bbatsov/ruby-style-guide#snake-case-symbols-methods-vars Style Guide}),
+  # symbols and variables are expressed in lower_snake_case form. Parse, however,
+  # prefers column names in {String#columnize} format (ex. `objectId`,
+  # `createdAt` and `updatedAt`). To keep in line with the style
+  # guides between the languages, we do the automatic conversion of the field
+  # names when compiling the query. This feature can be overridden by changing the
+  # value of {Parse::Query.field_formatter}.
+  #
+  #  # default uses :columnize
+  #  query = Parse::User.query :field_one => 1, :FieldTwo => 2, :Field_Three => 3
+  #  query.compile_where # => {"fieldOne"=>1, "fieldTwo"=>2, "fieldThree"=>3}
+  #
+  #  # turn off
+  #  Parse::Query.field_formatter = nil
+  #  query = Parse::User.query :field_one => 1, :FieldTwo => 2, :Field_Three => 3
+  #  query.compile_where # => {"field_one"=>1, "FieldTwo"=>2, "Field_Three"=>3}
+  #
+  #  # force everything camel case
+  #  Parse::Query.field_formatter = :camelize
+  #  query = Parse::User.query :field_one => 1, :FieldTwo => 2, :Field_Three => 3
+  #  query.compile_where # => {"FieldOne"=>1, "FieldTwo"=>2, "FieldThree"=>3}
+  #
+  # Most of the constraints supported by Parse are available to `Parse::Query`.
+  # Assuming you have a column named `field`, here are some examples. For an
+  # explanation of the constraints, please see
+  # {http://parseplatform.github.io/docs/rest/guide/#queries Parse Query Constraints documentation}.
+  # You can build your own custom query constraints by creating a `Parse::Constraint`
+  # subclass. For all these `where` clauses assume `q` is a `Parse::Query` object.
   class Query
     extend  ::ActiveModel::Callbacks
     include Parse::Client::Connectable
     include Enumerable
+    # @!group Callbacks
+    #
+    # @!method before_prepare
+    #   A callback called before the query is compiled
+    #   @yield A block to execute for the callback.
+    #   @see ActiveModel::Callbacks
+    # @!method after_prepare
+    #   A callback called after the query is compiled
+    #   @yield A block to execute for the callback.
+    #   @see ActiveModel::Callbacks
+    # @!endgroup
     define_model_callbacks :prepare, only: [:after, :before]
     # A query needs to be tied to a Parse table name (Parse class)
     # The client object is of type Parse::Client in order to send query requests.
     # You can modify the default client being used by all Parse::Query objects by setting
     # Parse::Query.client. You can override individual Parse::Query object clients
     # by changing their client variable to a different Parse::Client object.
+
+    # @!attribute [rw] table
+    #  @return [String] the name of the Parse collection to query against.
+    # @!attribute [rw] client
+    #  @return [Parse::Client] the client to use for the API Query request.
+    # @!attribute [rw] key
+    #  This parameter is used to support `select` queries where you have to
+    #  pass a `key` parameter for matching different tables.
+    #  @return [String] the foreign key to match against.
+    # @!attribute [rw] cache
+    #  Set whether this query should be cached and for how long. This parameter
+    #  is used to cache queries when using {Parse::Middleware::Caching}. If
+    #  the caching middleware is configured, all queries will be cached for the
+    #  duration allowed by the cache, and therefore some queries could return
+    #  cached results. To disable caching and cached results for this specific query,
+    #  you may set this field to `false`. To specify the specific amount of time
+    #  you want this query to be cached, set a duration (in number of seconds) that
+    #  the caching middleware should cache this request.
+    #  @example
+    #   # find all users with name "Bob"
+    #   query = Parse::Query.new("_User", :name => "Bob")
+    #
+    #   query.cache = true # (default) cache using default cache duration.
+    #
+    #   query.cache = 1.day # cache for 86400 seconds
+    #
+    #   query.cache = false # do not cache or use cache results
+    #
+    #   # You may optionally pass this into the constraint hash.
+    #   query = Parse::Query.new("_User", :name => "Bob", :cache => 1.day)
+    #
+    #  @return [Boolean] if set to true or false on whether it should use the default caching
+    #   length set when configuring {Parse::Middleware::Caching}.
+    #  @return [Integer] if set to a number of seconds to cache this specific request
+    #   with the {Parse::Middleware::Caching}.
+    # @!attribute [rw] use_master_key
+    #  True or false on whether we should send the master key in this request. If
+    #  You have provided the master_key when initializing Parse, then all requests
+    #  will send the master key by default. This feature is useful when you want to make
+    #  a particular query be performed with public credentials, or on behalf of a user using
+    #  a {session_token}. Default is set to true.
+    #  @see #session_token
+    #  @example
+    #   # disable use of the master_key in the request.
+    #   query = Parse::Query.new("_User", :name => "Bob", :master_key => false)
+    #  @return [Boolean] whether we should send the master key in this request.
+    # @!attribute [rw] session_token
+    #  Set the session token to send with this API request. A session token is tied to
+    #  a logged in {Parse::User}. When sending a session_token in the request,
+    #  this performs the query on behalf of the user (with their allowed priviledges).
+    #  @example
+    #   # perform this query as user represented by session_token
+    #   query = Parse::Query.new("_User", :name => "Bob", :session_token => "r:XyX123...")
+    #  @note Using a session_token automatically disables sending the master key in the request.
+    #  @return [String] the session token to send with this API request.
     attr_accessor :table, :client, :key, :cache, :use_master_key, :session_token
 
     # We have a special class method to handle field formatting. This turns
@@ -44,11 +148,18 @@ module Parse
     # in lower case). You can specify a different method to call by setting the Parse::Query.field_formatter
     # variable with the symbol name of the method to call on the object. You can set this to nil
     # if you do not want any field formatting to be performed.
+
     @field_formatter = :columnize
     class << self
-      #field formatter getters and setters.
+      # The method to use when converting field names to Parse column names. Default is {String#columnize}.
+      # By convention Parse uses lowercase-first camelcase syntax for field/column names, but ruby
+      # uses snakecase. To support this methodology we process all field constraints through the method
+      # defined by the field formatter. You may set this to nil to turn off this functionality.
+      # @return [Symbol] The filter method to process column and field names. Default {String#columnize}.
       attr_accessor :field_formatter
 
+      # @param str [String] the string to format
+      # @return [String] formatted string using {Parse::Query.field_formatter}.
       def format_field(str)
         res = str.to_s.strip
         if field_formatter.present? && res.respond_to?(field_formatter)
@@ -57,18 +168,48 @@ module Parse
         res
       end
 
-      # Simple way to create a query.
-      def all(table, constraints = {})
-        self.new(table, {limit: :max}.merge(constraints) )
+      # Helper method to create a query with constraints for a specific Parse collection.
+      # Also sets the default limit count to `:max`.
+      # @param table [String] the name of the Parse collection to query. (ex. "_User")
+      # @param constraints [Hash] a set of query constraints.
+      # @return [Query] a new query for the Parse collection with the passed in constraints.
+      def all(table, constraints = {limit: :max})
+        self.new(table, constraints.reverse_merge({limit: :max}))
+      end
+
+      # This methods takes a set of constraints and merges them to build a final
+      # `where` constraint clause for sending to the Parse backend.
+      # @param where [Array] an array of {Parse::Constraint} objects.
+      # @return [Hash] a hash representing the compiled query
+      def compile_where(where)
+        constraint_reduce( where )
+      end
+
+      # @!visibility private
+      def constraint_reduce(clauses)
+        # @todo Need to add proper constraint merging
+        clauses.reduce({}) do |clause, subclause|
+          #puts "Merging Subclause: #{subclause.as_json}"
+
+          clause.deep_merge!( subclause.as_json || {} )
+          clause
+        end
       end
 
     end
 
+    # @!attribute [r] client
+    # @return [Parse::Client] the client to use for making the API request.
+    # @see Parse::Client::Connectable
     def client
       # use the set client or the default client.
       @client ||= self.class.client
     end
 
+    # Clear a specific clause of this query. This can be one of: :where, :order,
+    # :includes, :skip, :limit, :count, :keys or :results.
+    # @param item [:Symbol] the clause to clear.
+    # @return [self]
     def clear(item = :results)
       case item
       when :where
@@ -89,10 +230,27 @@ module Parse
         @keys = []
       end
       @results = nil
-
-      self
+      self # chaining
     end
 
+    # Constructor method to create a query with constraints for a specific Parse collection.
+    # Also sets the default limit count to `:max`.
+    # @overload new(table)
+    #   Create a query for this Parse collection name.
+    #   @example
+    #     Parse::Query.new "_User"
+    #     Parse::Query.new "_Installation", :device_type => 'ios'
+    #   @param table [String] the name of the Parse collection to query. (ex. "_User")
+    #   @param constraints [Hash] a set of query constraints.
+    # @overload new(parseSubclass)
+    #   Create a query for this Parse model (or anything that responds to {Parse::Object.parse_class}).
+    #   @example
+    #     Parse::Query.new Parse::User
+    #     # assume Post < Parse::Object
+    #     Parse::Query.new Post, like_count.gt => 0
+    #   @param parseSubclass [Parse::Object] the Parse model constant
+    #   @param constraints [Hash] a set of query constraints.
+    # @return [Query] a new query for the Parse collection with the passed in constraints.
     def initialize(table, constraints = {})
       table = table.to_s.to_parse_class if table.is_a?(Symbol)
       table = table.parse_class if table.respond_to?(:parse_class)
@@ -108,9 +266,11 @@ module Parse
       @cache = true
       @use_master_key = true
       conditions constraints
-      self # chaining
     end # initialize
 
+    # Add a set of query expressions and constraints.
+    # @param expressions
+    # @return [self]
     def conditions(expressions = {})
       expressions.each do |expression, value|
         if expression == :order
@@ -144,12 +304,29 @@ module Parse
       @table = t.to_s.camelize
     end
 
-    # returns the query parameter for the particular clause
+    # returns the query clause for the particular clause
+    # @param clause_name [Symbol] One of supported clauses to return: :keys,
+    #  :where, :order, :includes, :limit, :skip
+    # @return [Object] the content of the clause for this query.
     def clause(clause_name = :where)
       return unless [:keys, :where, :order, :includes, :limit, :skip].include?(clause_name)
       instance_variable_get "@#{clause_name}".to_sym
     end
 
+    # Restrict the fields returned by the query. This is useful for larger query
+    # results set where some of the data will not be used, which reduces network
+    # traffic and deserialization performance.
+    # @example
+    #  # results only contain :name field
+    #  Song.all :keys => :name
+    #
+    #  # multiple keys
+    #  Song.all :keys => [:name,:artist]
+    # @note Use this feature with caution when working with the results, as
+    #    values for the fields not specified in the query will be omitted in
+    #    the resulting object.
+    # @param fields [Array] the name of the fields to return.
+    # @return [self]
     def keys(*fields)
       @keys ||= []
       fields.flatten.each do |field|
@@ -162,6 +339,16 @@ module Parse
       self # chaining
     end
 
+    # Add a sorting order for the query.
+    # @example
+    #  # order updated_at ascending order
+    #  Song.all :order => :updated_at
+    #
+    #  # first order by highest like_count, then by ascending name.
+    #  # Note that ascending is the default if not specified (ex. `:name.asc`)
+    #  Song.all :order => [:like_count.desc, :name]
+    # @param ordering [Parse::Order] an ordering
+    # @return [self]
     def order(*ordering)
       @order ||= []
       ordering.flatten.each do |order|
@@ -175,6 +362,13 @@ module Parse
       self #chaining
     end #order
 
+    # Use with limit to paginate through results. Default is 0 with
+    # maximum value being 10,000.
+    # @example
+    #  # get the next 3 songs after the first 10
+    #  Song.all :limit => 3, :skip => 10
+    # @param count [Integer] The number of records to skip.
+    # @return [self]
     def skip(count)
       #  min <= count <= max
       @skip = [ 0, count.to_i, 10_000].sort[1]
@@ -182,6 +376,19 @@ module Parse
       self #chaining
     end
 
+    # Limit the number of objects returned by the query. The default is 100, with
+    # Parse allowing a maximum of 1000. The framework also allows a value of
+    # `:max`. Utilizing this will have the framework continually intelligently
+    # utilize `:skip` to continue to paginate through results until an empty
+    # result set is received or the `:skip` limit is reached (10,000). When
+    # utilizing `all()`, `:max` is the default option for `:limit`.
+    # @example
+    #  Song.all :limit => 1 # same as Song.first
+    #  Song.all :limit => 1000 # maximum allowed by Parse
+    #  Song.all :limit => :max # up to 11,000 records (theoretical).
+    # @param count [Integer,Symbol] The number of records to return. You may pass :max
+    #  to get as many as 11_000 records with the aid if skipping.
+    # @return [self]
     def limit(count)
       if count == :max || count == :all
         @limit = 11_000
@@ -201,6 +408,19 @@ module Parse
       self #chaining
     end
 
+    # Set a list of Parse Pointer columns to be fetched for matching records.
+    # You may chain multiple columns with the `.` operator.
+    # @example
+    #  # assuming an 'Artist' has a pointer column for a 'Manager'
+    #  # and a Song has a pointer column for an 'Artist'.
+    #
+    #  # include the full artist object
+    #  Song.all(:includes => [:artist])
+    #
+    #  # Chaining - fetches the artist and the artist's manager for matching songs
+    #  Song.all :includes => ['artist.manager']
+    # @param fields [Array] the list of Pointer columns to fetch.
+    # @return [self]
     def includes(*fields)
       @includes ||= []
       fields.flatten.each do |field|
@@ -212,14 +432,27 @@ module Parse
       @results = nil if fields.count > 0
       self # chaining
     end
-    alias_method :include, :includes
 
+    # Combine a list of {Parse::Constraint} objects
+    # @param list [Array<Parse::Constraint>] an array of Parse::Constraint subclasses.
+    # @return [self]
     def add_constraints(list)
       list = Array.wrap(list).select { |m| m.is_a?(Parse::Constraint) }
       @where = @where + list
       self
     end
 
+    # Add a constraint to the query. This is mainly used internally for compiling constraints.
+    # @example
+    #  # add where :field equals "value"
+    #  query.add_constraint(:field.eq, "value")
+    #
+    #  # add where :like_count is greater than 20
+    #  query.add_constraint(:like_count.gt, 20)
+    #
+    # @param operator [Parse::Operator] an operator object containing the operation and operand.
+    # @param value [Object] the value for the constraint.
+    # @return [self]
     def add_constraint(operator, value = nil, **opts)
       @where ||= []
       constraint = operator # assume Parse::Constraint
@@ -242,10 +475,26 @@ module Parse
       self #chaining
     end
 
+    # @return [Array<Parse::Constraint>] an array of constraints
+    #  composing the :where clause for this query.
     def constraints
       @where
     end
 
+    # Add additional query constraints to the `where` clause. The `where` clause
+    # is based on utilizing a set of constraints on the defined column names in
+    # your Parse classes. The constraints are implemented as method operators on
+    # field names that are tied to a value. Any symbol/string that is not one of
+    # the main expression keywords described here will be considered as a type of
+    # query constraint for the `where` clause in the query.
+    # @example
+    #  # parts of a single where constraint
+    #  { :column.constraint => value }
+    # @see Parse::Constraint
+    # @param conditions [Hash] a set of constraints for this query.
+    # @param opts [Hash] a set of options when adding the constraints. This is
+    #  specific for each Parse::Constraint.
+    # @return [self]
     def where(conditions = nil, opts = {})
       return @where if conditions.nil?
       if conditions.is_a?(Hash)
@@ -256,6 +505,22 @@ module Parse
       self #chaining
     end
 
+    # Combine two where clauses into an OR constraint. Equivalent to the `$or`
+    # Parse query operation. This is useful if you want to find objects that
+    # match several queries. We overload the `|` operator in order to have a
+    # clean syntax for joining these `or` operations.
+    # @example
+    #  query = Player.where(:wins.gt => 150)
+    #  query.or_where(:wins.lt => 5)
+    #  # where wins > 150 || wins < 5
+    #  results = query.results
+    #
+    #  # or_query = query1 | query2 | query3 ...
+    #  # ex. where wins > 150 || wins < 5
+    #  query = Player.where(:wins.gt => 150) | Player.where(:wins.lt => 5)
+    #  results = query.results
+    # @param where_clauses [Array<Parse::Constraint>] a list of Parse::Constraint objects to combine.
+    # @return [Query] the combined query with an OR clause.
     def or_where(where_clauses = [])
       where_clauses = where_clauses.where if where_clauses.is_a?(Parse::Query)
       where_clauses = Parse::Query.new(@table, where_clauses ).where if where_clauses.is_a?(Hash)
@@ -277,6 +542,8 @@ module Parse
       self #chaining
     end
 
+    # @see #or_where
+    # @return [Query] the combined query with an OR clause.
     def |(other_query)
         raise ArgumentError, "Parse queries must be of the same class #{@table}." unless @table == other_query.table
         copy_query = self.clone
@@ -284,6 +551,16 @@ module Parse
         copy_query
     end
 
+    # Perform a count query.
+    # @example
+    #  # get number of songs with a play_count > 10
+    #  Song.count :play_count.gt => 10
+    #
+    #  # same
+    #  query = Parse::Query.new("Song")
+    #  query.where :play_count.gt => 10
+    #  query.count
+    # @return [Integer] the count result
     def count
       old_value = @count
       @count = 1
@@ -292,36 +569,47 @@ module Parse
       res
     end
 
+    # @yield a block yield for each object in the result
+    # @return [Array]
+    # @see Array#each
     def each
        return results.enum_for(:each) unless block_given? # Sparkling magic!
        results.each(&Proc.new)
     end
 
+    # @yield a block yield for each object in the result
+    # @return [Array]
+    # @see Array#map
     def map
       return results.enum_for(:map) unless block_given? # Sparkling magic!
       results.map(&Proc.new)
     end
 
+    # @yield a block yield for each object in the result
+    # @return [Array]
+    # @see Array#select
     def select
       return results.enum_for(:select) unless block_given? # Sparkling magic!
       results.select(&Proc.new)
     end
 
+    # @return [Array]
+    # @see Array#to_a
     def to_a
       results.to_a
     end
 
-    def select
-      return results.enum_for(:select) unless block_given? # Sparkling magic!
-      results.select(&Proc.new)
-    end
-
+    # @param limit [Integer] the number of first items to return.
+    # @return [Parse::Object] the first object from the result.
     def first(limit = 1)
       @results = nil if @limit != limit
       @limit = limit
       limit == 1 ? results.first : results.first(limit)
     end
 
+    # max_results is used to iterate through as many API requests as possible using
+    # :skip and :limit paramter.
+    # @!visibility private
     def max_results(raw: false)
       compiled_query = compile
       query_limit = compiled_query[:limit] ||= 1_000
@@ -331,10 +619,9 @@ module Parse
       results = []
 
       iterations.times do |idx|
-        #puts "Fetching 1000 after #{compiled_query[:skip]}"
         response = fetch!( compiled_query )
         break if response.error? || response.results.empty?
-        #puts "Appending #{response.results.count} results..."
+
         items = response.results
         items = decode(items) unless raw
 
@@ -353,6 +640,7 @@ module Parse
       results
     end
 
+    # @!visibility private
     def _opts
       opts = {}
       opts[:cache] = self.cache || false
@@ -365,6 +653,9 @@ module Parse
       opts
     end
 
+    # Performs the fetch request for the query.
+    # @param compiled_query [Hash] the compiled query
+    # @return [Parse::Response] a response for a query request.
     def fetch!(compiled_query)
 
       response = client.find_objects(@table, compiled_query.as_json, _opts )
@@ -375,6 +666,27 @@ module Parse
     end
     alias_method :execute!, :fetch!
 
+    # Executes the query and builds the result set of Parse::Objects that matched.
+    # When this method is passed a block, the block is yielded for each matching item
+    # in the result, and the items are not returned. This methodology is more performant
+    # as large quantifies of objects are fetched in batches and all of them do
+    # not have to be kept in memory after the query finishes executing. This is the recommended
+    # method of processing large result sets.
+    # @example
+    #  query = Parse::Query.new("_User", :created_at.before => DateTime.now)
+    #  users = query.results # => Array of Parse::User objects.
+    #
+    #  query = Parse::Query.new("_User", limit: :max)
+    #
+    #  query.results do |user|
+    #   # recommended; more memory efficient
+    #  end
+    #
+    # @param raw [Boolean] whether to get the raw hash results of the query instead of
+    #   a set of Parse::Object subclasses.
+    # @yield a block to iterate for each object that matched the query.
+    # @return [Array<Hash>] if raw is set to true, a set of Parse JSON hashes.
+    # @return [Array<Parse::Object>] if raw is set to false, a list of matching Parse::Object subclasses.
     def results(raw: false)
       if @results.nil?
         if @limit.nil? || @limit.to_i <= 1_000
@@ -393,18 +705,32 @@ module Parse
     end
     alias_method :result, :results
 
+    # Builds objects based on the set of Parse JSON hashes in an array.
+    # @param list [Array<Hash>] a list of Parse JSON hashes
+    # @return [Array<Parse::Object>] an array of Parse::Object subclasses.
     def decode(list)
       list.map { |m| Parse::Object.build(m, @table) }.compact
     end
 
+    # @return [Hash]
     def as_json(*args)
       compile.as_json
     end
 
+    # Returns a compiled query without encoding the where clause.
+    # @param includeClassName [Boolean] whether to include the class name of the collection
+    #  in the resulting compiled query.
+    # @return [Hash] a hash representing the prepared query request.
     def prepared(includeClassName: false)
       compile(encode: false, includeClassName: includeClassName)
     end
 
+    # Complies the query and runs all prepare callbacks.
+    # @param encode [Boolean] whether to encode the `where` clause to a JSON string.
+    # @param includeClassName [Boolean] whether to include the class name of the collection.
+    # @return [Hash] a hash representing the prepared query request.
+    # @see #before_prepare
+    # @see #after_prepare
     def compile(encode: true, includeClassName: false)
       run_callbacks :prepare do
         q = {} #query
@@ -432,26 +758,15 @@ module Parse
       end
     end
 
+    # @return [Hash] a hash representing just the `where` clause of this query.
     def compile_where
       self.class.compile_where( @where || [] )
     end
 
-    def self.compile_where(where)
-      constraint_reduce( where )
-    end
-
-    def self.constraint_reduce(clauses)
-      # TODO: Need to add proper constraint merging
-      clauses.reduce({}) do |clause, subclause|
-        #puts "Merging Subclause: #{subclause.as_json}"
-
-        clause.deep_merge!( subclause.as_json || {} )
-        clause
-      end
-    end
-
-    def print
-      puts JSON.pretty_generate( as_json )
+    # Retruns a formatted JSON string representing the query, useful for debugging.
+    # @return [String]
+    def pretty
+      JSON.pretty_generate( as_json )
     end
 
   end # Query