WIP: Updating and reformatting existing docstrings.

pysamp/__init__.py

@@ -1,10 +1,18 @@
 """Snake case wrappers for PEP8 compatibility."""
-from typing import Tuple, Callable
-import functools
-from pysamp.event import registry
 
+# Disable warnings for missing docstrings in modukle:
+# pylint: disable=C0114
+
+import functools
+from typing import Callable, Tuple
 
+from pysamp.event import registry
 from samp import (
+    CAMERA_CUT,
+    INVALID_PLAYER_ID,
+    INVALID_VEHICLE_ID,
+    MAPICON_LOCAL,
+    SPECTATE_MODE_NORMAL,
     AddMenuItem,
     AddPlayerClass,
     AddPlayerClassEx,
@@ -32,7 +40,6 @@
     BlockIpAddress,
     CallNativeFunction,
     CallRemoteFunction,
-    RegisterCallback,
     CancelEdit,
     CancelSelectTextDraw,
     ChangeVehicleColor,
@@ -196,7 +203,6 @@
     GetWeaponName,
     GivePlayerMoney,
     GivePlayerWeapon,
-    gpci as _gpci,
     HideMenuForPlayer,
     InterpolateCameraLookAt,
     InterpolateCameraPos,
@@ -222,6 +228,7 @@
     IsValidVehicle,
     IsVehicleStreamedIn,
     Kick,
+    KillTimer,
     LimitGlobalChatRadius,
     LimitPlayerMarkerRadius,
     LinkVehicleToInterior,
@@ -237,6 +244,7 @@
     NetStats_MessagesRecvPerSecond,
     NetStats_MessagesSent,
     NetStats_PacketLossPercent,
+    OBJECT_MATERIAL_SIZE_256x128,
     PlayAudioStreamForPlayer,
     PlayCrimeReportForPlayer,
     PlayerPlaySound,
@@ -262,6 +270,7 @@
     PlayerTextDrawTextSize,
     PlayerTextDrawUseBox,
     PutPlayerInVehicle,
+    RegisterCallback,
     RemoveBuildingForPlayer,
     RemovePlayerAttachedObject,
     RemovePlayerFromVehicle,
@@ -342,7 +351,6 @@
     SetSVarString,
     SetTeamCount,
     SetTimer,
-    KillTimer,
     SetVehicleAngularVelocity,
     SetVehicleHealth,
     SetVehicleNumberPlate,
@@ -399,13 +407,8 @@
     UpdateVehicleDamageStatus,
     UsePlayerPedAnims,
     VectorSize,
-    CAMERA_CUT,
-    MAPICON_LOCAL,
-    SPECTATE_MODE_NORMAL,
-    OBJECT_MATERIAL_SIZE_256x128,
-    INVALID_PLAYER_ID,
-    INVALID_VEHICLE_ID
 )
+from samp import gpci as _gpci
 
 from .callbacks import _path_hook  # noqa
 
