gcloud 0.6.3 → 0.7.0

data/lib/gcloud/datastore/connection.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,17 +12,20 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "faraday"
 
 module Gcloud
   module Datastore
     ##
+    # @private
+    #
     # Represent the HTTP connection to the Datastore,
     # as well as the Datastore API calls.
     #
     # This class only deals with Protocol Buffer objects,
     # and is not part of the public API.
-    class Connection #:nodoc:
+    class Connection
       API_VERSION = "v1beta2"
       API_URL = "https://www.googleapis.com"
 
@@ -33,13 +35,15 @@ module Gcloud
 
       ##
       # The Credentials object for signing HTTP requests.
-      attr_accessor :credentials #:nodoc:
+      attr_accessor :credentials
 
       ##
       # Create a new Connection instance.
       #
+      # @example
       #   conn = Gcloud::Datastore.Connection.new "my-todo-project",
       #     Gcloud::Datastore::Credentials.new("/path/to/keyfile.json")
+      #
       def initialize dataset_id, credentials
         @dataset_id = dataset_id
         @credentials = credentials
@@ -114,24 +118,24 @@ module Gcloud
 
       ##
       # The default HTTP headers to be sent on all API calls.
-      def default_http_headers #:nodoc:
+      def default_http_headers
         @default_http_headers ||= {
           "User-Agent"   => "gcloud-node/#{Gcloud::VERSION}",
           "Content-Type" => "application/x-protobuf" }
       end
       ##
       # Update the default HTTP headers.
-      attr_writer :default_http_headers #:nodoc:
+      attr_writer :default_http_headers
 
       ##
       # The HTTP object that makes calls to Datastore.
       # This must be a Faraday object.
-      def http #:nodoc:
+      def http
         @http ||= Faraday.new url: http_host
       end
       ##
       # Update the HTTP object.
-      attr_writer :http #:nodoc:
+      attr_writer :http
 
       ##
       # The Datastore API URL.
@@ -146,7 +150,7 @@ module Gcloud
         @http_host = new_http_host
       end
 
-      def inspect #:nodoc:
+      def inspect
         "#{self.class}(#{@dataset_id})"
       end
 

data/lib/gcloud/datastore/credentials.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,17 +12,20 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/credentials"
 
 module Gcloud
   module Datastore
     ##
+    # @private
+    #
     # Authentication credentials to Google Cloud.
     # The most common way to create this object is to provide the path
     # to the JSON keyfile downloaded from Google Cloud.
     #
-    # https://developers.google.com/accounts/docs/application-default-credentials
-    class Credentials < Gcloud::Credentials #:nodoc:
+    # @see https://developers.google.com/accounts/docs/application-default-credentials
+    class Credentials < Gcloud::Credentials
       SCOPE = ["https://www.googleapis.com/auth/datastore",
                "https://www.googleapis.com/auth/userinfo.email"]
       PATH_ENV_VARS = %w(DATASTORE_KEYFILE GCLOUD_KEYFILE GOOGLE_CLOUD_KEYFILE)
@@ -32,7 +34,7 @@ module Gcloud
 
       ##
       # Sign OAuth 2.0 API calls.
-      def sign_http_request request #:nodoc:
+      def sign_http_request request
         if @client
           @client.fetch_access_token! if @client.expired?
           @client.generate_authenticated_request request: request

data/lib/gcloud/datastore/dataset.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/gce"
 require "gcloud/datastore/connection"
 require "gcloud/datastore/credentials"
@@ -25,15 +25,18 @@ require "gcloud/datastore/dataset/query_results"
 module Gcloud
   module Datastore
     ##
-    # = Dataset
+    # # Dataset
     #
     # Dataset is the data saved in a project's Datastore.
     # Dataset is analogous to a database in relational database world.
     #
     # Gcloud::Datastore::Dataset is the main object for interacting with
