Added documentation on a lot of classes and functions (and removed some files I commited by mistake)

dungeonbattle/interfaces.py

@@ -10,7 +10,7 @@ from dungeonbattle.display.texturepack import TexturePack
 class Map:
     """
     Object that represents a Map with its width, height
-    and the whole tiles, with their custom properties.
+    and tiles, that have their custom properties.
     """
     width: int
     height: int
@@ -120,6 +120,9 @@ class Map:
             entity.act(self)
 
     def save_state(self) -> dict:
+        """
+        Saves the map's attributes to a dictionnary
+        """
         d = dict()
         d["width"] = self.width
         d["height"] = self.height
@@ -133,6 +136,9 @@ class Map:
         return d
 
     def load_state(self, d: dict) -> None:
+        """
+        Loads the map's attributes from a dictionnary
+        """
         self.width = d["width"]
         self.height = d["height"]
         self.start_y = d["start_y"] 
@@ -143,6 +149,9 @@ class Map:
         #add entities
 
 class Tile(Enum):
+    """
+    The internal representation of the tiles of the map
+    """
     EMPTY = auto()
     WALL = auto()
     FLOOR = auto()
@@ -158,9 +167,15 @@ class Tile(Enum):
         raise ValueError(ch)
 
     def char(self, pack: TexturePack) -> str:
+        """
+        Translates a Tile to the corresponding character according to the texture pack
+        """
         return getattr(pack, self.name)
 
     def is_wall(self) -> bool:
+        """
+        Is this Tile a wall?
+        """
         return self == Tile.WALL
 
     def can_walk(self) -> bool:
@@ -171,10 +186,13 @@ class Tile(Enum):
 
 
 class Entity:
+    """
+    An Entity object represents any entity present on the map
+    """
     y: int
     x: int
     name: str
-    map: Map
+    map: Map 
 
     def __init__(self):
         self.y = 0
@@ -182,29 +200,47 @@ class Entity:
 
     def check_move(self, y: int, x: int, move_if_possible: bool = False)\
             -> bool:
+        """
+        Checks if moving to (y,x) is authorized
+        """
         free = self.map.is_free(y, x)
         if free and move_if_possible:
             self.move(y, x)
         return free
 
     def move(self, y: int, x: int) -> bool:
+        """
+        Moves an entity to (y,x) coordinates
+        """
         self.y = y
         self.x = x
         return True
 
     def move_up(self, force: bool = False) -> bool:
+        """
+        Moves the entity up one tile, if possible
+        """
         return self.move(self.y - 1, self.x) if force else \
             self.check_move(self.y - 1, self.x, True)
 
     def move_down(self, force: bool = False) -> bool:
+        """
+        Moves the entity down one tile, if possible
+        """
         return self.move(self.y + 1, self.x) if force else \
             self.check_move(self.y + 1, self.x, True)
 
     def move_left(self, force: bool = False) -> bool:
+        """
+        Moves the entity left one tile, if possible
+        """
         return self.move(self.y, self.x - 1) if force else \
             self.check_move(self.y, self.x - 1, True)
 
     def move_right(self, force: bool = False) -> bool:
+        """
+        Moves the entity right one tile, if possible
+        """
         return self.move(self.y, self.x + 1) if force else \
             self.check_move(self.y, self.x + 1, True)
 
@@ -229,14 +265,23 @@ class Entity:
         return sqrt(self.distance_squared(other))
 
     def is_fighting_entity(self) -> bool:
+        """
+        Is this entity a fighting entity?
+        """
         return isinstance(self, FightingEntity)
 
     def is_item(self) -> bool:
+        """
+        Is this entity an item?
+        """
         from dungeonbattle.entities.items import Item
         return isinstance(self, Item)
 
     @staticmethod
     def get_all_entity_classes():
+        """
+        Returns all entities subclasses
+        """
         from dungeonbattle.entities.items import Heart, Bomb
         from dungeonbattle.entities.monsters import Beaver, Hedgehog, \
             Rabbit, TeddyBear
@@ -260,6 +305,10 @@ class Entity:
 
 
 class FightingEntity(Entity):
+    """
+    A FightingEntity is an entity that can fight, and thus has a health,
+    level and stats
+    """
     maxhealth: int
     health: int
     strength: int
@@ -285,27 +334,45 @@ class FightingEntity(Entity):
         
 
     def hit(self, opponent: "FightingEntity") -> None:
+        """
+        Deals damage to the opponent, based on the stats
+        """
         opponent.take_damage(self, self.strength)
 
     def take_damage(self, attacker: "Entity", amount: int) -> None:
+        """
+        Take damage from the attacker, based on the stats
+        """
         self.health -= amount
         if self.health <= 0:
             self.die()
 
     def die(self) -> None:
+        """
+        If a fighting entity has no more health, it dies and is removed
+        """
         self.dead = True
         self.map.remove_entity(self)
 
     def keys(self) -> list:
+        """
+        Returns a fighting entities specific attributes
+        """
         return ["maxhealth", "health", "level", "dead", "strength", "intelligence", "charisma", "dexterity", "constitution"]
 
     def save_state(self) -> dict:
+        """
+        Saves the state of the entity into a dictionnary
+        """
         d = super().save_state()
         for name in self.keys():
             d[name] = self.__getattribute__(name)
         return d
 
     def recover_state(self, d : dict) -> None:
+        """
+        Loads the state of an entity from a dictionnary
+        """
         super().recover_state(d)
         for name in d.keys():
             self.__setattribute__(name, d[name])