gcloud 0.6.3 → 0.7.0

data/lib/gcloud/datastore/dataset/lookup_results.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "delegate"
 
 module Gcloud
@@ -24,14 +24,16 @@ module Gcloud
       # contains the entities as well as the Keys that were deferred from
       # the results and the Entities that were missing in the dataset.
       #
+      # Please be cautious when treating the QueryResults as an Array.
+      # Many common Array methods will return a new Array instance.
+      #
+      # @example
       #   entities = dataset.find_all key1, key2, key3
       #   entities.size #=> 3
       #   entities.deferred #=> []
       #   entities.missing #=> []
       #
-      # Please be cautious when treating the LookupResults as an Array. Many
-      # common Array methods will return a new Array instance.
-      #
+      # @example Caution, many Array methods will return a new Array instance:
       #   entities = dataset.find_all key1, key2, key3
       #   entities.size #=> 3
       #   entities.deferred #=> []

data/lib/gcloud/datastore/dataset/query_results.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "delegate"
 
 module Gcloud
@@ -24,13 +24,15 @@ module Gcloud
       # the Entities from the query as well as the query's cursor and
       # more_results value.
       #
+      # Please be cautious when treating the QueryResults as an Array.
+      # Many common Array methods will return a new Array instance.
+      #
+      # @example
       #   entities = dataset.run query
       #   entities.size #=> 3
       #   entities.cursor #=> "c3VwZXJhd2Vzb21lIQ"
       #
-      # Please be cautious when treating the QueryResults as an Array.
-      # Many common Array methods will return a new Array instance.
-      #
+      # @example Caution, many Array methods will return a new Array instance:
       #   entities = dataset.run query
       #   entities.size #=> 3
       #   entities.end_cursor #=> "c3VwZXJhd2Vzb21lIQ"

data/lib/gcloud/datastore/entity.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/datastore/key"
 require "gcloud/datastore/properties"
 require "gcloud/datastore/proto"
@@ -20,11 +20,12 @@ require "gcloud/datastore/proto"
 module Gcloud
   module Datastore
     ##
-    # = Entity
+    # # Entity
     #
     # Entity represents a Datastore record.
-    # Every Entity has a Key, and a list of properties.
+    # Every Entity has a {Key}, and a list of properties.
     #
+    # @example
     #   entity = Gcloud::Datastore::Entity.new
     #   entity.key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
     #   entity["name"] = "Heidi Henderson"
@@ -45,19 +46,11 @@ module Gcloud
       ##
       # Retrieve a property value by providing the name.
       #
-      # === Parameters
-      #
-      # +prop_name+::
-      #   The name of the property. (+String+ or +Symbol+)
-      #
-      # === Returns
-      #
-      # Object if the property exists, +nil+ if the property doesn't exist
+      # @param [String, Symbol] prop_name The name of the property.
       #
-      # === Example
-      #
-      # Properties can be retrieved with a string name:
+      # @return [Object, nil] Returns `nil` if the property doesn't exist
       #
+      # @example Properties can be retrieved with a string name:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -65,8 +58,7 @@ module Gcloud
       #   user = dataset.find "User", "heidi@example.com"
       #   user["name"] #=> "Heidi Henderson"
       #
-      # Or with a symbol name:
-      #
+      # @example Or with a symbol name:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -81,17 +73,10 @@ module Gcloud
       ##
       # Set a property value by name.
       #
-      # === Parameters
-      #
-      # +prop_name+::
-      #   The name of the property. (+String+ or +Symbol+)
-      # +prop_value+::
-      #   The value of the property. (+Object+)
-      #
-      # === Example
-      #
-      # Properties can be set with a string name:
+      # @param [String, Symbol] prop_name The name of the property.
+      # @param [Object] prop_value The value of the property.
       #
+      # @example Properties can be set with a string name:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -99,8 +84,7 @@ module Gcloud
       #   user = dataset.find "User", "heidi@example.com"
       #   user["name"] = "Heidi H. Henderson"
       #
-      # Or with a symbol name:
-      #
+      # @example Or with a symbol name:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -116,12 +100,9 @@ module Gcloud
       # Retrieve properties in a hash-like structure.
       # Properties can be accessed or set by string or symbol.
       #
-      # === Returns
-      #
-      # Gcloud::Datastore::Properties
-      #
-      # === Example
+      # @return [Gcloud::Datastore::Properties]
       #
+      # @example
       #   entity.properties[:name] = "Heidi H. Henderson"
       #   entity.properties["name"] #=> "Heidi H. Henderson"
       #
@@ -129,19 +110,16 @@ module Gcloud
       #     puts "property #{name} has a value of #{value}"
       #   end
       #