-    # Google Datastore. Gcloud::Datastore::Entity objects are created,
+    # Google Datastore. {Gcloud::Datastore::Entity} objects are created,
     # read, updated, and deleted by Gcloud::Datastore::Dataset.
     #
+    # See {Gcloud#datastore}
+    #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -44,15 +47,15 @@ module Gcloud
     #
     #   tasks = dataset.run query
     #
-    # See Gcloud#datastore
     class Dataset
-      attr_accessor :connection #:nodoc:
+      # @private
+      attr_accessor :connection
 
       ##
-      # Creates a new Dataset instance.
+      # @private Creates a new Dataset instance.
       #
-      # See Gcloud#datastore
-      def initialize project, credentials #:nodoc:
+      # See {Gcloud#datastore}
+      def initialize project, credentials
         project = project.to_s # Always cast to a string
         fail ArgumentError, "project is missing" if project.empty?
         @connection = Connection.new project, credentials
@@ -61,8 +64,7 @@ module Gcloud
       ##
       # The Datastore project connected to.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new "my-todo-project",
@@ -76,8 +78,8 @@ module Gcloud
       end
 
       ##
-      # Default project.
-      def self.default_project #:nodoc:
+      # @private Default project.
+      def self.default_project
         ENV["DATASTORE_DATASET"] ||
           ENV["DATASTORE_PROJECT"] ||
           ENV["GCLOUD_PROJECT"] ||
@@ -88,19 +90,12 @@ module Gcloud
       ##
       # Generate IDs for a Key before creating an entity.
       #
-      # === Parameters
-      #
-      # +incomplete_key+::
-      #   A Key without +id+ or +name+ set. (+Key+)
-      # +count+::
-      #   The number of new key IDs to create. (+Integer+)
-      #
-      # === Returns
-      #
-      # Array of Gcloud::Datastore::Key
+      # @param [Key] incomplete_key A Key without `id` or `name` set.
+      # @param [String] count The number of new key IDs to create.
       #
-      # === Example
+      # @return [Array<Gcloud::Datastore::Key>]
       #
+      # @example
       #   empty_key = dataset.key "Task"
       #   task_keys = dataset.allocate_ids empty_key, 5
       #
@@ -119,18 +114,12 @@ module Gcloud
       ##
       # Persist one or more entities to the Datastore.
       #
-      # === Parameters
+      # @param [Entity] entities One or more entity objects to be saved without
+      #   `id` or `name` set.
       #
-      # +entities+::
-      #   One or more entity objects to be saved without +id+ or +name+ set.
-      #   (+Entity+)
-      #
-      # === Returns
-      #
-      # Array of Gcloud::Datastore::Entity
-      #
-      # === Example
+      # @return [Array<Gcloud::Datastore::Entity>]
       #
+      # @example
       #   dataset.save task1, task2
       #
       def save *entities
@@ -144,27 +133,17 @@ module Gcloud
       ##
       # Retrieve an entity by providing key information.
       #
-      # === Parameters
-      #
-      # +key_or_kind+::
-      #   A Key object or +kind+ string value. (+Key+ or +String+)
-      # +id_or_name+::
-      #   The Key's +id+ or +name+ value if a +kind+ was provided in the first
-      #   parameter. (+Integer+ or +String+ or +nil+)
-      #
-      # === Returns
+      # @param [Key, String] key_or_kind A Key object or `kind` string value.
+      # @param [Integer, String, nil] id_or_name The Key's `id` or `name` value
+      #   if a `kind` was provided in the first parameter.
       #
-      # Gcloud::Datastore::Entity or +nil+
-      #
-      # === Example
-      #
-      # Finding an entity with a key:
+      # @return [Gcloud::Datastore::Entity, nil]
       #
+      # @example Finding an entity with a key:
       #   key = dataset.key "Task", 123456
       #   task = dataset.find key
       #
-      # Finding an entity with a +kind+ and +id+/+name+:
-      #
+      # @example Finding an entity with a `kind` and `id`/`name`:
       #   task = dataset.find "Task", 123456
       #
       def find key_or_kind, id_or_name = nil
