📔 Improve bullet documentation

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.
+    The abstract base class for Bullet models.
-
-    **All** methods of :class:`Bullet` can raise :exc:`.exc.BulletException`, such as :class:`.exc.ForbiddenError` or
-    :class:`.exc.NotSupportedError`.
     """
 
     @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.