@@ -715,8 +718,7 @@ def remove_building_for_player(
 def get_player_last_shot_vectors(
     player_id: int,
 ) -> Tuple[float, float, float, float, float, float]:
-    """
-    This function returns two coordinates in a tuple.
+    """This function returns two coordinates in a tuple.
     The first three values are the coordinate where the shot was shot from.
     The last three values are where the bullet hit (if it hit something).
 
@@ -2364,7 +2366,7 @@ def get_vehicle_z_angle(vehicle_id: int) -> float:
 
 
 def get_vehicle_rotation_quat(
-    vehicle_id: int
+    vehicle_id: int,
 ) -> Tuple[float, float, float, float]:
     return GetVehicleRotationQuat(vehicle_id)
 
@@ -2699,7 +2701,7 @@ def create_player_3d_text_label(
         draw_distance,
         attached_player,
         attached_vehicle,
-        test_line_of_sight
+        test_line_of_sight,
     )
 
 
@@ -2718,10 +2720,7 @@ def gpci(playerid: int) -> str:
 
 
 def set_timer(
-    function: Callable,
-    interval_ms: int,
-    repeating: bool = False,
-    *args: Tuple
+    function: Callable, interval_ms: int, repeating: bool = False, *args: Tuple
 ) -> int:
     return SetTimer(function, interval_ms, repeating, *args)
 
@@ -2744,24 +2743,24 @@ def register_callback(name: str, arguments: str):
 
 on_gamemode_init = functools.partial(
     registry.register_callback,
-    'OnGameModeInit',
-    group='pysamp.on_gamemode_init',
+    "OnGameModeInit",
+    group="pysamp.on_gamemode_init",
 )
 
 on_gamemode_exit = functools.partial(
     registry.register_callback,
-    'OnGameModeExit',
-    group='pysamp.on_gamemode_exit',
+    "OnGameModeExit",
+    group="pysamp.on_gamemode_exit",
 )
 
 on_rcon_login_attempt = functools.partial(
     registry.register_callback,
-    'OnRconLoginAttempt',
-    group='pysamp.on_rcon_login_attempt',
+    "OnRconLoginAttempt",
+    group="pysamp.on_rcon_login_attempt",
 )
 
 on_incoming_connection = functools.partial(
     registry.register_callback,
-    'OnIncomingConnection',
-    group='pysamp.on_incoming_connection',
+    "OnIncomingConnection",
+    group="pysamp.on_incoming_connection",
 )

pysamp/actor.py

@@ -1,3 +1,11 @@
+"""Actors module, to handle and create actors.
+
+These 'actors' are like NPCs, however they have limited functionality.
+They do not take up server player slots.
+"""
+
+from typing import Optional, Tuple
+
 from pysamp import (
     apply_actor_animation,
     clear_actor_animations,
@@ -16,7 +24,6 @@
     set_actor_pos,
     set_actor_virtual_world,
 )
-from typing import Optional, Tuple
 from pysamp.event import event
 
 
@@ -30,17 +37,12 @@ class Actor:
     https://open.mp/docs/scripting/functions/CreateActor
     """
 
-    def __init__(self, id: int) -> None:
+    def __init__(self, id: int) -> None:  # noqa: D107
         self.id: int = id
 
     @classmethod
     def create(
-        cls,
-        modelid: int,
-        x: float,
-        y: float,
-        z: float,
-        rotation: float
+        cls, modelid: int, x: float, y: float, z: float, rotation: float
     ) -> Optional["Actor"]:
         """Create a new actor.
 
@@ -52,11 +54,10 @@ def create(
         :return: An :class:`Actor` object. Will return ``None`` if the actor
             limit is reached of 1000 actors.
         """
-        return cls(
-            create_actor(modelid, x, y, z, rotation)
-        )
+        return cls(create_actor(modelid, x, y, z, rotation))
 
     def get_id(self) -> int:
+        """Get the actor ID."""
         return self.id
 
     def destroy(self) -> bool:
@@ -72,7 +73,11 @@ def get_virtual_world(self) -> int:
         return get_actor_virtual_world(self.id)
 
     def set_virtual_world(self, virtual_world: int) -> bool:
-        """Set the actor to a specific virtual world id."""
+        """Set the actor to a specific virtual world id.
+
+        :param int virtual_world: The virtual world ID (0-65535).
+        :return: This method does not return anything.
+        """
         return set_actor_virtual_world(self.id, virtual_world)
 
     def apply_animation(
@@ -86,7 +91,18 @@ def apply_animation(
         freeze: bool,
         time: int,
     ) -> bool:
-        """Set an animation on the actor."""
+        """Set an animation on the actor.
+
+        :param str animation_library: The name of the animation library.
+        :param str animation_name: The name of the animation.
+        :param float delta: The animation delta.
+        :param bool loop: Whether the animation should loop.
+        :param bool lock_x: Whether the animation should lock the X axis.
+        :param bool lock_y: Whether the animation should lock the Y axis.
+        :param bool freeze: Whether the animation should freeze.
+        :param int time: The animation time.
+        :return: This method does not return anything.
+        """
         return apply_actor_animation(
             self.id,
             animation_library,
@@ -100,51 +116,98 @@ def apply_animation(
         )
 
     def clear_animations(self) -> bool:
-        """Clear the animations that are in use by the actor, if any."""
+        """Clear the animations that are in use by the actor, if any.
+
+        :return: This method does not return anything.
+        """
         return clear_actor_animations(self.id)
 
     def get_position(self) -> Tuple[float, float, float]:
-        """Gets the current world coordinates of where the actor is located."""
+        """Get the current world coordinates of where the actor is located.
+
+        :return: A tuple of (x, y, z).
+        """
         return get_actor_pos(self.id)
 
     def set_position(self, x: float, y: float, z: float) -> bool:
-        """Set a new position for the actor."""
+        """Set a new position for the actor.
+
+        For rotation, check out method :meth:`~set_facing_angle`.
+        """
+        if not self.is_valid():
+            return False
         return set_actor_pos(self.id, x, y, z)
 
     def get_facing_angle(self) -> float:
-        """Get the actor's facing angle."""
+        """Get the actor's facing angle.
+
+        :return: The actor's facing angle.
+        """
         return get_actor_facing_angle(self.id)
 
     def set_facing_angle(self, angle: float) -> bool:
-        """Set the actor's facing angle."""
+        """Set the actor's facing angle.
+
+        For position, check out method :meth:`~set_position`.
+        """
+        if not self.is_valid():
+            return False
         return set_actor_facing_angle(self.id, angle)
 
     def get_health(self) -> float:
-        """Get how much health the actor has."""
+        """Get how much health the actor has.
+
+        :return: The actor's health, between `0.0` and `100.0`.
+        """
         return get_actor_health(self.id)
 
     def set_health(self, health: float) -> bool:
-        """Set the health of the actor."""
+        """Set the health of the actor.
+
+        :param health: A float between `0.0` and `100.0`.
+        :return: This method does not return anything.
+        """
         return set_actor_health(self.id, health)
 
     def is_invulnerable(self) -> bool:
-        """See if the actor is invulnerable to damage."""
+        """See if the actor is invulnerable to damage.
+
+        :return: ``True`` if the actor is invulnerable, ``False`` otherwise.
+        """
         return is_actor_invulnerable(self.id)
 
     def set_invulnerable(self, invulnerable: bool = True) -> bool:
-        """Set the actor to be invlunerable to damage."""
+        """Set the actor to be invlunerable to damage.
+
+        :param bool invulnerable: Whether the actor should be invulnerable.
+        :return: This method does not return anything.
+        """
         return set_actor_invulnerable(self.id, invulnerable)
 
     def is_valid(self) -> bool:
-        """Check if the actor is valid."""
+        """Check if the actor is valid.
+
+        :return: ``True`` if valid, otherwise ``False``.
+        """
         return is_valid_actor(self.id)
 
     @event("OnActorStreamIn")
     def on_stream_in(cls, actorid: int, forplayerid: int):
+        """Event that is triggered when an actor is streamed in to a player.
+
+        :param Actor actor: The actor that was streamed in.
+        :param Player forplayer: The player that streamed the actor in.
+        """
         return (cls(actorid), Player(forplayerid))
 
     @event("OnActorStreamOut")
     def on_stream_out(cls, actorid: int, forplayerid: int):
+        """Event that is triggered when an actor is streamed out of a player.
+
+        :param Actor actor: The actor that was streamed out.
+        :param Player forplayer: The player that streamed the actor out.
+        """
         return (cls(actorid), Player(forplayerid))
 
-from pysamp.player import Player  # noqa
+
+from pysamp.player import Player  # noqa