Documentation for callbacks

[Ykpauneu]

• Added documentation for callbacks

[dennorske]

And in order to get these on sphinx, I will need to set up a proper pipeline and config to read the event-docs ^_^

[dennorske]

As mentioned on discord DM with you, we call these events instead of callbacks, and they are used subscribe to things like callbacks behind the scenes.

In the API itself, they look like this now:

    @event("OnActorStreamIn")
    def on_stream_in(cls, actorid: int, forplayerid: int):
        """This callback is called when an actor is streamed in\
        by a player's client.
        :param int actorid: The ID of the actor.
        :param int forplayerid: The ID of the player\
        that streamed the actor in.
        :returns: No return value.
        .. note:: This callbackcan also be called by NPC.
        """
        return (cls(actorid), Player(forplayerid))

...But they are part of our OO Pysamp 2.1 API. The way you use them is not how they look in the API, but rather what the decorator does (and returns) to the methods we decorate. Imagine we use that event as an example:

@Actor.on_stream_in
def my_event_handling_function(actor: Actor, player: Player):  
    # see the expected types, these are the same as the ones we return from that event above
    pass

That means the documentation needs to reflect what the event "decorates" and returns, instead of what they are expecting behind the scenes. The user should not have to handle playerid's or actorid's, but rather the objects themselves.