gcloud 0.6.3 → 0.7.0

data/lib/gcloud/search/api_client.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,16 +12,17 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/version"
 require "google/api_client"
 
 module Gcloud
   module Search
     ##
-    # Temporary substitute for Google::APIClient. Once the Search API is
-    # discoverable, initialization of this class in Connection should be
+    # @private Temporary substitute for Google::APIClient. Once the Search API
+    # is discoverable, initialization of this class in Connection should be
     # replaced with the Google API Client.
-    class APIClient #:nodoc:
+    class APIClient
       attr_accessor :authorization, :connection
 
       ##
@@ -50,7 +50,7 @@ module Gcloud
 
       ##
       # Return type for APIClient#discovered_api
-      class DiscoveredApi #:nodoc:
+      class DiscoveredApi
         def initialize name, version
           @name = name
           @version = version
@@ -70,7 +70,7 @@ module Gcloud
 
       ##
       # Return type for DiscoveredApi http verb methods
-      class ResourcePath #:nodoc:
+      class ResourcePath
         def initialize api_name, api_version, resource_root, resource_id_param
           @root = "https://#{api_name}.googleapis.com/#{api_version}" \
                   "/projects/{projectId}/#{resource_root}"
@@ -100,7 +100,7 @@ module Gcloud
 
       ##
       # Special-case return type for DiscoveredApi http search verb method
-      class IndexResourcePath < ResourcePath #:nodoc:
+      class IndexResourcePath < ResourcePath
         def search
           api_method :get, "/{indexId}/search"
         end

data/lib/gcloud/search/connection.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,25 +12,26 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/version"
 require "gcloud/search/api_client"
 
 module Gcloud
   module Search
     ##
-    # Represents the connection to Search,
+    # @private Represents the connection to Search,
     # as well as expose the API calls.
-    class Connection #:nodoc:
+    class Connection
       API_VERSION = "v1"
 
       attr_accessor :project
-      attr_accessor :credentials #:nodoc:
-      attr_accessor :client #:nodoc:
-      attr_accessor :connection #:nodoc:
+      attr_accessor :credentials
+      attr_accessor :client
+      attr_accessor :connection
 
       ##
       # Creates a new Connection instance.
-      def initialize project, credentials #:nodoc:
+      def initialize project, credentials
         @project = project
         @credentials = credentials
         client_config = {
@@ -120,7 +120,7 @@ module Gcloud
         )
       end
 
-      def inspect #:nodoc:
+      def inspect
         "#{self.class}(#{@project})"
       end
 

data/lib/gcloud/search/credentials.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,13 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/credentials"
 
 module Gcloud
   module Search
     ##
-    # Represents the Oauth2 signing logic for Search.
-    class Credentials < Gcloud::Credentials #:nodoc:
+    # @private Represents the Oauth2 signing logic for Search.
+    class Credentials < Gcloud::Credentials
       SCOPE = ["https://www.googleapis.com/auth/cloudsearch",
                "https://www.googleapis.com/auth/userinfo.email"]
       PATH_ENV_VARS = %w(SEARCH_KEYFILE GCLOUD_KEYFILE GOOGLE_CLOUD_KEYFILE)

data/lib/gcloud/search/document.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 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/search/document/list"
 require "gcloud/search/connection"
 require "gcloud/search/fields"
@@ -20,14 +20,16 @@ require "gcloud/search/fields"
 module Gcloud
   module Search
     ##
-    # = Document
+    # # Document
     #
     # A document is an object that stores data that can be searched. Each
-    # document has a #doc_id that is
-    # unique within its index, a #rank, and a list of #fields that contain typed
-    # data. Its field values can be accessed through hash-like methods such as
-    # #[] and #each.
+    # document has a {Gcloud::Search::Document#doc_id} that is unique within its
+    # index, a {Gcloud::Search::Document#rank}, and a list of
+    # {Gcloud::Search::Document#fields} that contain typed data. Its field
+    # values can be accessed through hash-like methods such as
+    # {Gcloud::Search::Document#[]} and {Gcloud::Search::Document#each}.
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -40,22 +42,23 @@ module Gcloud
     #   document.rank #=> 1443648166
     #   document["price"] #=> 24.95
     #
-    # For more information, see {Documents and
-    # Indexes}[https://cloud.google.com/search/documents_indexes].
+    # @see https://cloud.google.com/search/documents_indexes Documents and
+    #   Indexes
     #
     class Document
       ##
-      # Creates a new Document instance.
+      # @private Creates a new Document instance.
       #
-      def initialize #:nodoc:
+      def initialize
         @fields = Fields.new
         @raw = {}
       end
 
       ##
       # The unique identifier for the document. Can be set explicitly when the