-      # A property's existance can be determined by calling exist?
-      #
+      # @example A property's existence can be determined by calling `exist?`:
       #   entity.properties.exist? :name #=> true
       #   entity.properties.exist? "name" #=> true
       #   entity.properties.exist? :expiration #=> false
       #
-      # A property can be removed from the entity.
-      #
+      # @example A property can be removed from the entity:
       #   entity.properties.delete :name
       #   entity.save
       #
-      # The properties can be converted to a hash:
-      #
+      # @example The properties can be converted to a hash:
       #   prop_hash = entity.properties.to_h
       #
       attr_reader :properties
@@ -149,10 +127,10 @@ module Gcloud
       ##
       # Sets the Key that identifies the entity.
       #
-      # === Example
-      #
-      # The Key can be set before the entity is saved.
+      # Once the entity is saved, the key is frozen and immutable. Trying to set
+      # a key when immutable will raise a `RuntimeError`.
       #
+      # @example The Key can be set before the entity is saved:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -161,9 +139,7 @@ module Gcloud
       #   entity.key = Gcloud::Datastore::Key.new "User"
       #   dataset.save entity
       #
-      # Once the entity is saved, the key is frozen and immutable.
-      # Trying to set a key when immutable will raise a +RuntimeError+.
-      #
+      # @example Once the entity is saved, the key is frozen and immutable:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -182,8 +158,7 @@ module Gcloud
       ##
       # Indicates if the record is persisted. Default is false.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -201,17 +176,30 @@ module Gcloud
 
       ##
       # Indicates if a property is flagged to be excluded from the
-      # Datastore indexes. The default value is false.
+      # Datastore indexes. The default value is `false`. This is another way of
+      # saying that values are indexed by default.
       #
-      # Single property values will return a single flag setting.
+      # If the property is multi-valued, each value in the list can be managed
+      # separately for exclusion from indexing. Calling this method for a
+      # multi-valued property will return an array that contains the `excluded`
+      # boolean value for each corresponding value in the property. For example,
+      # if a multi-valued property contains `["a", "b"]`, and only the value
+      # `"b"` is indexed (meaning that `"a"`' is excluded), the return value for
+      # this method will be `[true, false]`.
       #
+      # @see https://cloud.google.com/datastore/docs/concepts/indexes#Datastore_Unindexed_properties
+      #   Unindexed properties
+      #
+      # @example Single property values will return a single flag setting:
       #   entity["age"] = 21
       #   entity.exclude_from_indexes? "age" #=> false
       #
-      # Array property values will return an array of flag settings.
-      #
+      # @example A multi-valued property will return an array of flag settings:
       #   entity["tags"] = ["ruby", "code"]
-      #   entity.exclude_from_indexes? "tags" #=> [false, false]
+      #   entity.exclude_from_indexes! "tags", [true, false]
+      #
+      #   entity.exclude_from_indexes? "tags" #=> [true, false]
+      #
       def exclude_from_indexes? name
         value = self[name]
         flag = @_exclude_indexes[name.to_s]
@@ -219,31 +207,50 @@ module Gcloud
       end
 
       ##
-      # Flag a property to be excluded from the Datastore indexes.
-      # Setting true will exclude the property from the indexes.
-      # Setting false will include the property on any applicable indexes.
-      # The default value for the flag is false.
-      #
+      # Sets whether a property should be excluded from the Datastore indexes.
+      # Setting `true` will exclude the property from the indexes.
+      # Setting `false` will include the property on any applicable indexes.
+      # The default value is `false`. This is another way of saying that values
+      # are indexed by default.
+      #
+      # If the property is multi-valued, each value in the list can be managed
+      # separately for exclusion from indexing. When you call this method for a
+      # multi-valued property, you can pass either a single boolean argument to
+      # be applied to all of the values, or an array that contains the boolean
+      # argument for each corresponding value in the property. For example,
+      # if a multi-valued property contains `["a", "b"]`, and only the value
+      # `"b"` should be indexed (meaning that `"a"`' should be excluded), you
+      # should pass the array: `[true, false]`.
+      #
+      # @param [String] name the property name
+      # @param [Boolean, Array<Boolean>, nil] flag whether the value or values
+      #   should be excluded from indexing
+      # @yield [value] a block yielding each value of the property
+      # @yieldparam [Object] value a value of the property
+      # @yieldreturn [Boolean] `true` if the value should be excluded from
+      #   indexing
+      #
+      # @see https://cloud.google.com/datastore/docs/concepts/indexes#Datastore_Unindexed_properties
+      #   Unindexed properties
+      #
+      # @example
       #   entity["age"] = 21
       #   entity.exclude_from_indexes! "age", true
       #
