Updated Entity docs

Author: Ayuto

addons/source-python/packages/source-python/entities/entity.py

@@ -89,7 +89,18 @@
 # >> CLASSES
 # =============================================================================
 class Entity(BaseEntity):
-    """Class used to interact directly with entities."""
+    """Class used to interact directly with entities.
+
+    Beside the standard way of doing stuff via methods and properties this
+    class also provides dynamic attributes that depend on the entity that is
+    being accessed with this class. You can print all dynamic properties by
+    iterating over the following generators:
+
+    1. :attr:`properties`
+    2. :attr:`inputs`
+    3. :attr:`outputs`
+    4. :attr:`keyvalues`
+    """
 
     def __init__(self, index):
         """Initialize the Entity object."""
@@ -165,7 +176,13 @@ def __dir__(self):
 
     @classmethod
     def create(cls, classname):
-        """Create a new networked entity with the given classname."""
+        """Create a new networked entity with the given classname.
+
+        :param str classname:
+            Classname of the entity to create.
+        :raise ValueError:
+            Raised if the given classname is not a networked entity.
+        """
         entity = BaseEntity.create(classname)
         if entity.is_networked():
             return cls(entity.index)
@@ -212,13 +229,16 @@ def _obj(cls, ptr):
 
     @property
     def index(self):
-        """Return the entity's index."""
+        """Return the entity's index.
+
+        :rtype: int
+        """
         return self._index
-        
+
     @property
     def owner(self):
         """Return the entity's owner.
-        
+
         :return: None if the entity has no owner.
         :rtype: Entity
         """
@@ -263,11 +283,18 @@ def keyvalues(self):
             yield from server_class.keyvalues
 
     def get_color(self):
-        """Return the entity's color as a Color instance."""
+        """Return the entity's color.
+
+        :rtype: Color
+        """
         return self.render_color
 
     def set_color(self, color):
-        """Set the entity's color."""
+        """Set the entity's color.
+
+        :param Color color:
+            Color to set.
+        """
         # Set the entity's render mode
         self.render_mode = RenderMode.TRANS_COLOR
 
@@ -283,11 +310,18 @@ def set_color(self, color):
         doc="""Property to get/set the entity's color values.""")
 
     def get_model(self):
-        """Return the entity's model."""
+        """Return the entity's model.
+
+        :rtype: Model
+        """
         return Model(self.model_name)
 
     def set_model(self, model):
-        """Set the entity's model to the given model."""
+        """Set the entity's model to the given model.
+
+        :param Model model:
+            The model to set.
+        """
         self.model_index = model.index
         self.model_name = model.path
 
@@ -523,7 +557,14 @@ def _callback(*args, **kwargs):
         return delay
 
     def get_input(self, name):
-        """Return the InputFunction instance for the given name."""
+        """Return the input function matching the given name.
+
+        :parma str name:
+            Name of the input function.
+        :rtype: InputFunction
+        :raise ValueError:
+            Raised if the input function wasn't found.
+        """
         # Loop through each server class for the entity
         for server_class in self.server_classes:
 
@@ -540,11 +581,27 @@ def get_input(self, name):
                 name, self.classname))
 
     def call_input(self, name, *args, **kwargs):
-        """Call the InputFunction instance for the given name."""
+        """Call the input function matching the given name.
+
+        :param str name:
+            Name of the input function.
+        :param args:
+            Optional arguments that should be passed to the input function.
+        :param kwargs:
+            Optional keyword arguments that should be passed to the input
+            function.
+        :raise ValueError:
+            Raised if the input function wasn't found.
+        """
         self.get_input(name)(*args, **kwargs)
 
     def lookup_attachment(self, name):
-        """Return the attachment index matching the given name."""
+        """Return the attachment index matching the given name.
+
+        :param str name:
+            The name of the attachment.
+        :rtype: int
+        """
         # Get the ModelHeader instance of the entity
         model_header = self.model_header
 
