parse-stack 1.5.1 → 1.5.2

data/lib/parse/model/associations/has_one.rb

@@ -5,18 +5,112 @@ require_relative '../pointer'
 require_relative 'collection_proxy'
 require_relative 'pointer_collection_proxy'
 require_relative 'relation_collection_proxy'
-# a given Parse Pointer. The key of the property is implied to be the
-# name of the class/parse table that contains the foreign associated record.
-# All belongs to relationship column types have the special data type of :pointer.
+
 module Parse
   module Associations
-
+    # The `has_one` creates a one-to-one association with another Parse class.
+    # This association says that the other class in the association contains a
+    # foreign pointer column which references instances of this class. If your
+    # model contains a column that is a Parse pointer to another class, you should
+    # use `belongs_to` for that association instead.
+    #
+    # Defining a `has_one` property generates a helper query method to fetch a
+    # particular record from a foreign class. This is useful for setting up the
+    # inverse relationship accessors of a `belongs_to`. In the case of the
+    # `has_one` relationship, the `:field` option represents the name of the
+    # column of the foreign class where the Parse pointer is stored. By default,
+    # the lower-first camel case version of the Parse class name is used.
+    #
+    # In the example below, a `Band` has a local column named `manager` which has
+    # a pointer to a `Parse::User` (_:user_) record. This setups up the accessor for `Band`
+    # objects to access the band's manager.
+    #
+    # Since we know there is a column named `manager` in the `Band` class that
+    # points to a single `Parse::User`, you can setup the inverse association
+    # read accessor in the `Parse::User` class. Note, that to change the
+    # association, you need to modify the `manager` property on the band instance
+    # since it contains the `belongs_to` property.
+    #
+    #  # every band has a manager
+    #  class Band < Parse::Object
+    #    belongs_to :manager, as: :user
+    #  end
+    #
+    #  band = Band.first id: '12345'
+    #  # the user represented by this manager
+    #  user = band.manger
+    #
+    #  # every user manages a band
+    #  class Parse::User
+    #    # inverse relationship to `Band.belongs_to :manager`
+    #    has_one :band, field: :manager
+    #  end
+    #
+    #  user = Parse::User.first
+    #
+    #  user.band # similar to performing: Band.first(:manager => user)
+    #
+    #
+    # You may optionally use `has_one` with scopes, in order to fine tune the
+    # query result. Using the example above, you can customize the query with
+    # a scope that only fetches the association if the band is approved. If
+    # the association cannot be fetched, `nil` is returned.
+    #
+    #  # adding to previous example
+    #  class Band < Parse::Object
+    #    property :approved, :boolean
+    #    property :approved_date, :date
+    #  end
+    #
+    #  # every user manages a band
+    #  class Parse::User
+    #    has_one :recently_approved, ->{ where(order: :approved_date.desc) }, field: :manager, as: :band
+    #    has_one :band_by_status, ->(status) { where(approved: status) },  field: :manager, as: :band
+    #  end
+    #
+    #  # gets the band most recently approved
+    #  user.recently_approved
+    #  # equivalent: Band.first(manager: user, order: :approved_date.desc)
+    #
+    #  # fetch the managed band that is not approved
+    #  user.band_by_status(false)
+    #  # equivalent: Band.first(manager: user, approved: false)
+    #
+    # @see Parse::Associations::BelongsTo
+    # @see Parse::Associations::HasMany
     module HasOne
 
+      # @!method self.has_one(key, scope = nil, opts = {})
+      # Creates a one-to-one association with another Parse model.
+      # @param [Symbol] key The singularized version of the foreign class and the name of the
+      #   *foreign* column in the foreign Parse table where the pointer is stored.
+      # @param [Proc] scope A proc that can customize the query by applying
+      #   additional constraints when fetching the associated record. Works similarly as
+      #   ActiveModel associations described in section {http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html Customizing the Query}
+      # @option opts [Symbol] :field override the name of the remote column
+      #  where the pointer is stored. By default this is inferred as
+      #  the columnized of the key parameter.
+      # @option opts [Symbol] :as override the inferred Parse::Object subclass.
+      #  By default this is inferred as the singularized camel case version of
+      #  the key parameter. This option allows you to override the Parse model used
+      #  to perform the query for the association, while allowing you to have a
+      #  different accessor name.
+      # @option opts [Boolean] scope_only Setting this option to `true`,
+      #  makes the association fetch based only on the scope provided and does
+      #  not use the local instance object as a foreign pointer in the query.
+      #  This allows for cases where another property of the local class, is
+      #  needed to match the resulting records in the association.
+      # @see String#columnize
+      # @see Associations::HasMany.has_many
+      # @return [Parse::Object] a Parse::Object subclass when using the accessor
+      #  when fetching the association.
+
+      # @!visibility private
       def self.included(base)
         base.extend(ClassMethods)
       end
 
