Docs: add docstrings to the World class

worlds/AutoWorld.py

@@ -131,54 +131,69 @@ class World(metaclass=AutoWorldRegister):
     """A World object encompasses a game's Items, Locations, Rules and additional data or functionality required.
     A Game should have its own subclass of World in which it defines the required data structures."""
 
-    option_definitions: ClassVar[Dict[str, AssembleOptions]] = {}  # link your Options mapping
+    option_definitions: ClassVar[Dict[str, AssembleOptions]] = {}
-    game: ClassVar[str]  # name the game
+    """link your Options mapping"""
-    topology_present: ClassVar[bool] = False  # indicate if world type has any meaningful layout/pathing
+    game: ClassVar[str]
+    """name the game"""
+    topology_present: ClassVar[bool] = False
+    """indicate if world type has any meaningful layout/pathing"""
 
-    # gets automatically populated with all item and item group names
     all_item_and_group_names: ClassVar[FrozenSet[str]] = frozenset()
+    """gets automatically populated with all item and item group names"""
 
-    # map names to their IDs
     item_name_to_id: ClassVar[Dict[str, int]] = {}
+    """map item names to their IDs"""
     location_name_to_id: ClassVar[Dict[str, int]] = {}
+    """map location names to their IDs"""
 
-    # maps item group names to sets of items. Example: "Weapons" -> {"Sword", "Bow"}
     item_name_groups: ClassVar[Dict[str, Set[str]]] = {}
+    """maps item group names to sets of items. Example: {"Weapons": {"Sword", "Bow"}}"""
 
-    # increment this every time something in your world's names/id mappings changes.
-    # While this is set to 0 in *any* AutoWorld, the entire DataPackage is considered in testing mode and will be
-    # retrieved by clients on every connection.
     data_version: ClassVar[int] = 1
+    """
+    increment this every time something in your world's names/id mappings changes.
+    While this is set to 0, this world's DataPackage is considered in testing mode and will be inserted to the multidata
+    and retrieved by clients on every connection.
+    """
 
-    # override this if changes to a world break forward-compatibility of the client
-    # The base version of (0, 1, 6) is provided for backwards compatibility and does *not* need to be updated in the
-    # future. Protocol level compatibility check moved to MultiServer.min_client_version.
     required_client_version: Tuple[int, int, int] = (0, 1, 6)
+    """
+    override this if changes to a world break forward-compatibility of the client
+    The base version of (0, 1, 6) is provided for backwards compatibility and does *not* need to be updated in the
+    future. Protocol level compatibility check moved to MultiServer.min_client_version.
+    """
 
-    # update this if the resulting multidata breaks forward-compatibility of the server
     required_server_version: Tuple[int, int, int] = (0, 2, 4)
+    """update this if the resulting multidata breaks forward-compatibility of the server"""
 
-    hint_blacklist: ClassVar[FrozenSet[str]] = frozenset()  # any names that should not be hintable
+    hint_blacklist: ClassVar[FrozenSet[str]] = frozenset()
+    """any names that should not be hintable"""
 
-    # Hide World Type from various views. Does not remove functionality.
     hidden: ClassVar[bool] = False
+    """Hide World Type from various views. Does not remove functionality."""
 
-    # see WebWorld for options
     web: ClassVar[WebWorld] = WebWorld()
+    """see WebWorld for options"""
 
-    # autoset on creation:
     multiworld: "MultiWorld"
+    """autoset on creation. The MultiWorld object for the currently generating multiworld."""
     player: int
+    """autoset on creation. The player number for this World"""
 
-    # automatically generated
     item_id_to_name: ClassVar[Dict[int, str]]
+    """automatically generated reverse lookup of item id to name"""
     location_id_to_name: ClassVar[Dict[int, str]]
+    """automatically generated reverse lookup of location id to name"""
 
-    item_names: ClassVar[Set[str]]  # set of all potential item names
+    item_names: ClassVar[Set[str]]
-    location_names: ClassVar[Set[str]]  # set of all potential location names
+    """set of all potential item names"""
+    location_names: ClassVar[Set[str]]
+    """set of all potential location names"""
 
-    zip_path: ClassVar[Optional[pathlib.Path]] = None  # If loaded from a .apworld, this is the Path to it.
+    zip_path: ClassVar[Optional[pathlib.Path]] = None
-    __file__: ClassVar[str]  # path it was loaded from
+    """If loaded from a .apworld, this is the Path to it."""
+    __file__: ClassVar[str]
+    """path it was loaded from"""
 
     def __init__(self, multiworld: "MultiWorld", player: int):
         self.multiworld = multiworld
@@ -196,18 +211,32 @@ class World(metaclass=AutoWorldRegister):
         pass
 
     def generate_early(self) -> None:
+        """
+        Run before any general steps of the MultiWorld other than options. Useful for getting and adjusting option
+        results and determining layouts for entrance rando etc. start inventory gets pushed after this step.
+        """
         pass
 
     def create_regions(self) -> None:
+        """Method for creating and connecting regions for the World."""
         pass
 
     def create_items(self) -> None:
+        """
+        Method for creating and submitting items to the itempool. Items and Regions should *not* be created and submitted
+        to the MultiWorld after this step. If items need to be placed during pre_fill use `get_prefill_items`.
+        """
         pass
 
     def set_rules(self) -> None:
+        """Method for setting the rules on the World's regions and locations."""
         pass
 
     def generate_basic(self) -> None:
+        """
+        Useful for randomizing things that don't affect logic but are better to be determined before the output stage.
+        i.e. checking what the player has marked as priority or randomizing enemies
+        """
         pass
 
     def pre_fill(self) -> None: