refactor(afk.py): improve readability by adding function docstrings and type hints

style(schema.prisma, afk.py): improve code formatting for better readability
feat(afk.py): add welcome back message when user returns from AFK
fix(afk.py): ensure guild exists before inserting AFK status to prevent errors

prisma/schema.prisma

@@ -11,14 +11,14 @@ datasource db {
 }
 
 model Guild {
-  guild_id        BigInt        @id
-  guild_joined_at DateTime?     @default(now())
-  cases           Case[]
-  snippets        Snippet[]
-  notes           Note[]
-  reminders       Reminder[]
-  guild_config    GuildConfig[]
-  AFK             AFKModel[]
+  guild_id         BigInt             @id
+  guild_joined_at  DateTime?          @default(now())
+  cases            Case[]
+  snippets         Snippet[]
+  notes            Note[]
+  reminders        Reminder[]
+  guild_config     GuildConfig[]
+  AFK              AFKModel[]
   Starboard        Starboard?
   StarboardMessage StarboardMessage[]
   case_count       BigInt             @default(0)

tux/cogs/utility/afk.py

@@ -19,15 +19,31 @@ class AFK(commands.Cog):
         usage="afk [reason]",
     )
     @commands.guild_only()
-    async def afk(self, ctx: commands.Context[Tux], *, reason: str = "No reason."):
+    async def afk(
+        self,
+        ctx: commands.Context[Tux],
+        *,
+        reason: str = "No reason.",
+    ) -> discord.Message:
+        """
+        Set yourself as AFK.
+
+        Parameters
+        ----------
+        reason : str
+            The reason you are AFK.
+        """
+
         target = ctx.author
+
         assert ctx.guild
-        assert isinstance(target, discord.Member)  # only hit if inside a guild
+        assert isinstance(target, discord.Member)
 
         if await self.db.is_afk(target.id, guild_id=ctx.guild.id):
             return await ctx.send("You are already afk!", ephemeral=True)
 
         max_name_limit = 32
+
         if len(target.display_name) >= max_name_limit - 6:
             truncated_name = f"{target.display_name[:max_name_limit - 9]}..."
             new_name = f"[AFK] {truncated_name}"
@@ -36,6 +52,7 @@ class AFK(commands.Cog):
 
         await self.db.insert_afk(target.id, target.display_name, reason, ctx.guild.id)
         await target.edit(nick=new_name)
+
         return await ctx.send(
             content="\N{SLEEPING SYMBOL} || You are now afk! " + f"Reason: `{reason}`",
             allowed_mentions=discord.AllowedMentions(
@@ -46,7 +63,16 @@ class AFK(commands.Cog):
         )
 
     @commands.Cog.listener("on_message")
-    async def remove_afk(self, message: discord.Message):
+    async def remove_afk(self, message: discord.Message) -> None:
+        """
+        Remove the AFK status of a member when they send a message.
+
+        Parameters
+        ----------
+        message : discord.Message
+            The message to check.
+        """
+
         if not message.guild or message.author.bot:
             return
 
@@ -60,11 +86,21 @@ class AFK(commands.Cog):
         assert isinstance(message.author, discord.Member)
 
         await self.db.remove_afk(message.author.id)
+
         await message.reply("Welcome back!", delete_after=5)
         await message.author.edit(nick=entry.nickname)
 
     @commands.Cog.listener("on_message")
-    async def check_afk(self, message: discord.Message):
+    async def check_afk(self, message: discord.Message) -> None:
+        """
+        Check if a message mentions an AFK member.
+
+        Parameters
+        ----------
+        message : discord.Message
+            The message to check.
+        """
+
         if not message.guild:
             return
 
@@ -72,6 +108,7 @@ class AFK(commands.Cog):
             return
 
         afks_mentioned: list[AFKModel] = []
+
         for mentioned in message.mentions:
             entry = await self.db.get_afk_member(mentioned.id, guild_id=message.guild.id)
             if entry:
@@ -84,6 +121,7 @@ class AFK(commands.Cog):
             f"{mentioned.mention} is currently AFK: `{afk.reason}` (<t:{int(afk.since.timestamp())}:R>)"
             for mentioned, afk in zip(message.mentions, afks_mentioned, strict=False)
         ]
+
         await message.reply(
             content="\n".join(msgs),
             allowed_mentions=discord.AllowedMentions(

tux/database/controllers/afk.py

@@ -9,8 +9,10 @@ class AfkController:
 
     async def ensure_guild_exists(self, guild_id: int) -> Guild:
         guild = await self.guild.find_first(where={"guild_id": guild_id})
+
         if guild is None:
             return await self.guild.create(data={"guild_id": guild_id})
+
         return guild
 
     async def get_afk_member(self, member_id: int, *, guild_id: int) -> AFKModel | None:
@@ -22,6 +24,7 @@ class AfkController:
 
     async def insert_afk(self, member_id: int, nickname: str, reason: str, guild_id: int) -> AFKModel:
         await self.ensure_guild_exists(guild_id)
+
         return await self.table.create(
             data={
                 "member_id": member_id,