@@ -179,17 +158,11 @@ module Gcloud
       ##
       # Retrieve the entities for the provided keys.
       #
-      # === Parameters
-      #
-      # +keys+::
-      #   One or more Key objects to find records for. (+Key+)
-      #
-      # === Returns
-      #
-      # Gcloud::Datastore::Dataset::LookupResults
+      # @param [Key] keys One or more Key objects to find records for.
       #
-      # === Example
+      # @return [Gcloud::Datastore::Dataset::LookupResults]
       #
+      # @example
       #   gcloud = Gcloud.new
       #   dataset = gcloud.datastore
       #   key1 = dataset.key "Task", 123456
@@ -208,17 +181,12 @@ module Gcloud
       ##
       # Remove entities from the Datastore.
       #
-      # === Parameters
+      # @param [Entity, Key] entities_or_keys One or more Entity or Key objects
+      #   to remove.
       #
-      # +entities_or_keys+::
-      #   One or more Entity or Key objects to remove. (+Entity+ or +Key+)
-      #
-      # === Returns
-      #
-      # +true+ if successful
-      #
-      # === Example
+      # @return [Boolean] Returns `true` if successful
       #
+      # @example
       #   gcloud = Gcloud.new
       #   dataset = gcloud.datastore
       #   dataset.delete entity1, entity2
@@ -237,26 +205,17 @@ module Gcloud
       ##
       # Retrieve entities specified by a Query.
       #
-      # === Parameters
-      #
-      # +query+::
-      #   The Query object with the search criteria. (+Query+)
-      # +namespace+::
-      #   The namespace the query is to run within. (+String+)
-      #
-      # === Returns
+      # @param [Query] query The Query object with the search criteria.
+      # @param [String] namespace The namespace the query is to run within.
       #
-      # Gcloud::Datastore::Dataset::QueryResults
-      #
-      # === Examples
+      # @return [Gcloud::Datastore::Dataset::QueryResults]
       #
+      # @example
       #   query = dataset.query("Task").
       #     where("completed", "=", true)
       #   tasks = dataset.run query
       #
-      # The query can optionally run within namespace when the +namespace+
-      # option is provided:
-      #
+      # @example Run the query within a namespace with the `namespace` option:
       #   query = Gcloud::Datastore::Query.new.kind("Task").
       #     where("completed", "=", true)
       #   tasks = dataset.run query, namespace: "ns~todo-project"
@@ -274,10 +233,10 @@ module Gcloud
       ##
       # Creates a Datastore Transaction.
       #
-      # === Example
-      #
-      # Runs the given block in a database transaction:
+      # @yield [tx] a block yielding a new transaction
+      # @yieldparam [Transaction] tx the transaction object
       #
+      # @example Runs the given block in a database transaction:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -294,8 +253,7 @@ module Gcloud
       #     end
       #   end
       #
-      # Alternatively, if no block is given a Transaction object is returned:
-      #
+      # @example If no block is given, a Transaction object is returned:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -333,23 +291,16 @@ module Gcloud
       # Create a new Query instance. This is a convenience method to make the
       # creation of Query objects easier.
       #
-      # === Parameters
-      #
-      # +kinds+::
-      #   The kind of entities to query. This is optional. (+String+)
-      #
-      # === Returns
+      # @param [String] kinds The kind of entities to query. This is optional.
       #
-      # Gcloud::Datastore::Query
-      #
-      # === Example
+      # @return [Gcloud::Datastore::Query]
       #
+      # @example
       #   query = dataset.query("Task").
       #     where("completed", "=", true)
       #   tasks = dataset.run query
       #
-      # This code is equivalent to the following:
-      #
+      # @example The previous example is equivalent to:
       #   query = Gcloud::Datastore::Query.new.
       #     kind("Task").
       #     where("completed", "=", true)
@@ -365,23 +316,16 @@ module Gcloud
       # Create a new Key instance. This is a convenience method to make the
       # creation of Key objects easier.
       #
