From cfee9fa42842d95ad41d80690513aaf68f372e03 Mon Sep 17 00:00:00 2001
From: Thomas Rubini <74205383+ThomasRubini@users.noreply.github.com>
Date: Fri, 13 Jan 2023 09:44:57 +0100
Subject: [PATCH] discord_bot.py documentation

---
 truthseeker/discord_bot.py | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/truthseeker/discord_bot.py b/truthseeker/discord_bot.py
index 9d42acb..9a9a354 100644
--- a/truthseeker/discord_bot.py
+++ b/truthseeker/discord_bot.py
@@ -3,10 +3,14 @@ import threading
 import truthseeker
 import asyncio
 
-async def empty_coro():
-    return
-
 class DiscordBot:
+    """
+    Wrapper around a discord bot, providing utility methods to interact with it
+
+    :attr Client bot: the underlying discord bot from discord.py
+    :attr TextChannel __channel__: the channel used by the bot to send messages
+    """
+
     def __init__(self):
         self.bot = discord.Client(intents=discord.Intents.default())
         self.__channel__ = None
@@ -19,7 +23,10 @@ class DiscordBot:
             self.__setup__channel__()
             self.update_games_presence()
 
-    def __setup__channel__(self):
+    def __setup__channel__(self) -> None:
+        """
+        Setup the channel that the bot will send message in
+        """
         if len(self.bot.guilds) == 1:
             self.__channel__ = discord.utils.get(self.bot.guilds[0].channels, name="bot")
         else:
@@ -31,6 +38,9 @@ class DiscordBot:
         return thr
 
     def API(func):
+        """
+        Decorator used to wrap APIs methods, to handle thread context change, and ready check
+        """
         def decorator(self, *args, **kwargs):
             if self.bot and self.bot.is_ready():
                 self.event_loop.create_task(func(self, *args, **kwargs))
@@ -39,7 +49,10 @@ class DiscordBot:
         return decorator
 
     @API
-    async def update_games_presence(self):
+    async def update_games_presence(self) -> None:
+        """
+        Update the bot's status using the app's current context
+        """
         games_n = len(truthseeker.APP.games_list)
         activity_name = f"Handling {games_n} game{'' if games_n==1 else 's'} !"
         activity = discord.Activity(name=activity_name, type=discord.ActivityType.watching)
@@ -47,7 +60,10 @@ class DiscordBot:
 
     @API
     async def send_message(self, text):
+        """
+        Send a message to the channel used by the bot
+        """
         if self.__channel__:
             await self.__channel__.send(text)
         else:
-            print("channel member not defined, not sending discord message")
+            print("channel not defined, not sending discord message")