gcloud 0.6.3 → 0.7.0

data/lib/gcloud/datastore/key.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,29 +12,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/datastore/proto"
 
 module Gcloud
   module Datastore
     ##
-    # = Key
+    # # Key
     #
     # Every Datastore record has an identifying key, which includes the record's
     # entity kind and a unique identifier. The identifier may be either a key
     # name string, assigned explicitly by the application, or an integer numeric
     # ID, assigned automatically by Datastore.
     #
+    # @example
     #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
+    #
     class Key
       ##
       # The kind of the Key.
       #
-      # === Returns
-      #
-      # +String+
-      #
-      # === Example
+      # @return [String]
       #
+      # @example
       #   key = Gcloud::Datastore::Key.new "User"
       #   key.kind #=> "User"
       #   key.kind = "Task"
@@ -45,12 +44,9 @@ module Gcloud
       ##
       # The dataset_id of the Key.
       #
-      # === Returns
-      #
-      # +String+
-      #
-      # === Example
+      # @return [String]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new "my-todo-project",
@@ -65,12 +61,9 @@ module Gcloud
       ##
       # The namespace of the Key.
       #
-      # === Returns
-      #
-      # +String+ or +nil+
-      #
-      # === Example
+      # @return [String, nil]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new "my-todo-project",
@@ -85,19 +78,13 @@ module Gcloud
       ##
       # Create a new Key instance.
       #
-      # === Parameters
-      #
-      # +kind+::
-      #   The kind of the Key. This is optional. (+String+)
-      # +id_or_name+::
-      #   The id or name of the Key. This is optional. (+Integer+ or +String+)
-      #
-      # === Returns
+      # @param [String] kind The kind of the Key. This is optional.
+      # @param [Integer, String] id_or_name The id or name of the Key. This is
+      #   optional.
       #
-      # Gcloud::Datastore::Dataset::Key
-      #
-      # === Example
+      # @return [Gcloud::Datastore::Dataset::Key]
       #
+      # @example
       #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
       #
       def initialize kind = nil, id_or_name = nil
@@ -110,15 +97,12 @@ module Gcloud
       end
 
       ##
-      # Set the id of the Key.
+      # @private Set the id of the Key.
       # If a name is already present it will be removed.
       #
-      # === Returns
-      #
-      # +Integer+ or +nil+
-      #
-      # === Example
+      # @return [Integer, nil]
       #
+      # @example
       #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
       #   key.id #=> nil
       #   key.name #=> "heidi@example.com"
@@ -126,7 +110,7 @@ module Gcloud
       #   key.id #=> 654321
       #   key.name #=> nil
       #
-      def id= new_id #:nodoc:
+      def id= new_id
         @name = nil if new_id
         @id = new_id
       end
@@ -134,27 +118,21 @@ module Gcloud
       ##
       # The id of the Key.
       #
-      # === Returns
-      #
-      # +Integer+ or +nil+
-      #
-      # === Example
+      # @return [Integer, nil]
       #
+      # @example
       #   key = Gcloud::Datastore::Key.new "User", 123456
       #   key.id #=> 123456
       #
       attr_reader :id
 
       ##
-      # Set the name of the Key.
+      # @private Set the name of the Key.
       # If an id is already present it will be removed.
       #
-      # === Returns
-      #
-      # +String+ or +nil+
-      #
-      # === Example
+      # @return [String, nil]
       #
+      # @example
       #   key = Gcloud::Datastore::Key.new "User", 123456
       #   key.id #=> 123456
       #   key.name #=> nil
@@ -162,7 +140,7 @@ module Gcloud
       #   key.id #=> nil
       #   key.name #=> "heidi@example.com"
       #
-      def name= new_name #:nodoc:
+      def name= new_name
         @id = nil if new_name
         @name = new_name
       end
@@ -170,30 +148,24 @@ module Gcloud
       ##
       # The name of the Key.
       #
-      # === Returns
-      #
-      # +String+ or +nil+
-      #
-      # === Example
+      # @return [String, nil]
       #
+      # @example
       #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
       #   key.name #=> "heidi@example.com"
       #
       attr_reader :name
 
       ##
-      # Set the parent of the Key.
+      # @private Set the parent of the Key.
       #
-      # === Returns
-      #
-      # +Key+ or +nil+
-      #
-      # === Example
+      # @return [Key, nil]
       #