-      # document is saved. (See Index#document and #doc_id= .) If missing, it is
-      # automatically assigned to the document when saved.
+      # document is saved. (See {Gcloud::Search::Index#document} and
+      # {Gcloud::Search::Document#doc_id=}.) If missing, it is automatically
+      # assigned to the document when saved.
       def doc_id
         @raw["docId"]
       end
@@ -74,8 +77,9 @@ module Gcloud
       ##
       # A positive integer which determines the default ordering of documents
       # returned from a search. The rank can be set explicitly when the document
-      # is saved. (See Index#document and #rank= .)  If missing, it is
-      # automatically assigned to the document when saved.
+      # is saved. (See {Gcloud::Search::Index#document} and
+      # {Gcloud::Search::Document#rank=}.)  If missing, it is automatically
+      # assigned to the document when saved.
       def rank
         @raw["rank"]
       end
@@ -83,12 +87,12 @@ module Gcloud
       ##
       # Sets the rank of the document.
       #
-      # The same rank should not be assigned to many documents, and should
-      # never be assigned to more than 10,000 documents. By default (when it is
-      # not specified or set to 0), it is set at the time the document is
-      # created to the number of seconds since January 1, 2011. The rank can be
-      # used in Index#search options +expressions+, +order+, and
-      # +fields+, where it is referenced as +rank+.
+      # The same rank should not be assigned to many documents, and should never
+      # be assigned to more than 10,000 documents. By default (when it is not
+      # specified or set to 0), it is set at the time the document is created to
+      # the number of seconds since January 1, 2011. The rank can be used in
+      # {Gcloud::Search::Index#search} options `expressions`, `order`, and
+      # `fields`, where it is referenced as `rank`.
       def rank= new_rank
         @raw["rank"] = new_rank
       end
@@ -96,18 +100,12 @@ module Gcloud
       ##
       # Retrieve the field values associated to a field name.
       #
-      # === Parameters
-      #
-      # +name+::
-      #   The name of the field. New values will be configured with this name.
-      #   (+String+)
-      #
-      # === Returns
-      #
-      # FieldValues
+      # @param [String] name The name of the field. New values will be
+      #   configured with this name.
       #
-      # === Example
+      # @return [FieldValues]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -124,64 +122,49 @@ module Gcloud
         @fields[name]
       end
 
-      # rubocop:disable Style/TrivialAccessors
-      # Disable rubocop because we want .fields to be listed with the other
-      # methods on the class.
+      # Trivial accessor because we want .fields to be listed with methods.
 
       ##
       # The fields in the document. Each field has a name (String) and a list of
-      # values (FieldValues). (See Fields)
+      # values ({FieldValues}). (See {Fields})
       def fields
         @fields
       end
 
-      # rubocop:enable Style/TrivialAccessors
-
-      # rubocop:disable Metrics/LineLength
-      # Disabled because there are links in the docs that are long.
-
       ##
       # Add a new value. If the field name does not exist it will be added. If
       # the field value is a DateTime or Numeric, or the type is set to
-      # +:datetime+ or +:number+, then the added value will replace any existing
-      # values of the same type (since there can be only one). (See Fields#add)
-      #
-      # === Parameters
+      # `:datetime` or `:number`, then the added value will replace any existing
+      # values of the same type (since there can be only one).
       #
-      # +name+::
-      #   The name of the field. (+String+)
-      # +value+::
-      #   The value to add to the field. (+String+ or +Datetime+ or +Float+)
-      # +type+::
-      #   The type of the field value. An attempt is made to set the correct
-      #   type when this option is missing, although it must be provided for
-      #   +:geo+ values. A field can have multiple values with same or different
-      #   types; however, it cannot have multiple +:datetime+ or +:number+
-      #   values. (+Symbol+)
+      # @param [String] name The name of the field.
+      # @param [String, Datetime, Float] value The value to add to the field.
+      # @param [Symbol] type The type of the field value. An attempt is made to
+      #   set the correct type when this option is missing, although it must be
+      #   provided for `:geo` values. A field can have multiple values with same
+      #   or different types; however, it cannot have multiple `:datetime` or
+      #   `:number` values.
       #
       #   The following values are supported:
-      #   * +:default+ - The value is a string. The format will be automatically
+      #
+      #   * `:default` - The value is a string. The format will be automatically
       #     detected. This is the default value for strings.
-      #   * +:text+ - The value is a string with maximum length 1024**2
+      #   * `:text` - The value is a string with maximum length 1024**2
       #     characters.
-      #   * +:html+ - The value is an HTML-formatted string with maximum length
+      #   * `:html` - The value is an HTML-formatted string with maximum length
       #     1024**2 characters.
-      #   * +:atom+ - The value is a string with maximum length 500 characters.
-      #   * +:geo+ - The value is a point on earth described by latitude and
+      #   * `:atom` - The value is a string with maximum length 500 characters.
+      #   * `:geo` - The value is a point on earth described by latitude and
       #     longitude coordinates, represented in string with any of the listed