+      # @!visibility private
       module ClassMethods
 
         # has one are not property but instance scope methods

data/lib/parse/model/associations/pointer_collection_proxy.rb

@@ -7,21 +7,31 @@ require 'active_support/inflector'
 require 'active_support/core_ext/object'
 require_relative 'collection_proxy'
 
-# A PointerCollectionProxy is a collection proxy that only allows Parse Pointers (Objects)
-# to be part of the collection. This is done by typecasting the collection to a particular
-# Parse class. Ex. An Artist may have several Song objects. Therefore an Artist could have a
-# column :songs, that is an array (collection) of Song (Parse::Object) objects.
-# Because this collection is typecasted, we can do some more interesting things.
-module Parse
 
+module Parse
+  # A PointerCollectionProxy is a collection proxy that only allows Parse Pointers (Objects)
+  # to be part of the collection. This is done by typecasting the collection to a particular
+  # Parse class. Ex. An Artist may have several Song objects. Therefore an Artist could have a
+  # column :songs, that is an array (collection) of Song (Parse::Object subclass) objects.
   class PointerCollectionProxy < CollectionProxy
 
+    # @!attribute [rw] collection
+    #  The internal backing store of the collection.
+    # @return [Array<Parse::Object>]
+    # @see CollectionProxy#collection
     def collection=(c)
       notify_will_change!
       @collection = c
     end
-    # When we add items, we will verify that they are of type Parse::Pointer at a minimum.
-    # If they are not, and it is a hash, we check to see if it is a Parse hash.
+
+    # Add Parse::Objects to the collection.
+    # @overload add(parse_object)
+    #  Add a Parse::Object or Parse::Pointer to this collection.
+    #  @param parse_object [Parse::Object,Parse::Pointer] the object to add
+    # @overload add(parse_objects)
+    #  Add an array of Parse::Objects or Parse::Pointers to this collection.
+    #  @param parse_objects [Array<Parse::Object,Parse::Pointer>] the array to append.
+    # @return [Array<Parse::Object>] the collection
     def add(*items)
       notify_will_change! if items.count > 0
       items.flatten.parse_objects.each do |item|
@@ -30,7 +40,14 @@ module Parse
       @collection
     end
 
-    # removes items from the collection
+    # Removes Parse::Objects from the collection.
+    # @overload remove(parse_object)
+    #  Remove a Parse::Object or Parse::Pointer to this collection.
+    #  @param parse_object [Parse::Object,Parse::Pointer] the object to remove
+    # @overload remove(parse_objects)
+    #  Remove an array of Parse::Objects or Parse::Pointers from this collection.
+    #  @param parse_objects [Array<Parse::Object,Parse::Pointer>] the array of objects to remove.
+    # @return [Array<Parse::Object>] the collection
     def remove(*items)
       notify_will_change! if items.count > 0
       items.flatten.parse_objects.each do |item|
@@ -39,36 +56,51 @@ module Parse
       @collection
     end
 
+    # Atomically add a set of Parse::Objects to this collection.
+    # This is done by making the API request directly with Parse server; the
+    # local object is not updated with changes.
+    # @see CollectionProxy#add!
+    # @see #add_unique!
     def add!(*items)
       super(items.flatten.parse_pointers)
     end
 
+    # Atomically add a set of Parse::Objects to this collection for those not already
+    # in the collection.
+    # This is done by making the API request directly with Parse server; the
+    # local object is not updated with changes.
+    # @see CollectionProxy#add_unique!
+    # @see #add!
     def add_unique!(*items)
       super(items.flatten.parse_pointers)
     end
 
