Documentation

marl_factory_grid/modules/machines/actions.py

@@ -1,17 +1,18 @@
 from typing import Union
 
-import marl_factory_grid.modules.machines.constants
-from marl_factory_grid.environment.actions import Action
-from marl_factory_grid.utils.results import ActionResult
-
-from marl_factory_grid.modules.machines import constants as m
 from marl_factory_grid.environment import constants as c
+from marl_factory_grid.environment.actions import Action
+from marl_factory_grid.modules.machines import constants as m
 from marl_factory_grid.utils import helpers as h
+from marl_factory_grid.utils.results import ActionResult
 
 
 class MachineAction(Action):
 
     def __init__(self):
+        """
+        Attempts to maintain the machine and returns an action result if successful.
+        """
         super().__init__(m.MACHINE_ACTION, m.MAINTAIN_VALID, m.MAINTAIN_FAIL)
 
     def do(self, entity, state) -> Union[None, ActionResult]:

marl_factory_grid/modules/machines/entitites.py

@@ -13,6 +13,14 @@ class Machine(Entity):
         return self._encodings[self.status]
 
     def __init__(self, *args, work_interval: int = 10, pause_interval: int = 15, **kwargs):
+        """
+        Represents a machine entity that the maintainer will try to maintain.
+
+        :param work_interval: How long should the machine work before pausing.
+        :type work_interval: int
+        :param pause_interval: How long should the machine pause before continuing to work.
+        :type pause_interval: int
+        """
         super(Machine, self).__init__(*args, **kwargs)
         self._intervals = dict({m.STATE_IDLE: pause_interval, m.STATE_WORK: work_interval})
         self._encodings = dict({m.STATE_IDLE: pause_interval, m.STATE_WORK: work_interval})
@@ -21,7 +29,10 @@ class Machine(Entity):
         self.health = 100
         self._counter = 0
 
-    def maintain(self):
+    def maintain(self) -> bool:
+        """
+        Attempts to maintain the machine by increasing its health.
+        """
         if self.status == m.STATE_WORK:
             return c.NOT_VALID
         if self.health <= 98:
@@ -31,6 +42,15 @@ class Machine(Entity):
             return c.NOT_VALID
 
     def tick(self, state):
+        """
+        Updates the machine's mode (work, pause) depending on its current counter and whether an agent is currently on
+        its position. If no agent is standing on the machine's position, it decrements its own health.
+
+        :param state: The current game state.
+        :type state: GameState
+        :return: The result of the tick operation on the machine.
+        :rtype: TickResult | None
+        """
         others = state.entities.pos_dict[self.pos]
         if self.status == m.STATE_MAINTAIN and any([c.AGENT in x.name for x in others]):
             return TickResult(identifier=self.name, validity=c.VALID, entity=self)
@@ -48,6 +68,9 @@ class Machine(Entity):
             return None
 
     def reset_counter(self):
+        """
+        Internal Usage
+        """
         self._counter = self._intervals[self.status]
 
     def render(self):

marl_factory_grid/modules/machines/groups.py

@@ -20,5 +20,8 @@ class Machines(Collection):
         return True
 
     def __init__(self, *args, **kwargs):
+        """
+        A Collection of Machines.
+        """
         super(Machines, self).__init__(*args, **kwargs)