result.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,54 +10,53 @@
 # 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/result/list"
 require "gcloud/search/fields"
 
 module Gcloud
   module Search
     ##
-    # = Result
+    # # Result
     #
-    # See Gcloud#search
+    # See {Gcloud#search}
     class Result
       ##
-      # Creates a new Result instance.
-      def initialize #:nodoc:
+      # @private Creates a new Result instance.
+      def initialize
         @fields = Fields.new
         @raw = {}
       end
 
       ##
       # The unique identifier of the document referenced in the search result.
+      #
+      # @return [String]
       def doc_id
         @raw["docId"]
       end
 
       ##
       # The token for the next page of results.
+      #
+      # @return [String]
       def token
         @raw["nextPageToken"]
       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 [FieldValue]
       #
-      # === Returns
-      #
-      # FieldValue
-      #
-      # === Example
-      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   search = gcloud.search
       #   index = search.index "products"
@@ -72,30 +70,25 @@
       #
       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 search result. Each field has a name (String) and a
-      # list of values (FieldValues). (See Fields)
+      # list of values ({FieldValues}). (See {Fields})
       def fields
         @fields
       end
 
-      # rubocop:enable Style/TrivialAccessors
-
       ##
       # 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"
@@ -114,12 +107,15 @@
         @fields.each(&block)
       end
 
       ##
       # Returns a new array populated with all the field names.
-      # (See Fields#names)
+      # (See {Fields#names})
       #
+      # @return [Array<String>]
+      #
+      # @example
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
       #   search = gcloud.search
       #   index = search.index "products"
@@ -134,12 +130,12 @@
       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_token = ""
         if token
           trunc_token = "#{token[0, 8]}...#{token[-5..-1]}"
           trunc_token = token if token.length < 20
           insp_token = ", token: #{trunc_token.inspect}"
@@ -147,20 +143,20 @@
         insp_fields = ", fields: (#{fields.names.map(&:inspect).join ', '})"
         "#{self.class}(doc_id: #{doc_id.inspect}#{insp_token}#{insp_fields})"
       end
 
       ##
-      # New Result from a raw data object.
-      def self.from_hash hash #:nodoc:
+      # @private New Result from a raw data object.
+      def self.from_hash hash
         result = new
         result.instance_variable_set "@raw", hash
         result.instance_variable_set "@fields", Fields.from_raw(hash["fields"])
         result
       end
 
       ##
-      # Returns the Result data as a hash
-      def to_hash #:nodoc:
+      # @private Returns the Result data as a hash
+      def to_hash
         hash = @raw.dup
         hash["fields"] = @fields.to_raw
         hash
       end
     end