finished documentation of modules for now.

marl_factory_grid/modules/batteries/actions.py

@@ -12,7 +12,7 @@ class Charge(Action):
 
     def __init__(self):
         """
-        Checks if a charge pod is present at the entity's position.
+        Checks if a charge pod is present at the agent's position.
         If found, it attempts to charge the battery using the charge pod.
         """
         super().__init__(b.ACTION_CHARGE, b.REWARD_CHARGE_VALID, b.Reward_CHARGE_FAIL)

marl_factory_grid/modules/batteries/entitites.py

@@ -31,7 +31,7 @@ class Battery(Object):
 
     def __init__(self, initial_charge_level, owner, *args, **kwargs):
         """
-        Represents a battery entity in the environment that can be bound to an agent and charged at chargepods.
+        Represents a battery entity in the environment that can be bound to an agent and charged at charge pods.
 
         :param initial_charge_level: The current charge level of the battery, ranging from 0 to 1.
         :type initial_charge_level: float
@@ -45,7 +45,7 @@ class Battery(Object):
 
     def do_charge_action(self, amount) -> bool:
         """
-        Updates the Battery's charge level accordingly.
+        Updates the Battery's charge level according to the passed value.
 
         :param amount: Amount added to the Battery's charge level.
         :returns: whether the battery could be charged. if not, it was already fully charged.
@@ -59,7 +59,7 @@ class Battery(Object):
 
     def decharge(self, amount) -> bool:
         """
-        Decreases the charge value of a battery. Currently only riggered by the battery-decharge rule.
+        Decreases the charge value of a battery. Currently only triggered by the battery-decharge rule.
         """
         if self.charge_level != 0:
             # noinspection PyTypeChecker
@@ -84,11 +84,11 @@ class ChargePod(Entity):
         """
         Represents a charging pod for batteries in the environment.
 
-        :param charge_rate: The rate at which the charging pod charges batteries. Default is 0.4.
+        :param charge_rate: The rate at which the charging pod charges batteries. Defaults to 0.4.
         :type charge_rate: float
 
         :param multi_charge: Indicates whether the charging pod supports charging multiple batteries simultaneously.
-                        Default is False.
+                        Defaults to False.
         :type multi_charge: bool
         """
         super(ChargePod, self).__init__(*args, **kwargs)
@@ -97,7 +97,8 @@ class ChargePod(Entity):
 
     def charge_battery(self, entity, state) -> bool:
         """
-        Checks whether the battery can be charged. If so, triggers the charge action.
+        Triggers the battery charge action if possible. Impossible if battery at full charge level or more than one
+        agent at charge pods' position.
 
         :returns: whether the action was successful (valid) or not.
         """

marl_factory_grid/modules/batteries/groups.py

@@ -19,7 +19,7 @@ class Batteries(Collection):
 
     def __init__(self, size, initial_charge_level=1.0, *args, **kwargs):
         """
-        A collection of batteries that can spawn batteries.
+        A collection of batteries that is in charge of spawning batteries. (spawned batteries are bound to agents)
 
         :param size: The maximum allowed size of the collection. Ensures that the collection does not exceed this size.
         :type size: int

marl_factory_grid/modules/clean_up/actions.py

@@ -12,7 +12,7 @@ class Clean(Action):
 
     def __init__(self):
         """
-        Attempts to reduce dirt amount on entity's position.
+        Attempts to reduce dirt amount on entity's position. Fails if no dirt is found at the at agents' position.
         """
         super().__init__(d.CLEAN_UP, d.REWARD_CLEAN_UP_VALID, d.REWARD_CLEAN_UP_FAIL)
 

marl_factory_grid/modules/clean_up/entitites.py

@@ -18,7 +18,8 @@ class DirtPile(Entity):
 
     def __init__(self, *args, amount=2, max_local_amount=5, **kwargs):
         """
-        Represents a pile of dirt at a specific position in the environment.
+        Represents a pile of dirt at a specific position in the environment that agents can interact with. Agents can
+        clean the dirt pile or, depending on activated rules, interact with it in different ways.
 
         :param amount: The amount of dirt in the pile.
         :type amount: float

marl_factory_grid/modules/destinations/actions.py

@@ -10,7 +10,7 @@ class DestAction(Action):
 
     def __init__(self):
         """
-        Attempts to wait at destination.
+        The agent performing this action attempts to wait at the destination in order to receive a reward.
         """
         super().__init__(d.DESTINATION, d.REWARD_WAIT_VALID, d.REWARD_WAIT_FAIL)
 

marl_factory_grid/modules/destinations/entitites.py