@@ -569,24 +626,38 @@ def emit_sound(
             download=False, stream=False):
         """Emit a sound from this entity.
 
-        :param str sample: Sound file relative to the "sounds" directory.
-        :param RecipientFilter recipients: Recipients to emit the sound to.
-        :param int index: Index of the entity to emit the sound from.
-        :param float volume: Volume of the sound.
-        :param Attenuation attenuation: How far the sound should reaches.
-        :param int channel: Channel to emit the sound with.
-        :param SoundFlags flags: Flags of the sound.
-        :param Pitch pitch: Pitch of the sound.
-        :param Vector origin: Origin of the sound.
-        :param Vector direction: Direction of the sound.
-        :param tuple origins: Origins of the sound.
-        :param bool update_positions: Whether or not the positions should be
-            updated.
-        :param float sound_time: Time to play the sound for.
-        :param int speaker_entity: Index of the speaker entity.
-        :param bool download: Whether or not the sample should be added to the
-            downloadables.
-        :param bool stream: Whether or not the sound should be streamed.
+        :param str sample:
+            Sound file relative to the ``sounds`` directory.
+        :param RecipientFilter recipients:
+            Recipients to emit the sound to.
+        :param int index:
+            Index of the entity to emit the sound from.
+        :param float volume:
+            Volume of the sound.
+        :param Attenuation attenuation:
+            How far the sound should reaches.
+        :param int channel:
+            Channel to emit the sound with.
+        :param SoundFlags flags:
+            Flags of the sound.
+        :param Pitch pitch:
+            Pitch of the sound.
+        :param Vector origin:
+            Origin of the sound.
+        :param Vector direction:
+            Direction of the sound.
+        :param tuple origins:
+            Origins of the sound.
+        :param bool update_positions:
+            Whether or not the positions should be updated.
+        :param float sound_time:
+            Time to play the sound for.
+        :param int speaker_entity:
+            Index of the speaker entity.
+        :param bool download:
+            Whether or not the sample should be added to the downloadables.
+        :param bool stream:
+            Whether or not the sound should be streamed.
         """
         # Get the correct Sound class...
         if not stream:
@@ -609,14 +680,24 @@ def emit_sound(
     def stop_sound(self, sample, channel=Channel.AUTO):
         """Stop the given sound from being emitted by this entity.
 
-        :param str sample: Sound file relative to the "sounds" directory.
-        :param Channel channel: The channel of the sound.
+        :param str sample:
+            Sound file relative to the ``sounds`` directory.
+        :param Channel channel:
+            The channel of the sound.
         """
         engine_sound.stop_sound(self.index, channel, sample)
 
     def is_in_solid(
             self, mask=ContentMasks.ALL, generator=BaseEntityGenerator):
-        """Return whether or not the entity is in solid."""
+        """Return whether or not the entity is in solid.
+
+        :param ContentMasks mask:
+            Contents the ray can possibly collide with.
+        :param generator:
+            A callable that returns an iterable which contains
+            :class:`BaseEntity` instances that are ignored by the ray.
+        :rtype: bool
+        """
         # Get a Ray object of the entity physic box
         ray = Ray(self.origin, self.origin, self.mins, self.maxs)
 
@@ -634,7 +715,24 @@ def take_damage(
             self, damage, damage_type=DamageTypes.GENERIC, attacker_index=None,
             weapon_index=None, hitgroup=HitGroup.GENERIC, skip_hooks=False,
             **kwargs):
-        """Method used to hurt the entity with the given arguments."""
+        """Deal damage to the entity.
+
+        :param int damage:
+            Amount of damage to deal.
+        :param DamageTypes damage_type:
+            Type of the dealed damage.
+        :param int attacker_index:
+            If not None, the index will be used as the attacker.
+        :param int weapon_index:
+            If not None, the index will be used as the weapon. This method
+            also tries to retrieve the attacker from the weapon, if
+            ``attacker_index`` wasn't set.
+        :param HitGroup hitgroup:
+            The hitgroup where the damage should be applied.
+        :param bool skip_hooks:
+            If True, the damage will be dealed directly by skipping any
+            registered hooks.
+        """
         # Import Entity classes
         # Doing this in the global scope causes cross import errors
         from weapons.entity import Weapon
@@ -730,7 +828,7 @@ def take_damage(
     @wrap_entity_mem_func
     def teleport(self, origin=None, angle=None, velocity=None):
         """Change the origin, angle and/or velocity of the entity.
-        
+
         :param Vector origin:
             New location of the entity.
         :param QAngle angle:
@@ -762,7 +860,8 @@ def set_parent(self, parent, attachment=INVALID_ATTACHMENT_INDEX):
 def _on_entity_deleted(base_entity):
     """Called when an entity is removed.
 
-    :param BaseEntity base_entity: The removed entity.
+    :param BaseEntity base_entity:
+        The removed entity.
     """
     # Make sure the entity is networkable...
     if not base_entity.is_networked():