+    # Atomically remove a set of Parse::Objects to this collection.
+    # This is done by making the API request directly with Parse server; the
+    # local object is not updated with changes.
+    # @see CollectionProxy#remove!
     def remove!(*items)
       super(items.flatten.parse_pointers)
     end
 
-    # We define a fetch and fetch! methods on array
-    # that contain pointer objects. This will make requests for each object
-    # in the array that is of pointer state (object with unfetch data) and fetch
-    # them in parallel.
-
+    # Force fetch the set of pointer objects in this collection.
+    # @see Array.fetch_objects!
     def fetch!
       collection.fetch_objects!
     end
 
+    # Fetch the set of pointer objects in this collection.
+    # @see Array.fetch_objects
     def fetch
       collection.fetch_objects
     end
-    # Even though we may have full Parse Objects in the collection, when updating
-    # or storing them in Parse, we actually just want Parse::Pointer objects.
+
+    # Encode the collection as a JSON object of Parse::Pointers.
     def as_json(*args)
       collection.parse_pointers.as_json
     end
 
+    # @return [Array<Parse::Pointer>] an array of pointers representing this collection.
     def parse_pointers
       collection.parse_pointers
     end

data/lib/parse/model/associations/relation_collection_proxy.rb

@@ -6,39 +6,44 @@ require 'active_support/inflector'
 require 'active_support/core_ext/object'
 require_relative 'pointer_collection_proxy'
 
-# The RelationCollectionProxy is similar to a PointerCollectionProxy except that
-# there is no actual "array" object in Parse. Parse treats relation through an
-# intermediary table (a.k.a. join table). Whenever a developer wants the
-# contents of a collection, the foreign table needs to be queried instead.
-# In this scenario, the parse_class: initializer argument should be passed in order to
-# know which remote table needs to be queried in order to fetch the items of the collection.
-#
-# Unlike managing an array of Pointers, relations in Parse are done throug atomic operations,
-# which have a specific API. The design of this proxy is to maintain two sets of lists,
-# items to be added to the relation and a separate list of items to be removed from the
-# relation.
-#
-# Because this relationship is based on queryable Parse table, we are also able to
-# not just get all the items in a collection, but also provide additional constraints to
-# get matching items within the relation collection.
-#
-# When creating a Relation proxy, all the delegate methods defined in the superclasses
-# need to be implemented, in addition to a few others with the key parameter:
-# _relation_query and _commit_relation_updates . :'key'_relation_query should return a
-# Parse::Query object that is properly tied to the foreign table class related to this object column.
-# Example, if an Artist has many Song objects, then the query to be returned by this method
-# should be a Parse::Query for the class 'Song'.
-# Because relation changes are separate from object changes, you can call save on a
-# relation collection to save the current add and remove operations. Because the delegate needs
-# to be informed of the changes being committed, it will be notified
-# through :'key'_commit_relation_updates message. The delegate is also in charge of
-# clearing out the change information for the collection if saved successfully.
-
 module Parse
-
+  # The RelationCollectionProxy is similar to a PointerCollectionProxy except that
+  # there is no actual "array" object in Parse. Parse treats relation through an
+  # intermediary table (a.k.a. join table). Whenever a developer wants the
+  # contents of a collection, the foreign table needs to be queried instead.
+  # In this scenario, the parse_class: initializer argument should be passed in order to
+  # know which remote table needs to be queried in order to fetch the items of the collection.
+  #
+  # Unlike managing an array of Pointers, relations in Parse are done throug atomic operations,
+  # which have a specific API. The design of this proxy is to maintain two sets of lists,
+  # items to be added to the relation and a separate list of items to be removed from the
+  # relation.
+  #
+  # Because this relationship is based on queryable Parse table, we are also able to
+  # not just get all the items in a collection, but also provide additional constraints to
+  # get matching items within the relation collection.
+  #
+  # When creating a Relation proxy, all the delegate methods defined in the superclasses
+  # need to be implemented, in addition to a few others with the key parameter:
+  # _relation_query and _commit_relation_updates . :'key'_relation_query should return a
+  # Parse::Query object that is properly tied to the foreign table class related to this object column.
+  # Example, if an Artist has many Song objects, then the query to be returned by this method
+  # should be a Parse::Query for the class 'Song'.
+  # Because relation changes are separate from object changes, you can call save on a
+  # relation collection to save the current add and remove operations. Because the delegate needs
+  # to be informed of the changes being committed, it will be notified
+  # through :'key'_commit_relation_updates message. The delegate is also in charge of
+  # clearing out the change information for the collection if saved successfully.
+  # @see PointerCollectionProxy
   class RelationCollectionProxy < PointerCollectionProxy
 
     define_attribute_methods :additions, :removals
