gcloud 0.6.3 → 0.7.0

data/lib/gcloud/search/field_value.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,22 +12,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module Gcloud
   module Search
     ##
-    # = FieldValue
+    # # FieldValue
     #
     # FieldValue is used to represent a value that belongs to a field. (See
-    # Fields and FieldValues)
+    # {Fields} and {FieldValues})
     #
     # A field value must have a type. A value that is a Numeric will default to
     # `:number`, while a DateTime will default to `:datetime`. If a type is not
     # provided it will be determined by looking at the value.
     #
     # String values (text, html, atom) can also specify a lang value, which is
-    # an {ISO 639-1
-    # code}[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes].
+    # an [ISO 639-1
+    # code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -41,8 +42,8 @@ module Gcloud
     #     puts "* #{value} (#{value.type}) [#{value.lang}]"
     #   end
     #
-    # For more information see {Documents and
-    # fields}[https://cloud.google.com/search/documents_indexes].
+    # @see https://cloud.google.com/search/documents_indexes Documents and
+    #   fields
     #
     class FieldValue < DelegateClass(::Object)
       attr_reader :type, :lang, :name
@@ -51,40 +52,33 @@ module Gcloud
       # Disabled because there are links in the docs that are long.
 
       ##
-      # Create a new FieldValue object.
-      #
-      # === Parameters
+      # @private Create a new FieldValue object.
       #
-      # +value+::
-      #   The value to add to the field. (+String+ or +Datetime+ or +Float+)
-      # +type+::
-      #   The type of the field value. A field can have multiple values with
+      # @param [String, Datetime, Float] value The value to add to the field.
+      # @param [Symbol] type The type of the field value. A field can have multiple values with
       #   same or different types; however, it cannot have multiple Timestamp or
-      #   number values. (+Symbol+)
+      #   number values.
       #
       #   The following values are supported:
-      #   * +: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+)
-      # +name+::
-      #   The name of the field. New values will be configured with this name.
-      #   (+String+)
+      # @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).
+      # @param [String] name The name of the field. New values will be configured with this name.
       #
-      def initialize value, type: nil, lang: nil, name: nil #:nodoc:
+      def initialize value, type: nil, lang: nil, name: nil
         super value
         if type
           @type = type.to_s.downcase.to_sym
@@ -105,14 +99,14 @@ module Gcloud
       end
 
       ##
-      # Get the original value object.
-      def value #:nodoc:
+      # @private Get the original value object.
+      def value
         __getobj__
       end
 
       ##
-      # Create a new FieldValue instance from a value Hash.
-      def self.from_raw field_value, name = nil #:nodoc:
+      # @private Create a new FieldValue instance from a value Hash.
+      def self.from_raw field_value, name = nil
         value = field_value["stringValue"]
         type = field_value["stringFormat"]
         if field_value["timestampValue"]
@@ -130,8 +124,8 @@ module Gcloud
       end
 
       ##