-      # === 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
-      #
-      # Gcloud::Datastore::Key
+      # @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.
       #
-      # === Example
+      # @return [Gcloud::Datastore::Key]
       #
+      # @example
       #   key = dataset.key "User", "heidi@example.com"
       #
-      # This code is equivalent to the following:
-      #
+      # @example The previous example is equivalent to:
       #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
       #
       def key kind = nil, id_or_name = nil
@@ -392,50 +336,39 @@ module Gcloud
       # Create a new empty Entity instance. This is a convenience method to make
       # the creation of Entity objects easier.
       #
-      # === Parameters
-      #
-      # +key_or_kind+::
-      #   A Key object or +kind+ string value. This is optional. (+Key+ or
-      #   +String+ or +nil+)
-      # +id_or_name+::
-      #   The Key's +id+ or +name+ value if a +kind+ was provided in the first
-      #   parameter. (+Integer+ or +String+ or +nil+)
-      #
-      # === Returns
+      # @param [Key, String, nil] key_or_kind A Key object or `kind` string
+      #   value. This is optional.
+      # @param [Integer, String, nil] id_or_name The Key's `id` or `name` value
+      #   if a `kind` was provided in the first parameter.
+      # @yield [entity] a block yielding a new entity
+      # @yieldparam [Entity] entity the newly created entity object
       #
-      # Gcloud::Datastore::Entity
-      #
-      # === Examples
+      # @return [Gcloud::Datastore::Entity]
       #
+      # @example
       #   entity = dataset.entity
       #
-      # This code is equivalent to the following:
-      #
+      # @example The previous example is equivalent to:
       #   entity = Gcloud::Datastore::Entity.new
       #
-      # The key can also be passed in as an object:
-      #
+      # @example The key can also be passed in as an object:
       #   key = dataset.key "User", "heidi@example.com"
       #   entity = dataset.entity key
       #
-      # Or the key values can be passed in as parameters:
-      #
+      # @example Or the key values can be passed in as parameters:
       #   entity = dataset.entity "User", "heidi@example.com"
       #
-      # This code is equivalent to the following:
-      #
+      # @example The previous example is equivalent to:
       #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
       #   entity = Gcloud::Datastore::Entity.new
       #   entity.key = key
       #
-      # The newly created entity object can also be configured using a block:
-      #
+      # @example The newly created entity can also be configured using a block:
       #   user = dataset.entity "User", "heidi@example.com" do |u|
       #     u["name"] = "Heidi Henderson"
       #  end
       #
-      # This code is equivalent to the following:
-      #
+      # @example The previous example is equivalent to:
       #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
       #   entity = Gcloud::Datastore::Entity.new
       #   entity.key = key
@@ -477,15 +410,15 @@ module Gcloud
       end
 
       ##
-      # Save a key to be given an ID when comitted.
-      def auto_id_register entity #:nodoc:
+      # @private Save a key to be given an ID when comitted.
+      def auto_id_register entity
         @_auto_id_entities ||= []
         @_auto_id_entities << entity
       end
 
       ##
-      # Update saved keys with new IDs post-commit.
-      def auto_id_assign_ids auto_ids #:nodoc:
+      # @private Update saved keys with new IDs post-commit.
+      def auto_id_assign_ids auto_ids
         @_auto_id_entities ||= []
         Array(auto_ids).each_with_index do |key, index|
           entity = @_auto_id_entities[index]
@@ -495,9 +428,9 @@ module Gcloud
       end
 
       ##
-      # Add entities to a Mutation, and register they key to be
+      # @private Add entities to a Mutation, and register they key to be
       # updated with an auto ID if needed.
-      def save_entities_to_mutation entities, mutation #:nodoc:
+      def save_entities_to_mutation entities, mutation
         entities.each do |entity|
           if entity.key.id.nil? && entity.key.name.nil?
             mutation.insert_auto_id << entity.to_proto