-      #     {ways of writing
-      #     coordinates}[http://en.wikipedia.org/wiki/Geographic_coordinate_conversion].
-      #   * +:datetime+ - The value is a +DateTime+.
-      #   * +:number+ - The value is a +Numeric+ between -2,147,483,647 and
+      #     [ways of writing coordinates](http://en.wikipedia.org/wiki/Geographic_coordinate_conversion).
+      #   * `:datetime` - The value is a `DateTime`.
+      #   * `:number` - The value is a `Numeric` between -2,147,483,647 and
       #     2,147,483,647. The value will be stored as a double precision
       #     floating point value in Cloud Search.
-      # +lang+::
-      #   The language of a string value. Must be a valid {ISO 639-1
-      #   code}[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes].
-      #   (+String+)
-      #
-      # === Example
+      # @param [String] lang The language of a string value. Must be a valid
+      #   [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -200,18 +183,12 @@ module Gcloud
         @fields[name].add value, type: type, lang: lang
       end
 
-      # rubocop:enable Metrics/LineLength
-
       ##
-      # Deletes a field and all values. (See Fields#delete)
+      # Deletes a field and all values. (See {Fields#delete})
       #
-      # === Parameters
-      #
-      # +name+::
-      #   The name of the field. (+String+)
-      #
-      # === Example
+      # @param [String] name The name of the field.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -228,10 +205,9 @@ module Gcloud
       ##
       # Calls block once for each field, passing the field name and values pair
       # as parameters. If no block is given an enumerator is returned instead.
-      # (See Fields#each)
-      #
-      # === Example
+      # (See {Fields#each})
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -253,8 +229,9 @@ module Gcloud
 
       ##
       # Returns a new array populated with all the field names.
-      # (See Fields#names)
+      # (See {Fields#names})
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -272,8 +249,8 @@ module Gcloud
       end
 
       ##
-      # Override to keep working in interactive shells manageable.
-      def inspect #:nodoc:
+      # @private Override to keep working in interactive shells manageable.
+      def inspect
         insp_rank = ""
         insp_rank = ", rank: #{rank}" if rank
         insp_fields = ", fields: (#{fields.names.map(&:inspect).join ', '})"
@@ -281,8 +258,8 @@ module Gcloud
       end
 
       ##
-      # New Document from a raw data object.
-      def self.from_hash hash #:nodoc:
+      # @private New Document from a raw data object.
+      def self.from_hash hash
         doc = new
         doc.instance_variable_set "@raw", hash
         doc.instance_variable_set "@fields", Fields.from_raw(hash["fields"])
@@ -290,8 +267,8 @@ module Gcloud
       end
 
       ##
-      # Returns the Document data as a hash
-      def to_hash #:nodoc:
+      # @private Returns the Document data as a hash
+      def to_hash
         hash = @raw.dup
         hash["fields"] = @fields.to_raw
         hash

data/lib/gcloud/search/document/list.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 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.
 
+
 module Gcloud
   module Search
     class Document
@@ -25,7 +25,7 @@ module Gcloud
         attr_accessor :token
 
         ##
-        # Create a new Document::List with an array of Document instances.
+        # Create a new Document::List with an array of {Document} instances.
         def initialize arr = []
           super arr
         end
@@ -45,7 +45,7 @@ module Gcloud
         end
 
         ##
-        # Retrieves all documents by repeatedly loading pages until #next?
+        # Retrieves all documents by repeatedly loading pages until {#next?}
         # returns false. Returns the list instance for method chaining.
         def all
           while next?
@@ -57,8 +57,8 @@ module Gcloud
         end
 
         ##
-        # New Documents::List from a response object.
-        def self.from_response resp, index #:nodoc:
+        # @private New Documents::List from a response object.
+        def self.from_response resp, index
           data = JSON.parse resp.body
           documents = new(Array(data["documents"]).map do |doc_hash|
             Document.from_hash doc_hash

data/lib/gcloud/search/errors.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 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/errors"
 
 module Gcloud
@@ -33,13 +33,15 @@ module Gcloud
       # The errors encountered.
       attr_reader :errors
 
-      def initialize message, code, errors = [] #:nodoc:
+      # @private
+      def initialize message, code, errors = []
         super message
         @code   = code
         @errors = errors
       end
 
-      def self.from_response resp #:nodoc:
+      # @private
+      def self.from_response resp
         data = JSON.parse resp.body
         if data["error"]
           from_response_data data["error"]
@@ -50,11 +52,13 @@ module Gcloud
         from_response_status resp
       end
 
-      def self.from_response_data error #:nodoc:
+      # @private
+      def self.from_response_data error
         new error["message"], error["code"], error["errors"]
       end
 
-      def self.from_response_status resp #:nodoc:
+      # @private
+      def self.from_response_status resp
         if resp.status == 404
           new "#{resp.body}: #{resp.request.uri.request_uri}",
               resp.status