Refactor: adjust docstrings based on feedback

* Capitalize month names
* Add backticks to `sha` attr reference
* Avoid misusing the term 'poll'

Co-authored-by: MarkKoz <[email protected]>

3 files changed, 13 insertions, 17 deletions

diff --git a/bot/constants.py b/bot/constants.py
index 34bbf87f..22ea9177 100644
--- a/bot/constants.py
+++ b/bot/constants.py
@@ -81,7 +81,7 @@ class Client(NamedTuple):
     token = environ.get("SEASONALBOT_TOKEN")
     sentry_dsn = environ.get("SEASONALBOT_SENTRY_DSN")
     debug = environ.get("SEASONALBOT_DEBUG", "").lower() == "true"
-    # Override seasonal locks: 1 (january) to 12 (december)
+    # Override seasonal locks: 1 (January) to 12 (December)
     month_override = int(environ["MONTH_OVERRIDE"]) if "MONTH_OVERRIDE" in environ else None
 
 
diff --git a/bot/exts/evergreen/branding.py b/bot/exts/evergreen/branding.py
index 8fd8d6eb..754e8cfa 100644
--- a/bot/exts/evergreen/branding.py
+++ b/bot/exts/evergreen/branding.py
@@ -43,7 +43,7 @@ class GithubFile(t.NamedTuple):
     """
     Represents a remote file on Github.
 
-    The sha hash is kept so that we can determine that a file has changed,
+    The `sha` hash is kept so that we can determine that a file has changed,
     despite its filename remaining unchanged.
     """
 
@@ -266,7 +266,7 @@ class BrandingManager(commands.Cog):
 
     async def _get_files(self, path: str, include_dirs: bool = False) -> t.Dict[str, GithubFile]:
         """
-        Poll `path` in branding repo for information about present files.
+        Get files at `path` in the branding repository.
 
         If `include_dirs` is False (default), only returns files at `path`.
         Otherwise, will return both files and directories. Never returns symlinks.
@@ -292,10 +292,10 @@ class BrandingManager(commands.Cog):
 
     async def refresh(self) -> bool:
         """
-        Poll Github API to refresh currently available icons.
+        Synchronize available assets with branding repository.
 
         If the current season is not the evergreen, and lacks at least one asset,
-        we also poll the evergreen seasonal dir as fallback for missing assets.
+        we use the evergreen seasonal dir as fallback for missing assets.
 
         Finally, if neither the seasonal nor fallback branding directories contain
         an asset, it will simply be ignored.
@@ -455,7 +455,7 @@ class BrandingManager(commands.Cog):
     @branding_cmds.command(name="info", aliases=["status"])
     async def branding_info(self, ctx: commands.Context) -> None:
         """
-        Show assets for current season.
+        Show available assets for current season.
 
         This can be used to confirm that assets have been resolved properly.
         When `apply` is used, it attempts to upload exactly the assets listed here.
@@ -464,11 +464,7 @@ class BrandingManager(commands.Cog):
 
     @branding_cmds.command(name="refresh")
     async def branding_refresh(self, ctx: commands.Context) -> None:
-        """
-        Refresh current season from branding repository.
-
-        Polls Github API to refresh assets available for current season.
-        """
+        """Sync currently available assets with branding repository."""
         async with ctx.typing():
             await self.refresh()
             await self.branding_info(ctx)
diff --git a/bot/seasons.py b/bot/seasons.py
index 30979d2a..cb74ec89 100644
--- a/bot/seasons.py
+++ b/bot/seasons.py
@@ -30,7 +30,7 @@ class SeasonBase:
 
 
 class Christmas(SeasonBase):
-    """Branding for december."""
+    """Branding for December."""
 
     season_name = "Festive season"
     bot_name = "Merrybot"
@@ -47,7 +47,7 @@ class Christmas(SeasonBase):
 
 
 class Easter(SeasonBase):
-    """Branding for april."""
+    """Branding for April."""
 
     season_name = "Easter"
     bot_name = "BunnyBot"
@@ -64,7 +64,7 @@ class Easter(SeasonBase):
 
 
 class Halloween(SeasonBase):
-    """Branding for october."""
+    """Branding for October."""
 
     season_name = "Halloween"
     bot_name = "NeonBot"
@@ -78,7 +78,7 @@ class Halloween(SeasonBase):
 
 
 class Pride(SeasonBase):
-    """Branding for june."""
+    """Branding for June."""
 
     season_name = "Pride"
     bot_name = "ProudBot"
@@ -98,7 +98,7 @@ class Pride(SeasonBase):
 
 
 class Valentines(SeasonBase):
-    """Branding for february."""
+    """Branding for February."""
 
     season_name = "Valentines"
     bot_name = "TenderBot"
@@ -112,7 +112,7 @@ class Valentines(SeasonBase):
 
 
 class Wildcard(SeasonBase):
-    """Branding for august."""
+    """Branding for August."""
 
     season_name = "Wildcard"
     bot_name = "RetroBot"