+    # @!attribute [r] removals
+    #  The objects that have been newly removed to this collection
+    # @return [Array<Parse::Object>]
+    # @!attribute [r] additions
+    #  The objects that have been newly added to this collection
+    # @return [Array<Parse::Object>]
     attr_reader :additions, :removals
 
     def initialize(collection = nil, delegate: nil, key: nil, parse_class: nil)
@@ -65,9 +70,14 @@ module Parse
     end
 
 
-    # add the current items to the relation. The process of adding it
-    # is adding it to the @additions array and making sure it is
-    # removed from the @removals array.
+    # Add Parse::Objects to the relation.
+    # @overload add(parse_object)
+    #  Add a Parse::Object or Parse::Pointer to this relation.
+    #  @param parse_object [Parse::Object,Parse::Pointer] the object to add
+    # @overload add(parse_objects)
+    #  Add an array of Parse::Objects or Parse::Pointers to this relation.
+    #  @param parse_objects [Array<Parse::Object,Parse::Pointer>] the array to append.
+    # @return [Array<Parse::Object>] the collection
     def add(*items)
       items = items.flatten.parse_objects
       return @collection if items.empty?
@@ -85,9 +95,14 @@ module Parse
       @collection
     end
 
-    # removes the current items from the relation.
-    # The process of removing is deleting it from the @removals array,
-    # and adding it to the @additions array.
+    # Removes Parse::Objects from the relation.
+    # @overload remove(parse_object)
+    #  Remove a Parse::Object or Parse::Pointer to this relation.
+    #  @param parse_object [Parse::Object,Parse::Pointer] the object to remove
+    # @overload remove(parse_objects)
+    #  Remove an array of Parse::Objects or Parse::Pointers from this relation.
+    #  @param parse_objects [Array<Parse::Object,Parse::Pointer>] the array of objects to remove.
+    # @return [Array<Parse::Object>] the collection
     def remove(*items)
       items = items.flatten.parse_objects
       return @collection if items.empty?
@@ -103,31 +118,41 @@ module Parse
       @collection
     end
 
+    # Atomically add a set of Parse::Objects to this relation.
+    # This is done by making the API request directly with Parse server; the
+    # local object is not updated with changes.
     def add!(*items)
       return false unless @delegate.respond_to?(:op_add_relation!)
       items = items.flatten.parse_pointers
       @delegate.send :op_add_relation!, @key, items
     end
 
+    # Atomically add a set of Parse::Objects to this relation.
+    # This is done by making the API request directly with Parse server; the
+    # local object is not updated with changes.
     def add_unique!(*items)
       return false unless @delegate.respond_to?(:op_add_relation!)
       items = items.flatten.parse_pointers
       @delegate.send :op_add_relation!, @key, items
     end
 
+    # Atomically remove a set of Parse::Objects to this relation.
+    # This is done by making the API request directly with Parse server; the
+    # local object is not updated with changes.
     def remove!(*items)
       return false unless @delegate.respond_to?(:op_remove_relation!)
       items = items.flatten.parse_pointers
       @delegate.send :op_remove_relation!, @key, items
     end
 
-    # save the changes if any
+    # Save the changes to the relation
     def save
       unless @removals.empty? && @additions.empty?
         forward :"#{@key}_commit_relation_updates"
       end
     end
 
+    # @see #add
     def <<(*list)
       list.each { |d| add(d) }
       @collection

data/lib/parse/model/bytes.rb

@@ -6,31 +6,37 @@ require 'active_support/core_ext/object'
 require_relative "model"
 require 'base64'
 
-# Support for Bytes type in Parse
+
 module Parse
 
+  # Support for the Bytes type in Parse
   class Bytes < Model
     ATTRIBUTES = {__type: :string, base64: :string }.freeze
+    # @return [String] the base64 string representing the content
     attr_accessor :base64
