more comments on functions

ballsdex/packages/info/cog.py

@@ -47,6 +47,9 @@ def __init__(self, bot: "BallsDexBot"):
         self.bot = bot
 
     async def _get_10_balls_emojis(self) -> list[discord.Emoji]:
+        """
+        Get 10 random enabled countryball emojis.
+        """
         balls: list[Ball] = random.choices(
             [x for x in countryballs.values() if x.enabled], k=min(10, len(countryballs))
         )

ballsdex/packages/trade/display.py

@@ -12,6 +12,10 @@
 
 
 class TradeViewFormat(menus.ListPageSource):
+    """
+    Formats the trade history for a user.
+    """
+
     def __init__(
         self,
         entries: Iterable[TradeModel],
@@ -44,6 +48,9 @@ async def format_page(self, menu: Pages, trade: TradeModel) -> discord.Embed:
 
 
 def _get_prefix_emote(trader: TradingUser) -> str:
+    """
+    Determine the appropriate emoji prefix for a trader based on their status.
+    """
     if trader.cancelled:
         return "\N{NO ENTRY SIGN}"
     elif trader.accepted:
@@ -57,6 +64,13 @@ def _get_prefix_emote(trader: TradingUser) -> str:
 def _build_list_of_strings(
     trader: TradingUser, bot: "BallsDexBot", short: bool = False
 ) -> list[str]:
+    """
+    Build a list of strings representing a trader's proposal, ensuring the total length 
+    does not exceed 1024 characters per field for Discord embeds.
+
+    This function avoids breaking a line in the middle of a description. The output is 
+    split across multiple lines if necessary, ensuring no line exceeds the character limit.
+    """
     # this builds a list of strings always lower than 1024 characters
     # while not cutting in the middle of a line
     proposal: list[str] = [""]

ballsdex/packages/trade/menu.py

@@ -30,6 +30,9 @@ class InvalidTradeOperation(Exception):
 
 
 class TradeView(View):
+    """
+    Handles the buttons appearing below the trade embed.
+    """
     def __init__(self, trade: TradeMenu):
         super().__init__(timeout=60 * 30)
         self.trade = trade
@@ -47,6 +50,9 @@ async def interaction_check(self, interaction: discord.Interaction, /) -> bool:
 
     @button(label="Lock proposal", emoji="\N{LOCK}", style=discord.ButtonStyle.primary)
     async def lock(self, interaction: discord.Interaction, button: Button):
+        """
+        Format and handle the 'Lock proposal' button.
+        """
         trader = self.trade._get_trader(interaction.user)
         if trader.locked:
             await interaction.response.send_message(
@@ -69,6 +75,9 @@ async def lock(self, interaction: discord.Interaction, button: Button):
 
     @button(label="Reset", emoji="\N{DASH SYMBOL}", style=discord.ButtonStyle.secondary)
     async def clear(self, interaction: discord.Interaction, button: Button):
+        """
+        Format and handle the 'Reset' button.
+        """
         trader = self.trade._get_trader(interaction.user)
         if trader.locked:
             await interaction.response.send_message(
@@ -88,11 +97,17 @@ async def clear(self, interaction: discord.Interaction, button: Button):
         style=discord.ButtonStyle.danger,
     )
     async def cancel(self, interaction: discord.Interaction, button: Button):
+        """
+        Format and handle the 'Cancel trade' button.
+        """
         await self.trade.user_cancel(self.trade._get_trader(interaction.user))
         await interaction.response.send_message("Trade has been cancelled.", ephemeral=True)
 
 
 class ConfirmView(View):
+    """
+    Handles the buttons below the trade embed on the last phase of a trade.
+    """
     def __init__(self, trade: TradeMenu):
         super().__init__(timeout=90)
         self.trade = trade
@@ -113,6 +128,9 @@ async def interaction_check(self, interaction: discord.Interaction, /) -> bool:
         style=discord.ButtonStyle.success, emoji="\N{HEAVY CHECK MARK}\N{VARIATION SELECTOR-16}"
     )
     async def accept_button(self, interaction: discord.Interaction, button: Button):
+        """
+        Handle the 'Accept' button.
+        """
         trader = self.trade._get_trader(interaction.user)
         if self.trade.cooldown_start_time is None:
             return
@@ -151,6 +169,9 @@ async def accept_button(self, interaction: discord.Interaction, button: Button):
         emoji="\N{HEAVY MULTIPLICATION X}\N{VARIATION SELECTOR-16}",
     )
     async def deny_button(self, interaction: discord.Interaction, button: Button):
+        """
+        Handle the 'Deny' button.
+        """
         await self.trade.user_cancel(self.trade._get_trader(interaction.user))
         await interaction.response.send_message("Trade has been cancelled.", ephemeral=True)
 
@@ -182,6 +203,9 @@ def _get_trader(self, user: discord.User | discord.Member) -> TradingUser:
         raise RuntimeError(f"User with ID {user.id} cannot be found in the trade")
 
     def _generate_embed(self):
+        """
+        Generate the trade embed with the initial content.
+        """
         add_command = self.cog.add.extras.get("mention", "`/trade add`")
         remove_command = self.cog.remove.extras.get("mention", "`/trade remove`")
         view_command = self.cog.view.extras.get("mention", "`/trade view`")
@@ -293,6 +317,9 @@ async def user_cancel(self, trader: TradingUser):
         await self.cancel()
 
     async def perform_trade(self):
+        """
+        Perform the trade if possible, else handle the errors.
+        """
         valid_transferable_countryballs: list[BallInstance] = []
 
         trade = await Trade.create(player1=self.trader1.player, player2=self.trader2.player)