lib/ldclient-rb/evaluation.rb in ldclient-rb-5.4.3 vs lib/ldclient-rb/evaluation.rb in ldclient-rb-5.5.0

@@ -1,39 +1,87 @@
 require "date"
 require "semantic"
 
 module LaunchDarkly
-  # An object returned by `LDClient.variation_detail`, combining the result of a flag evaluation with
+  # An object returned by {LDClient#variation_detail}, combining the result of a flag evaluation with
   # an explanation of how it was calculated.
   class EvaluationDetail
     def initialize(value, variation_index, reason)
       @value = value
       @variation_index = variation_index
       @reason = reason
     end
 
-    # @return [Object] The result of the flag evaluation. This will be either one of the flag's
-    #   variations or the default value that was passed to the `variation` method.
+    #
+    # The result of the flag evaluation. This will be either one of the flag's variations, or the
+    # default value that was passed to {LDClient#variation_detail}. It is the same as the return
+    # value of {LDClient#variation}.
+    #
+    # @return [Object]
+    #
     attr_reader :value
 
-    # @return [int|nil] The index of the returned value within the flag's list of variations, e.g.
-    #   0 for the first variation - or `nil` if the default value was returned.
+    #
+    # The index of the returned value within the flag's list of variations. The first variation is
+    # 0, the second is 1, etc. This is `nil` if the default value was returned.
+    #
+    # @return [int|nil]
+    #
     attr_reader :variation_index
 
-    # @return [Hash] An object describing the main factor that influenced the flag evaluation value.
+    #
+    # An object describing the main factor that influenced the flag evaluation value.
+    #
+    # This object is currently represented as a Hash, which may have the following keys:
+    #
+    # `:kind`: The general category of reason. Possible values:
+    #
+    # * `'OFF'`: the flag was off and therefore returned its configured off value
+    # * `'FALLTHROUGH'`: the flag was on but the user did not match any targets or rules
+    # * `'TARGET_MATCH'`: the user key was specifically targeted for this flag
+    # * `'RULE_MATCH'`: the user matched one of the flag's rules
+    # * `'PREREQUISITE_FAILED`': the flag was considered off because it had at least one
+    # prerequisite flag that either was off or did not return the desired variation
+    # * `'ERROR'`: the flag could not be evaluated, so the default value was returned
+    #
+    # `:ruleIndex`: If the kind was `RULE_MATCH`, this is the positional index of the
+    # matched rule (0 for the first rule).
+    #
+    # `:ruleId`: If the kind was `RULE_MATCH`, this is the rule's unique identifier.
+    #
+    # `:prerequisiteKey`: If the kind was `PREREQUISITE_FAILED`, this is the flag key of
+    # the prerequisite flag that failed.
+    #
+    # `:errorKind`: If the kind was `ERROR`, this indicates the type of error:
+    #
+    # * `'CLIENT_NOT_READY'`: the caller tried to evaluate a flag before the client had
+    # successfully initialized
+    # * `'FLAG_NOT_FOUND'`: the caller provided a flag key that did not match any known flag
+    # * `'MALFORMED_FLAG'`: there was an internal inconsistency in the flag data, e.g. a
+    # rule specified a nonexistent variation
+    # * `'USER_NOT_SPECIFIED'`: the user object or user key was not provied
+    # * `'EXCEPTION'`: an unexpected exception stopped flag evaluation
+    #
+    # @return [Hash]
+    #
     attr_reader :reason
 
-    # @return [boolean] True if the flag evaluated to the default value rather than to one of its
-    #   variations.
+    #
+    # Tests whether the flag evaluation returned a default value. This is the same as checking
+    # whether {#variation_index} is nil.
+    #
+    # @return [Boolean]
+    #
     def default_value?
       variation_index.nil?
     end
 
     def ==(other)
       @value == other.value && @variation_index == other.variation_index && @reason == other.reason
     end
   end
 
+  # @private
   module Evaluation
     BUILTINS = [:key, :ip, :country, :email, :firstName, :lastName, :avatar, :name, :anonymous]
 
     NUMERIC_VERSION_COMPONENTS_REGEX = Regexp.new("^[0-9.]*")