-      # Properties that are arrays can be given multiple exclude flags.
-      #
+      # @example Multi-valued properties can be given multiple exclude flags:
       #   entity["tags"] = ["ruby", "code"]
       #   entity.exclude_from_indexes! "tags", [true, false]
       #
-      # Or, array properties can be given a single flag that will be applied
-      # to each item in the array.
-      #
+      # @example Or, a single flag can be applied to all values in a property:
       #   entity["tags"] = ["ruby", "code"]
       #   entity.exclude_from_indexes! "tags", true
       #
-      # Flags can also be set with a block for either single and array values.
-      #
+      # @example Flags can also be set with a block:
       #   entity["age"] = 21
       #   entity.exclude_from_indexes! "age" do |age|
       #     age > 18
       #   end
+      #
       def exclude_from_indexes! name, flag = nil, &block
         name = name.to_s
         flag = block if block_given?
@@ -255,9 +262,8 @@ module Gcloud
       end
 
       ##
-      # Convert the Entity to a protocol buffer object.
-      # This is not part of the public API.
-      def to_proto #:nodoc:
+      # @private Convert the Entity to a protocol buffer object.
+      def to_proto
         entity = Proto::Entity.new.tap do |e|
           e.key = @key.to_proto
           e.property = Proto.to_proto_properties @properties.to_h
@@ -267,9 +273,8 @@ module Gcloud
       end
 
       ##
-      # Create a new Entity from a protocol buffer object.
-      # This is not part of the public API.
-      def self.from_proto proto #:nodoc:
+      # @private Create a new Entity from a protocol buffer object.
+      def self.from_proto proto
         entity = Entity.new
         entity.key = Key.from_proto proto.key
         Array(proto.property).each do |p|
@@ -285,11 +290,11 @@ module Gcloud
       # Disabled rubocop because this is intentionally complex.
 
       ##
-      # Map the exclude flag object to value.
+      # @private Map the exclude flag object to value.
       # The flag object can be a boolean, Proc, or Array.
       # Procs will be called and passed in the value.
       # This will return an array of flags for an array value.
-      def map_exclude_flag_to_value flag, value #:nodoc:
+      def map_exclude_flag_to_value flag, value
         if value.is_a? Array
           if flag.is_a? Proc
             value.map { |v| !!flag.call(v) }
@@ -310,8 +315,8 @@ module Gcloud
       end
 
       ##
-      # Update the exclude data after a new object is created.
-      def update_exclude_indexes! entity #:nodoc:
+      # @private Update the exclude data after a new object is created.
+      def update_exclude_indexes! entity
         @_exclude_indexes = {}
         Array(entity.property).each do |property|
           @_exclude_indexes[property.name] = !property.value.indexed
@@ -323,8 +328,8 @@ module Gcloud
       end
 
       ##
-      # Update the indexed values before the object is saved.
-      def update_properties_indexed! entity #:nodoc:
+      # @private Update the indexed values before the object is saved.
+      def update_properties_indexed! entity
         Array(entity.property).each do |property|
           excluded = exclude_from_indexes? property.name
           if excluded.is_a? Array

data/lib/gcloud/datastore/errors.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,26 +12,27 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/errors"
 
 module Gcloud
   module Datastore
     ##
-    # = Datastore Error
+    # # Datastore Error
     #
     # Base Datastore exception class.
     class Error < Gcloud::Error
     end
 
     ##
-    # = KeyfileError
+    # # KeyfileError
     #
     # Raised when a keyfile is not correct.
     class KeyfileError < Gcloud::Datastore::Error
     end
 
     ##
-    # = ApiError
+    # # ApiError
     #
     # Raised when an API call is not successful.
     class ApiError < Gcloud::Datastore::Error
@@ -44,7 +44,8 @@ module Gcloud
       # The response object of the failed HTTP request.
       attr_reader :response
 
-      def initialize method, response = nil #:nodoc:
+      # @private
+      def initialize method, response = nil
         super("API call to #{method} was not successful")
         @method = method
         @response = response
@@ -52,14 +53,14 @@ module Gcloud
     end
 
     ##
-    # = PropertyError
+    # # PropertyError
     #
     # Raised when a property is not correct.
     class PropertyError < Gcloud::Datastore::Error
     end
 
     ##
-    # = TransactionError
+    # # TransactionError
     #
     # General error for Transaction problems.
     class TransactionError < Gcloud::Datastore::Error
@@ -67,7 +68,8 @@ module Gcloud
       # An error that occurred within the transaction. (optional)
       attr_reader :inner
 
-      def initialize message, inner = nil #:nodoc:
+      # @private
+      def initialize message, inner = nil
         super(message)
         @inner = inner
       end