[FSSDK-12760] Tighten holdout scope docstrings/comments

Condense the spec §5 cleanup comments to one-line/short-docstring form
per updated spec guidance. Same content, more compact.

Author: jaeopt

optimizely/entities.py

@@ -233,11 +233,8 @@ def __init__(
         self.trafficAllocation = trafficAllocation
         self.audienceIds = audienceIds
         self.audienceConditions = audienceConditions
-        # Per-rule targeting list for local holdouts. Scope is NOT determined by this
-        # field — it is determined by which datafile section the entity was parsed
-        # from ('holdouts' = global, 'localHoldouts' = local). ProjectConfig strips
-        # this field on entries parsed from the 'holdouts' section so that entities
-        # built from that section always satisfy is_global. See FSSDK-12760.
+        # Per-rule targeting for local holdouts. Scope comes from the datafile
+        # section, not this field; ProjectConfig strips it on 'holdouts' entries.
         self.included_rules: Optional[list[str]] = includedRules
 
     def get_audience_conditions_or_ids(self) -> Sequence[str | list[str]]:
@@ -250,22 +247,11 @@ def get_audience_conditions_or_ids(self) -> Sequence[str | list[str]]:
 
     @property
     def is_global(self) -> bool:
-        """Check if this is a global holdout (applies to all rules across all flags).
+        """True if this is a global holdout.
 
-        Authoritative scope is the datafile section the entity came from:
-        the top-level 'holdouts' section is global, 'localHoldouts' is local.
-        ProjectConfig enforces this by stripping 'includedRules' from entries
-        parsed out of the 'holdouts' section before constructing the entity,
-        so for entities built via ProjectConfig this property is consistent
-        with section membership.
-
-        At the entity level the property is still computed from
-        ``included_rules`` for code holding entity references directly:
-        None → global, [] or non-empty list → local. An empty list is a
-        local holdout that targets no rules (distinct from None/global).
-
-        Returns:
-            True if included_rules is None (global), False otherwise (local).
+        Scope is set by the datafile section ('holdouts' vs 'localHoldouts').
+        ProjectConfig strips 'includedRules' on 'holdouts' entries, so this
+        property stays consistent with section membership.
         """
         return self.included_rules is None
 

optimizely/helpers/types.py

@@ -130,9 +130,6 @@ class HoldoutDict(ExperimentDict):
     Extends ExperimentDict with holdout-specific properties.
     """
     holdoutStatus: HoldoutStatus
-    # Per-rule targeting list for local holdouts. Holdout scope is determined by which
-    # top-level datafile section the entry appears in ('holdouts' vs 'localHoldouts'),
-    # NOT by this field. On 'holdouts'-section entries this field is ignored and
-    # stripped at parse time (see ProjectConfig). On 'localHoldouts'-section entries
-    # the field is required; missing or None is an error and the entry is excluded.
+    # Per-rule targeting for local holdouts. Scope comes from the datafile section,
+    # not this field; required on 'localHoldouts' entries, stripped on 'holdouts'.
     includedRules: Optional[list[str]]