Fix docstrings and add a few explanatory comments

4 files changed, 8 insertions, 5 deletions

diff --git a/bot/constants.py b/bot/constants.py
index 00d75a3f..cb5a91cc 100644
--- a/bot/constants.py
+++ b/bot/constants.py
@@ -40,8 +40,8 @@ def _parse_aoc_leaderboard_env() -> Dict[str, AdventOfCodeLeaderboard]:
     Parse the environment variable containing leaderboard information.
 
     A leaderboard should be specified in the format `id,session,join_code`,
-    without the backticks. If more than leaderboard needs to be added to the
-    constants, separate the individual leaderboards with `::`.
+    without the backticks. If more than one leaderboard needs to be added to
+    the constant, separate the individual leaderboards with `::`.
 
     Example ENV: `id1,session1,join_code1::id2,session2,join_code2`
     """
diff --git a/bot/exts/christmas/advent_of_code/__init__.py b/bot/exts/christmas/advent_of_code/__init__.py
index 20ac5ab9..3c521168 100644
--- a/bot/exts/christmas/advent_of_code/__init__.py
+++ b/bot/exts/christmas/advent_of_code/__init__.py
@@ -2,7 +2,7 @@ from bot.bot import Bot
 
 
 def setup(bot: Bot) -> None:
-    """Advent of Code Cog load."""
+    """Set up the Advent of Code extension."""
     # Import the Cog at runtime to prevent side effects like defining
     # RedisCache instances too early.
     from ._cog import AdventOfCode
diff --git a/bot/exts/christmas/advent_of_code/_cog.py b/bot/exts/christmas/advent_of_code/_cog.py
index 388d0592..19baca93 100644
--- a/bot/exts/christmas/advent_of_code/_cog.py
+++ b/bot/exts/christmas/advent_of_code/_cog.py
@@ -230,7 +230,7 @@ class AdventOfCode(commands.Cog):
     @adventofcode_group.command(name="join", aliases=("j",), brief="Learn how to join the leaderboard (via DM)")
     @override_in_channel(AOC_WHITELIST)
     async def join_leaderboard(self, ctx: commands.Context) -> None:
-        """DM the user the information for joining the PyDis AoC private leaderboard."""
+        """DM the user the information for joining the Python Discord leaderboard."""
         author = ctx.message.author
         log.info(f"{author.name} ({author.id}) has requested a PyDis AoC leaderboard code")
 
@@ -284,7 +284,7 @@ class AdventOfCode(commands.Cog):
     @adventofcode_group.command(
         name="stats",
         aliases=("dailystats", "ds"),
-        brief="Get daily statistics for the PyDis private leaderboard"
+        brief="Get daily statistics for the Python Discord leaderboard"
     )
     @override_in_channel(AOC_WHITELIST)
     async def private_leaderboard_daily_stats(self, ctx: commands.Context) -> None:
diff --git a/bot/exts/christmas/advent_of_code/_helpers.py b/bot/exts/christmas/advent_of_code/_helpers.py
index 8b85bf5d..57aad54d 100644
--- a/bot/exts/christmas/advent_of_code/_helpers.py
+++ b/bot/exts/christmas/advent_of_code/_helpers.py
@@ -102,10 +102,13 @@ def _parse_raw_leaderboard_data(raw_leaderboard_data: dict) -> dict:
         sorted(leaderboard.items(), key=lambda t: t[1]["score"], reverse=True)
     )
 
+    # Create summary stats for the stars completed for each day of the event.
     daily_stats = {}
     for day in range(1, 26):
         star_one = len(star_results.get((day, 1), []))
         star_two = len(star_results.get((day, 1), []))
+        # By using a dictionary instead of namedtuple here, we can serialize
+        # this data to JSON in order to cache it in Redis.
         daily_stats[day] = {"star_one": star_one, "star_two": star_two}
 
     return {"daily_stats": daily_stats, "leaderboard": sorted_leaderboard}