added documentation for environment entity and factory

marl_factory_grid/environment/entity/util.py

@@ -4,7 +4,7 @@ from marl_factory_grid.environment.entity.object import Object
 
 
 ##########################################################################
-# ####################### Objects and Entitys ########################## #
+# ####################### Objects and Entities ########################## #
 ##########################################################################
 
 
@@ -12,10 +12,11 @@ class PlaceHolder(Object):
 
     def __init__(self, *args, fill_value=0, **kwargs):
         """
-        TODO
+        A placeholder object that can be used as an observation during training. It is designed to be later replaced
+        with a meaningful observation that wasn't initially present in the training run.
 
-
-        :return:
+        :param fill_value: The default value to fill the placeholder observation (Default: 0)
+        :type fill_value: Any
         """
         super().__init__(*args, **kwargs)
         self._fill_value = fill_value
@@ -23,20 +24,20 @@ class PlaceHolder(Object):
     @property
     def var_can_collide(self):
         """
-        TODO
+        Indicates whether this placeholder object can collide with other entities. Always returns False.
 
-
-        :return:
+        :return: False
+        :rtype: bool
         """
         return False
 
     @property
     def encoding(self):
         """
-        TODO
+        Get the fill value representing the placeholder observation.
 
-
-        :return:
+        :return: The fill value
+        :rtype: Any
         """
         return self._fill_value
 
@@ -54,10 +55,10 @@ class GlobalPosition(Object):
     @property
     def encoding(self):
         """
-        TODO
+        Get the encoded representation of the global position based on whether normalization is enabled.
 
-
-        :return:
+        :return: The encoded representation of the global position
+        :rtype: tuple[float, float] or tuple[int, int]
         """
         if self._normalized:
             return tuple(np.divide(self._bound_entity.pos, self._shape))
@@ -66,10 +67,14 @@ class GlobalPosition(Object):
 
     def __init__(self, agent, level_shape, *args, normalized: bool = True, **kwargs):
         """
-        TODO
+        A utility class representing the global position of an entity in the environment.
 
-
-        :return:
+        :param agent: The agent entity to which the global position is bound.
+        :type agent: marl_factory_grid.environment.entity.agent.Agent
+        :param level_shape: The shape of the environment level.
+        :type level_shape: tuple[int, int]
+        :param normalized: Indicates whether the global position should be normalized (Default: True)
+        :type normalized: bool
         """
         super(GlobalPosition, self).__init__(*args, **kwargs)
         self.bind_to(agent)