+      # @example
       #   key = Gcloud::Datastore::Key.new "List", "todos"
       #   key.parent = Gcloud::Datastore::Key.new "User", "heidi@example.com"
       #
-      def parent= new_parent #:nodoc:
+      def parent= new_parent
         # store key if given an entity
         new_parent = new_parent.key if new_parent.respond_to? :key
         @parent = new_parent
@@ -202,12 +174,9 @@ module Gcloud
       ##
       # The parent of the Key.
       #
-      # === Returns
-      #
-      # +Key+ or +nil+
-      #
-      # === Example
+      # @return [Key, nil]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -226,12 +195,9 @@ module Gcloud
       # Each inner array contains two values, the kind and the id or name.
       # If neither an id or name exist then nil will be returned.
       #
-      # === Returns
-      #
-      # Array of arrays
-      #
-      # === Example
+      # @return [Array<Array<(String, String)>>]
       #
+      # @example
       #   key = Gcloud::Datastore::Key.new "List", "todos"
       #   key.parent = Gcloud::Datastore::Key.new "User", "heidi@example.com"
       #   key.path #=> [["User", "heidi@example.com"], ["List", "todos"]]
@@ -245,7 +211,7 @@ module Gcloud
       # Determine if the key is complete.
       # A complete key has either an id or a name.
       #
-      # Inverse of #incomplete?
+      # Inverse of {#incomplete?}
       def complete?
         !incomplete?
       end
@@ -254,15 +220,14 @@ module Gcloud
       # Determine if the key is incomplete.
       # An incomplete key has neither an id nor a name.
       #
-      # Inverse of #complete?
+      # Inverse of {#complete?}
       def incomplete?
         kind.nil? || (id.nil? && (name.nil? || name.empty?))
       end
 
       ##
-      # Convert the Key to a protocol buffer object.
-      # This is not part of the public API.
-      def to_proto #:nodoc:
+      # @private Convert the Key to a protocol buffer object.
+      def to_proto
         Proto::Key.new.tap do |k|
           k.path_element = path.map do |pe_kind, pe_id_or_name|
             Proto.new_path_element pe_kind, pe_id_or_name
@@ -274,9 +239,8 @@ module Gcloud
       # rubocop:disable all
 
       ##
-      # Create a new Key from a protocol buffer object.
-      # This is not part of the public API.
-      def self.from_proto proto #:nodoc:
+      # @private Create a new Key from a protocol buffer object.
+      def self.from_proto proto
         # Disable rules because the complexity here is neccessary.
         key_proto = proto.dup
         key = Key.new

data/lib/gcloud/datastore/properties.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,14 +12,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module Gcloud
   module Datastore
     ##
-    # = Properties
+    # # Properties
     #
     # Hash-like data structure for Datastore properties.
     #
-    # See Entity#properties
+    # See {Entity#properties}
     class Properties
       def initialize properties = {}
         @hash = {}

data/lib/gcloud/datastore/proto.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/proto/datastore_v1.pb"
 require "gcloud/datastore/errors"
 
@@ -21,6 +21,8 @@ module Gcloud
     # rubocop:disable all
 
     ##
+    # @private
+    #
     # Proto is the namespace that contains all Protocol Buffer objects.
     #
     # The methods in this module are for convenience in using the
@@ -30,7 +32,7 @@ module Gcloud
     # this module's existance, may change in the future.
     #
     # You have been warned.
-    module Proto #:nodoc:
+    module Proto
       def self.from_proto_value proto_value
         if !proto_value.timestamp_microseconds_value.nil?
           microseconds = proto_value.timestamp_microseconds_value
@@ -111,7 +113,7 @@ module Gcloud
         Time.at(microseconds / 1000000, microseconds % 1000000).utc
       end
 
