update string docs for_identifier*()

Author: mrlevitas

reddit_decider/__init__.py

@@ -452,6 +452,14 @@ def get_variant_for_identifier(
     ) -> Optional[str]:
         """Return a bucketing variant, if any, with auto-exposure for a given :code:`identifier`.
 
+        Note: If the experiment's :code:`bucket_val` (e.g. "user_id", "device_id", "canonical_url")
+            does not match the :code:`identifier_type` param,
+            the :code:`identifier` will be ignored and not used to bucket (:code:`{identifier_type: identifier}` is
+            added to internal :code:`DeciderContext` instance, but doesn't act like a bucketing override).
+
+            If the :code:`bucket_val` field exists on the :code:`DeciderContext` instance,
+            that field will be used to bucket, since it corresponds to the experiment's config.
+
         Since calling :code:`get_variant_for_identifier()` will fire an exposure event, it
         is best to call it when you are sure the user will be exposed to the experiment.
 
@@ -460,8 +468,11 @@ def get_variant_for_identifier(
         :param identifier: an arbitary string used to bucket the experiment by
             being set on :code:`DeciderContext`'s :code:`identifier_type` field.
 
-        :param identifier_type: Sets :code:`{identifier_type: identifier}` on DeciderContext and
-            should match an experiment's :code:`bucket_val` to get a variant.
+        :param identifier_type: Sets :code:`{identifier_type: identifier}` on :code:`DeciderContext`.
+            The experiment's :code:`bucket_val` will be looked up in :code:`DeciderContext` and be used to bucket.
+            If the experiment's :code:`bucket_val` field does not match :code:`identifier_type` param,
+            :code:`identifier` will be ignored, and the field corresponding :code:`bucket_val` will be looked up
+            from :code:`DeciderContext` for bucketing.
 
         :param exposure_kwargs: Additional arguments that will be passed
             to :code:`events_logger` (keys must be part of v2 event schema,
@@ -508,6 +519,14 @@ def get_variant_for_identifier_without_expose(
     ) -> Optional[str]:
         """Return a bucketing variant, if any, without emitting exposure event for a given :code:`identifier`.
 
+        Note: If the experiment's :code:`bucket_val` (e.g. "user_id", "device_id", "canonical_url")
+            does not match the :code:`identifier_type` param,
+            the :code:`identifier` will be ignored and not used to bucket (:code:`{identifier_type: identifier}` is
+            added to internal :code:`DeciderContext` instance, but doesn't act like a bucketing override).
+
+            If the :code:`bucket_val` field exists on the :code:`DeciderContext` instance,
+            that field will be used to bucket, since it corresponds to the experiment's config.
+
         The :code:`expose()` function is available to be manually called afterward to emit
         exposure event.
 
@@ -522,8 +541,11 @@ def get_variant_for_identifier_without_expose(
         :param identifier: an arbitary string used to bucket the experiment by
             being set on :code:`DeciderContext`'s :code:`identifier_type` field.
 
-        :param identifier_type: Sets :code:`{identifier_type: identifier}` on DeciderContext and
-            should match an experiment's :code:`bucket_val` to get a variant.
+        :param identifier_type: Sets :code:`{identifier_type: identifier}` on :code:`DeciderContext`.
+            The experiment's :code:`bucket_val` will be looked up in :code:`DeciderContext` and be used to bucket.
+            If the experiment's :code:`bucket_val` field does not match :code:`identifier_type` param,
+            :code:`identifier` will be ignored and the field corresponding :code:`bucket_val` will be looked up
+            from :code:`DeciderContext` for bucketing.
 
         :return: Variant name if a variant is assigned, None otherwise.
         """
@@ -631,7 +653,8 @@ def get_all_variants_without_expose(self) -> List[Dict[str, Union[str, int]]]:
     def get_all_variants_for_identifier_without_expose(
         self, identifier: str, identifier_type: Literal["user_id", "device_id", "canonical_url"]
     ) -> List[Dict[str, Union[str, int]]]:
-        """Return a list of experiment dicts for a given :code:`identifier` in this format:
+        """Return a list of experiment dicts for experiments having :code:`bucket_val` match
+        :code:`identifier_type`, for a given :code:`identifier`, in this format:
 
                 .. code-block:: json
 
@@ -658,7 +681,7 @@ def get_all_variants_for_identifier_without_expose(
             being set on :code:`DeciderContext`'s :code:`identifier_type` field.
 
         :param identifier_type: Sets :code:`{identifier_type: identifier}` on DeciderContext and
-            should match an experiment's :code:`bucket_val` to get a variant.
+            buckets all experiment with matching :code:`bucket_val`.
 
         :return: list of experiment dicts with non-:code:`None` variants.
         """