From a9cc5e77611b8fcb73188ce005973486a170953a Mon Sep 17 00:00:00 2001 From: Stefano Pigozzi Date: Wed, 30 Dec 2020 13:18:07 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=94=20Improve=20bullet=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- royalnet/engineer/bullet.py | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/royalnet/engineer/bullet.py b/royalnet/engineer/bullet.py index 459bd46d..5a8dd78b 100644 --- a/royalnet/engineer/bullet.py +++ b/royalnet/engineer/bullet.py @@ -1,5 +1,17 @@ """ -Bullets are parts of the data model +Bullets are parts of the data model that :mod:`royalnet.engineer` uses to build a common interface between different +chat apps (*frontends*). + +They exclusively use coroutine functions to access data, as it may be required to fetch it from a remote location before +it is available. + +**All** coroutine functions can have three different results: +- :exc:`.exc.BulletException` is raised, meaning that something went wrong during the data retrieval. + - :exc:`.exc.NotSupportedError` is raised, meaning that the frontend does not support the feature the requested data + is about (asking for :meth:`.Message.reply_to` in an IRC frontend, for example). +- :data:`None` is returned, meaning that there is no data in that field (if a message is not a reply to anything, + :meth:`Message.reply_to` will be :data:`None`. +- The data is returned. """ from __future__ import annotations @@ -14,10 +26,7 @@ from . import exc class Bullet(metaclass=abc.ABCMeta): """ - The abstract base class for Bullet data models. - - **All** methods of :class:`Bullet` can raise :exc:`.exc.BulletException`, such as :class:`.exc.ForbiddenError` or - :class:`.exc.NotSupportedError`. + The abstract base class for Bullet models. """ @abc.abstractmethod @@ -92,7 +101,7 @@ class Channel(Bullet, metaclass=abc.ABCMeta): async def send_message(self, text: str) -> t.Optional[Message]: """ - Send a message in this channel. + Send a message in the channel. :param text: The text to send in the message. :return: The sent message.