lib/gcloud/search/document.rb in gcloud-0.6.3 vs lib/gcloud/search/document.rb in gcloud-0.7.0
- old
+ new
@@ -1,6 +1,5 @@
-#--
# Copyright 2015 Google Inc. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
@@ -11,25 +10,28 @@
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# 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"
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
# search = gcloud.search
# index = search.index "products"
@@ -38,26 +40,27 @@
# document.add "price", 24.95
# index.save document
# 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
##
@@ -72,44 +75,39 @@
end
##
# 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
##
# 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
##
# Retrieve the field values associated to a field name.
#
- # === Parameters
+ # @param [String] name The name of the field. New values will be
+ # configured with this name.
#
- # +name+::
- # The name of the field. New values will be configured with this name.
- # (+String+)
+ # @return [FieldValues]
#
- # === Returns
- #
- # FieldValues
- #
- # === Example
- #
+ # @example
# require "gcloud"
#
# gcloud = Gcloud.new
# search = gcloud.search
# index = search.index "products"
@@ -122,68 +120,53 @@
#
def [] name
@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)
+ # `:datetime` or `:number`, then the added value will replace any existing
+ # values of the same type (since there can be only one).
#
- # === Parameters
+ # @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.
#
- # +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+)
- #
# 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).
#
- # === Example
- #
+ # @example
# require "gcloud"
#
# gcloud = Gcloud.new
# search = gcloud.search
# index = search.index "products"
@@ -198,22 +181,16 @@
#
def add name, value, type: nil, lang: nil
@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
+ # @param [String] name The name of the field.
#
- # +name+::
- # The name of the field. (+String+)
- #
- # === Example
- #
+ # @example
# require "gcloud"
#
# gcloud = Gcloud.new
# search = gcloud.search
# index = search.index "products"
@@ -226,14 +203,13 @@
end
##
# 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)
+ # (See {Fields#each})
#
- # === Example
- #
+ # @example
# require "gcloud"
#
# gcloud = Gcloud.new
# search = gcloud.search
# index = search.index "products"
@@ -251,12 +227,13 @@
@fields.each(&block)
end
##
# Returns a new array populated with all the field names.
- # (See Fields#names)
+ # (See {Fields#names})
#
+ # @example
# require "gcloud"
#
# gcloud = Gcloud.new
# search = gcloud.search
# index = search.index "products"
@@ -270,29 +247,29 @@
def names
@fields.names
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 ', '})"
"#{self.class}(doc_id: #{doc_id.inspect}#{insp_rank}#{insp_fields})"
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"])
doc
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
end
end