-      #:nodoc:
+      @private
       PROP_FILTER_OPS = {
         "<"   => PropertyFilter::Operator::LESS_THAN,
         "lt"  => PropertyFilter::Operator::LESS_THAN,
@@ -245,7 +247,8 @@ module Gcloud
         end
       end
 
-      class Key #:nodoc:
+      # @private
+      class Key
         def dup
           proto_request_body = ""
           self.encode proto_request_body

data/lib/gcloud/datastore/query.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/entity"
 require "gcloud/datastore/key"
 require "gcloud/datastore/proto"
@@ -20,20 +20,24 @@ require "gcloud/datastore/proto"
 module Gcloud
   module Datastore
     ##
-    # = Query
+    # # Query
     #
     # Represents the search criteria against a Datastore.
     #
+    # @example
     #   query = Gcloud::Datastore::Query.new
     #   query.kind("Task").
     #     where("completed", "=", true)
     #
     #   entities = dataset.run query
+    #
     class Query
       ##
       # Returns a new query object.
       #
+      # @example
       #   query = Gcloud::Datastore::Query.new
+      #
       def initialize
         @_query = Proto::Query.new
       end
@@ -41,10 +45,12 @@ module Gcloud
       ##
       # Add the kind of entities to query.
       #
+      # @example
       #   query = Gcloud::Datastore::Query.new
       #   query.kind "Task"
       #
       #   all_tasks = dataset.run query
+      #
       def kind *kinds
         @_query.kind ||= Proto::KindExpression.new
         @_query.kind.name ||= []
@@ -55,11 +61,13 @@ module Gcloud
       ##
       # Add a property filter to the query.
       #
+      # @example
       #   query = Gcloud::Datastore::Query.new
       #   query.kind("Task").
       #     where("completed", "=", true)
       #
       #   completed_tasks = dataset.run query
+      #
       def where name, operator, value
         # Initialize filter
         @_query.filter ||= Proto.new_filter.tap do |f|
@@ -78,11 +86,13 @@ module Gcloud
       ##
       # Add a filter for entities that inherit from a key.
       #
+      # @example
       #   query = Gcloud::Datastore::Query.new
       #   query.kind("Task").
       #     ancestor(parent.key)
       #
       #   completed_tasks = dataset.run query
+      #
       def ancestor parent
         # Use key if given an entity
         parent = parent.key if parent.respond_to? :key
@@ -95,11 +105,13 @@ module Gcloud
       # To sort in descending order, provide a second argument
       # of a string or symbol that starts with "d".
       #
+      # @example
       #   query = Gcloud::Datastore::Query.new
       #   query.kind("Task").
       #     order("due", :desc)
       #
       #   sorted_tasks = dataset.run query
+      #
       def order name, direction = :asc
         @_query.order ||= []
         po = Proto::PropertyOrder.new
@@ -113,11 +125,13 @@ module Gcloud
       ##
       # Set a limit on the number of results to be returned.
       #
+      # @example
       #   query = Gcloud::Datastore::Query.new
       #   query.kind("Task").
       #     limit(10)
       #
       #   paginated_tasks = dataset.run query
+      #
       def limit num
         @_query.limit = num
         self
@@ -126,12 +140,14 @@ module Gcloud
       ##
       # Set an offset for the results to be returned.
       #
+      # @example
       #   query = Gcloud::Datastore::Query.new
       #   query.kind("Task").
       #     limit(10).
       #     offset(20)
       #
       #   paginated_tasks = dataset.run query
+      #
       def offset num
         @_query.offset = num
         self
@@ -140,12 +156,14 @@ module Gcloud
       ##
       # Set the cursor to start the results at.
       #
+      # @example
       #   query = Gcloud::Datastore::Query.new
       #   query.kind("Task").
       #     limit(10).
       #     cursor(task_cursor)
       #
       #   paginated_tasks = dataset.run query
+      #
       def start cursor
         @_query.start_cursor = Proto.decode_cursor cursor
         self
@@ -155,11 +173,13 @@ module Gcloud
       ##
       # Retrieve only select properties from the matched entities.
       #
+      # @example
       #   query = Gcloud::Datastore::Query.new
       #   query.kind("Task").
       #     select("completed", "due")
       #
       #   partial_tasks = dataset.run query
+      #
       def select *names
         @_query.projection ||= []
         @_query.projection += Proto.new_property_expressions(*names)
@@ -170,18 +190,21 @@ module Gcloud
       ##
       # Group results by a list of properties.
       #
+      # @example
       #   query = Gcloud::Datastore::Query.new
       #   query.kind("Task").
       #     group_by("completed")
       #
       #   grouped_tasks = dataset.run query
+      #
       def group_by *names
         @_query.group_by ||= []
         @_query.group_by += Proto.new_property_references(*names)
         self
       end
 
-      def to_proto #:nodoc:
+      # @private
+      def to_proto
         @_query
       end
     end