-    def parse_class; TYPE_BYTES; end;
+    # @return [TYPE_BYTES]
+    def self.parse_class; TYPE_BYTES; end;
+    # @return [TYPE_BYTES]
     def parse_class; self.class.parse_class; end;
     alias_method :__type, :parse_class
 
     # initialize with a base64 string or a Bytes object
+    # @param bytes [String] The content as base64 string.
     def initialize(bytes = "")
       @base64 = (bytes.is_a?(Bytes) ? bytes.base64 : bytes).dup
     end
 
+    # @return [Hash]
     def attributes
       ATTRIBUTES
     end
 
-    # takes a string and base64 encodes it
+    # Base64 encode and set the instance contents
     def encode(s)
       @base64 = Base64.encode64(s)
     end
 
-    # decode the internal data
+    # Get the content as decoded base64 bytes
     def decoded
       Base64.decode64(@base64 || "")
     end
@@ -43,7 +49,7 @@ module Parse
       end
     end
 
-    # two Bytes objects are equal if they have the same base64 signature
+    # Two Parse::Bytes objects are equal if they have the same base64 signature
     def ==(u)
       return false unless u.is_a?(self.class)
       @base64 == u.base64

data/lib/parse/model/classes/installation.rb

@@ -3,23 +3,70 @@
 require_relative '../object'
 
 module Parse
-
+  # This class represents the data and columns contained in the standard Parse
+  # `_Installation` collection. This class is also responsible for managing the
+  # device tokens for mobile devices in order to use push notifications. All queries done
+  # to send pushes using Parse::Push are performed against the Installation collection.
+  # An installation object represents an instance of your app being installed
+  # on a device. These objects are used to store subscription data for
+  # installations which have subscribed to one or more push notification channels.
+  # @see Push
   class Installation < Parse::Object
-    parse_class Parse::Model::CLASS_INSTALLATION
 
+    parse_class Parse::Model::CLASS_INSTALLATION
+    # This field only has meaning for Android installations that use the GCM
+    # push type. It is reserved for directing Parse to send pushes to this
+    # installation with an alternate GCM sender ID. This field should generally
+    # not be set unless you are uploading installation data from another push
+    # provider. If you set this field, then you must set the GCM API key
+    # corresponding to this GCM sender ID in your Parse application’s push settings.
+    # @return [String]
     property :gcm_sender_id, :string, field: :GCMSenderId
+    # A unique identifier for this installation’s client application. In iOS, this is the Bundle Identifier.
+    # @return [String]
     property :app_identifier
+    # The display name of the client application to which this installation belongs.
+    # @return [String]
     property :app_name
+    # The version string of the client application to which this installation belongs.
+    # @return [String]
     property :app_version
+    # A number field representing the last known application badge for iOS installations.
+    # @return [Integer]
     property :badge, :integer
+    # An array of the channels to which a device is currently subscribed.
+    # Note that **channelUris** (the Microsoft-generated push URIs for Windows devices) is
+    # not supported at this time.
+    # @return [Array]
     property :channels, :array
+    # The Apple or Google generated token used to deliver messages to the APNs
+    # or GCM push networks respectively.
+    # @return [String]
     property :device_token
+    # @return [Integer]
     property :device_token_last_modified, :integer
-    property :device_type
+    # The type of device, “ios”, “android”, “winrt”, “winphone”, or “dotnet” (readonly).
+    # This property is implemented as a Parse::Stack enumeration.
+    # @return [String]
+    property :device_type, enum: [:ios, :android, :winrt, :winphone, :dotnet]
+    # Universally Unique Identifier (UUID) for the device used by Parse. It
+    # must be unique across all of an app’s installations. (readonly).
+    # @return [String]
     property :installation_id
+    # The locale for this device.
+    # @return [String]
     property :locale_identifier
+    # The version of the Parse SDK which this installation uses.
+    # @return [String]
     property :parse_version
+    # This field is reserved for directing Parse to the push delivery network
+    # to be used. If the device is registered to receive pushes via GCM, this
+    # field will be marked “gcm”. If this device is not using GCM, and is
+    # using Parse’s push notification service, it will be blank (readonly).
+    # @return [String]
     property :push_type
+    # The current time zone where the target device is located. This should be an IANA time zone identifier.
+    # @return [String]
     property :time_zone
 
   end