From 8d2e308f8ca5cf3848a06abc41a8b5360c3d5506 Mon Sep 17 00:00:00 2001
From: NewSoupVi <57900059+NewSoupVi@users.noreply.github.com>
Date: Wed, 3 Jul 2024 21:10:56 +0200
Subject: [PATCH] docstrings

---
 worlds/witness/rules.py | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/worlds/witness/rules.py b/worlds/witness/rules.py
index 455b572aa78e..0970410cc744 100644
--- a/worlds/witness/rules.py
+++ b/worlds/witness/rules.py
@@ -219,8 +219,13 @@ def _can_do_theater_to_tunnels(state: CollectionState, world: "WitnessWorld") ->
     )
 
 
-def _has_item(item: str, world: "WitnessWorld", player: int,
-              player_logic: WitnessPlayerLogic, player_locations: WitnessPlayerLocations) -> CollectionRule | SimpleItemRepresentation:
+def _has_item(item: str, world: "WitnessWorld", player: int, player_logic: WitnessPlayerLogic,
+              player_locations: WitnessPlayerLocations) -> CollectionRule | SimpleItemRepresentation:
+    """
+    Convert a single element of a WitnessRule into a CollectionRule, unless it is referring to an item,
+    in which case we return it as an item-count pair ("SimpleItemRepresentation"). This allows some optimisation later.
+    """
+
     if item in player_logic.REFERENCE_LOGIC.ALL_REGIONS_BY_NAME:
         region = world.get_region(item)
         return region.can_reach
@@ -250,8 +255,11 @@ def _has_item(item: str, world: "WitnessWorld", player: int,
     return simple_rule
 
 
-def optimize_requirement_option(requirement_option: List[CollectionRule | SimpleItemRepresentation]) -> List[CollectionRule | SimpleItemRepresentation]:
-    # Optimize out "Progressive Dots: 1, Progressive Dots: 2"
+def optimize_requirement_option(requirement_option: List[CollectionRule | SimpleItemRepresentation])\
+        -> List[CollectionRule | SimpleItemRepresentation]:
+    """
+    This optimises out a requirement like [("Progressive Dots": 1), ("Progressive Dots": 2)] to only the "2" version.
+    """
 
     direct_items = [rule for rule in requirement_option if isinstance(rule, tuple)]
     if not direct_items:
@@ -270,6 +278,10 @@ def optimize_requirement_option(requirement_option: List[CollectionRule | Simple
 
 def convert_requirement_option(requirement: List[CollectionRule | SimpleItemRepresentation],
                                player: int) -> List[CollectionRule]:
+    """
+    Converts a list of CollectionRules and SimpleItemRepresentations to just a list of CollectionRules.
+    If the list is ONLY SimpleItemRepresentations, we can just return a CollectionRule based on state.has_all_counts()
+    """
     if all(isinstance(rule, tuple) for rule in requirement):
         item_counts = dict(requirement)
         return [lambda state: state.has_all_counts(item_counts, player)]
@@ -287,8 +299,7 @@ def convert_requirement_option(requirement: List[CollectionRule | SimpleItemRepr
 
 def _meets_item_requirements(requirements: WitnessRule, world: "WitnessWorld") -> Optional[CollectionRule]:
     """
-    Checks whether item and panel requirements are met for
-    a panel
+    Converts a WitnessRule into a CollectionRule.
     """
     player = world.player