-      # Create a raw Hash object containing the field value.
-      def to_raw #:nodoc:
+      # @private Create a raw Hash object containing the field value.
+      def to_raw
         case type
         when :atom, :default, :html, :text
           {
@@ -150,7 +144,7 @@ module Gcloud
 
       protected
 
-      def infer_type #:nodoc:
+      def infer_type
         if respond_to? :rfc3339
           :datetime
         elsif value.is_a? Numeric # must call on original object...

data/lib/gcloud/search/field_values.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,12 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud/search/field_value"
 
 module Gcloud
   module Search
     ##
-    # = FieldValues
+    # # FieldValues
     #
     # The list of values for a field.
     #
@@ -30,8 +30,9 @@ module Gcloud
     # Each field on a document can have multiple values. FieldValues is the
     # object that manages the multiple values. Values can be the same or
     # different types; however, it cannot have multiple datetime (DateTime) or
-    # number (Float) values. (See FieldValue)
+    # number (Float) values. (See {FieldValue})
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -44,25 +45,20 @@ module Gcloud
     #     puts "* #{value} (#{value.type}) [#{value.lang}]"
     #   end
     #
-    # For more information see {Documents and
-    # fields}[https://cloud.google.com/search/documents_indexes].
+    # @see https://cloud.google.com/search/documents_indexes Documents and
+    #   Indexes
     #
     class FieldValues
       include Enumerable
 
       ##
-      # Create a new FieldValues object.
-      #
-      # === Parameters
+      # @private Create a new FieldValues object.
       #
-      # +name+::
-      #   The name of the field. New values will be configured with this name.
-      #   (+String+)
-      # +values+::
-      #   A list of values to add to the field. (+Array+ of +FieldValue+
-      #   objects)
+      # @param [String] name The name of the field. New values will be
+      #   configured with this name.
+      # @param [Array<FieldValue>] values A list of values to add to the field.
       #
-      def initialize name, values = [] # :nodoc:
+      def initialize name, values = []
         @name = name
         @values = values
       end
@@ -77,58 +73,47 @@ module Gcloud
       # before an element. Additionally, an empty array is returned when the
       # starting index for an element range is at the end of the array.
       #
-      # Returns nil if the index (or starting index) are out of range.
+      # @return [FieldValue, nil] Returns nil if the index (or starting index)
+      #   are out of range.
       def [] index
         @values[index]
       end
 
-      # rubocop:disable Metrics/LineLength
-      # Disabled because there are links in the docs that are long.
-
       ##
-      # Add a new value. The field name will be added to the value object. If
+      # 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
+      # `:datetime` or `:number`, then the added value will replace any existing
       # values of the same type (since there can be only one).
       #
-      # === Parameters
-      #
-      # +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, 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+)
+      # @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).
       #
-      # === Returns
-      #
-      # FieldValue
-      #
-      # === Example
+      # @return [FieldValue]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -151,22 +136,15 @@ module Gcloud
         @values << new_field
       end
 
-      # rubocop:enable Metrics/LineLength
-
       ##
       # Deletes all values that are equal to value.
       #
-      # === Parameters
-      #
-      # +value+::
-      #   The value to remove from the list of values.
+      # @param [String] value The value to remove from the list of values.
       #
-      # === Returns
-      #
-      # The last deleted +FieldValue+, or +nil+ if no matching value is found.
-      #
-      # === Example
+      # @return [FieldValue, nil] The last deleted `FieldValue`, or `nil` if no
+      #   matching value is found.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -185,22 +163,15 @@ module Gcloud
 
       ##
       # Deletes the value at the specified index, returning that FieldValue, or
-      # +nil+ if the index is out of range.
-      ##
-      # Deletes all values that are equal to value.
+      # `nil` if the index is out of range.
       #
-      # === Parameters
+      # @param [String] index The index of the value to be removed from the list
+      #   of values.
       #
-      # +index+::
-      #   The index of the value to be removed from the list of values.
-      #
-      # === Returns
-      #
-      # The deleted +FieldValue+ found at the specified index, or # +nil+ if the
-      # index is out of range.
-      #
-      # === Example
+      # @return [FieldValue] The deleted `FieldValue` found at the specified
+      #   index, or # `nil` if the index is out of range.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -222,8 +193,7 @@ module Gcloud
       #
       # An Enumerator is returned if no block is given.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -241,21 +211,21 @@ module Gcloud
       end
 
       ##
-      # Returns +true+ if there are no values.
+      # Returns `true` if there are no values.
       def empty?
         @values.empty?
       end
 
       ##
-      # Create a new FieldValues instance from a name and values Hash.
-      def self.from_raw name, values #:nodoc:
+      # @private Create a new FieldValues instance from a name and values Hash.
+      def self.from_raw name, values
         field_values = values.map { |value| FieldValue.from_raw value, name }
         FieldValues.new name, field_values
       end
 
       ##
-      # Create a raw Hash object containing all the field values.
-      def to_raw #:nodoc:
+      # @private Create a raw Hash object containing all the field values.
+      def to_raw
         { "values" => @values.map(&:to_raw) }
       end
     end

data/lib/gcloud/search/fields.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/search/field_values"
 require "gcloud/search/field_value"
 
 module Gcloud
   module Search
     ##
-    # = Fields
+    # # Fields
     #
     # Fields is the object that provides access to a document's fields.
     #
@@ -30,8 +30,9 @@ module Gcloud
     #
     # A field can have multiple values with same or different types; however, it
     # cannot have multiple datetime (DateTime) or number (Float) values. (See
-    # FieldValues and FieldValue)
+    # {FieldValues} and {FieldValue})
     #
+    # @example
     #   require "gcloud"
     #
     #   gcloud = Gcloud.new
@@ -47,33 +48,27 @@ module Gcloud
     #     end
     #   end
     #
-    # For more information see {Documents and
-    # fields}[https://cloud.google.com/search/documents_indexes].
+    # @see https://cloud.google.com/search/documents_indexes Documents and
+    #   fields
     #
     class Fields
       include Enumerable
 
       ##
-      # Create a new empty fields object.
-      def initialize #:nodoc:
+      # @private Create a new empty fields object.
+      def initialize
         @hash = {}
       end
 
       ##
       # 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
+      # @param [String] name The name of the field. New values will be
+      #   configured with this name.
       #
-      # FieldValues
-      #
-      # === Example
+      # @return [FieldValues]
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -90,51 +85,40 @@ module Gcloud
         @hash[name] ||= FieldValues.new name
       end
 
-      # 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
+      # `:datetime` or `:number`, then the added value will replace any existing
       # values of the same type (since there can be only one).
       #
-      # === Parameters
-      #
-      # +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
@@ -154,18 +138,12 @@ module Gcloud
         @hash[name].add value, type: type, lang: lang
       end
 
-      # rubocop:enable Metrics/LineLength
-
       ##
       # Deletes a field and all values.
       #
-      # === Parameters
-      #
-      # +name+::
-      #   The name of the field. (+String+)
-      #
-      # === Example
+      # @param [String] name The name of the field.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -183,8 +161,7 @@ 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.
       #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -208,6 +185,7 @@ module Gcloud
       ##
       # Returns a new array populated with all the field names.
       #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
@@ -226,8 +204,8 @@ module Gcloud
       end
 
       ##
-      # Create a new Fields instance from a raw Hash.
-      def self.from_raw raw #:nodoc:
+      # @private Create a new Fields instance from a raw Hash.
+      def self.from_raw raw
         hsh = {}
         raw.each do |k, v|
           hsh[k] = FieldValues.from_raw k, v["values"]
@@ -238,8 +216,9 @@ module Gcloud
       end
 
       ##
-      # Create a raw Hash object containing all the field names and values.
-      def to_raw #:nodoc:
+      # @private Create a raw Hash object containing all the field names and
+      # values.
+      def to_raw
         hsh = {}
         @hash.each do |k, v|
           hsh[k] = v.to_raw unless v.empty?
@@ -250,8 +229,8 @@ module Gcloud
       protected
 
       ##
-      # Find all the fields that have values. This is needed because a field is
-      # required to have at least one value.
+      # @private Find all the fields that have values. This is needed because a
+      # field is required to have at least one value.
       #
       # Users can remove all values, and the empty FieldValues object will
       # remain in the internal hash. This is the same as not having that field.
@@ -259,7 +238,7 @@ module Gcloud
       # Users can also reference the field by name before adding a value. So we
       # have multiple valid use cases which add an empty FieldValues object to
       # the hash.
-      def fields_with_values #:nodoc:
+      def fields_with_values
         @hash.select { |_name, values| values.any? }
       end
     end