@@ -38,7 +38,11 @@ class Destination(Entity):
 
     def has_just_been_reached(self, state):
         """
-        Checks if the destination has just been reached based on the current state.
+        Checks if the destination has been reached in the last environment step.
+
+        :return: the agent that has just reached the destination or whether any agent in the environment has
+                performed actions equal to or exceeding the specified limit
+        :rtype: Union[Agent, bool]
         """
         if self.was_reached():
             return False

marl_factory_grid/modules/doors/actions.py

@@ -10,7 +10,8 @@ class DoorUse(Action):
 
     def __init__(self, **kwargs):
         """
-        Attempts to interact with door (open/close it) and returns an action result if successful.
+        The agent performing this action attempts to interact with door (open/close it), returning an action result if
+        successful.
         """
         super().__init__(d.ACTION_DOOR_USE, d.REWARD_USE_DOOR_VALID, d.REWARD_USE_DOOR_FAIL, **kwargs)
 

marl_factory_grid/modules/doors/entitites.py

@@ -19,7 +19,7 @@ class DoorIndicator(Entity):
 
     def __init__(self, *args, **kwargs):
         """
-        Is added around a door for agents to see.
+        Is added as a padding around doors so agents can see doors earlier.
         """
         super().__init__(*args, **kwargs)
         self.__delattr__('move')

marl_factory_grid/modules/doors/rules.py

@@ -9,7 +9,7 @@ class DoorAutoClose(Rule):
 
     def __init__(self, close_frequency: int = 10):
         """
-        This rule closes doors, that have been opened automatically, when no entity is blocking the position.
+        This rule closes doors that have been opened automatically when no entity is blocking the position.
 
         :type close_frequency: int
         :param close_frequency: How many ticks after opening, should the door close?

marl_factory_grid/modules/items/groups.py

@@ -62,7 +62,7 @@ class Inventory(IsBoundMixin, Collection):
 
     def __init__(self, agent, *args, **kwargs):
         """
-        An inventory that can hold items picked up by the agent this is bound to.
+        An inventory that can hold items picked up by the agent it is bound to.
 
         :param agent: The agent this inventory is bound to and belongs to.
         :type agent: Agent
@@ -96,7 +96,7 @@ class Inventory(IsBoundMixin, Collection):
 
     def clear_temp_state(self):
         """
-        Entites need this, but inventories have no state.
+        Entities need this, but inventories have no state.
         """
         pass
 
@@ -123,7 +123,7 @@ class Inventories(Objects):
 
     def __init__(self, size: int, *args, **kwargs):
         """
-        TODO
+        A collection of all inventories used to spawn an inventory per agent.
         """
         super(Inventories, self).__init__(*args, **kwargs)
         self.size = size

marl_factory_grid/modules/machines/actions.py

@@ -11,7 +11,8 @@ class MachineAction(Action):
 
     def __init__(self):
         """
-        Attempts to maintain the machine and returns an action result if successful.
+        When performing this action, the maintainer attempts to maintain the machine at his current position, returning
+        an action result if successful.
         """
         super().__init__(m.MACHINE_ACTION, m.MAINTAIN_VALID, m.MAINTAIN_FAIL)
 

marl_factory_grid/modules/machines/entitites.py

@@ -14,7 +14,8 @@ class Machine(Entity):
 
     def __init__(self, *args, work_interval: int = 10, pause_interval: int = 15, **kwargs):
         """
-        Represents a machine entity that the maintainer will try to maintain.
+        Represents a machine entity that the maintainer will try to maintain by performing the maintenance action.
+        Machines' health depletes over time.
 
         :param work_interval: How long should the machine work before pausing.
         :type work_interval: int
@@ -31,7 +32,8 @@ class Machine(Entity):
 
     def maintain(self) -> bool:
         """
-        Attempts to maintain the machine by increasing its health.
+        Attempts to maintain the machine by increasing its health, which is only possible if the machine is at a maximum
+        of 98/100 HP.
         """
         if self.status == m.STATE_WORK:
             return c.NOT_VALID

marl_factory_grid/modules/maintenance/entities.py

@@ -16,8 +16,9 @@ from ..doors import DoorUse
 class Maintainer(Entity):
 
     def __init__(self, objective, action, *args, **kwargs):
-        """
+        self.action_ = """
-        Represents the maintainer entity that aims to maintain machines.
+        Represents the maintainer entity that aims to maintain machines. The maintainer calculates its route using nx 
+        shortest path and restores the health of machines it visits to 100.
         
         :param objective: The maintainer's objective, e.g., "Machines".
         :type objective: str

marl_factory_grid/modules/maintenance/groups.py

@@ -27,7 +27,7 @@ class Maintainers(Collection):
 
     def __init__(self, *args, **kwargs):
         """
-        A collection of maintainers
+        A collection of maintainers that is used to spawn them.
         """
         super().__init__(*args, **kwargs)