Final docstrings

didier/cogs/discord.py

@@ -53,7 +53,7 @@ class Discord(commands.Cog):
         async with self.client.postgres_session as session:
             birthday = await birthdays.get_birthday_for_user(session, user_id)
 
-        name: Optional[str] = user and f"{user.display_name}'s"
+        name: Optional[str] = f"{user.display_name}'s" if user is not None else None
 
         if birthday is None:
             return await ctx.reply(f"I don't know {name or 'your'} birthday.", mention_author=False)
@@ -87,12 +87,12 @@ class Discord(commands.Cog):
     async def bookmark(self, ctx: commands.Context, *, label: Optional[str] = None):
         """Post the message bookmarked with `label`.
 
-        The `label` argument can contain spaces and does not require quotes around it. For example:
+        The `label`-argument can contain spaces and does not require quotes around it. For example:
         ```
         didier bookmark some label with multiple words
         ```
 
-        If no argument for `label` is provided, this is a shortcut to `bookmark search`.
+        When no value for `label` is provided, this is a shortcut to `bookmark search`.
         """
         # No label: shortcut to display bookmarks
         if label is None:
@@ -113,7 +113,8 @@ class Discord(commands.Cog):
         Instead of the link to a message, you can also reply to the message you wish to bookmark. In this case,
         the `message`-argument can be left out.
 
-        `label` can not be names (or aliases) of subcommands.
+        `label` can not be names (or aliases) of subcommands. However, names with spaces are allowed. If you wish
+        to use a name with spaces, it must be wrapped in "quotes".
         """
         # If no message was passed, allow replying to the message that should be bookmarked
         if message is None and ctx.message.reference is not None:
@@ -167,6 +168,11 @@ class Discord(commands.Cog):
 
         If a value for `query` was provided, results will be filtered down to only labels that include `query`.
         Otherwise, all bookmarks are displayed.
+
+        The `query`-argument can contain spaces and does not require quotes around it. For example:
+        ```
+        didier bookmark search some query with multiple words
+        ```
         """
         async with self.client.postgres_session as session:
             results = await bookmarks.get_bookmarks(session, ctx.author.id, query=query)

didier/cogs/meta.py

@@ -17,7 +17,7 @@ class Meta(commands.Cog):
 
     @commands.command(name="marco")
     async def marco(self, ctx: commands.Context):
-        """Ping command to get Didier's latency."""
+        """Get Didier's latency."""
         return await ctx.reply(f"Polo! {round(self.client.latency * 1000)}ms", mention_author=False)
 
     @commands.command(name="source", aliases=["src"])
@@ -25,6 +25,13 @@ class Meta(commands.Cog):
         """Get a link to the source code of Didier.
 
         If a value for `command_name` is passed, the source for `command_name` is shown instead.
+
+        Example usage:
+        ```
+        didier source
+        didier source dinks
+        didier source source
+        ```
         """
         repo_home = "https://github.com/stijndcl/didier"
 

didier/cogs/other.py

@@ -13,16 +13,18 @@ from didier.data.scrapers import google
 
 
 class Other(commands.Cog):
-    """Cog for commands that don't really belong anywhere else"""
+    """Commands that don't really belong anywhere else."""
 
     client: Didier
 
     def __init__(self, client: Didier):
         self.client = client
 
-    @commands.hybrid_command(name="define", description="Urban Dictionary", aliases=["Ud", "Urban"], usage="[Term]")
+    @commands.hybrid_command(
+        name="define", aliases=["ud", "urban"], description="Look up the definition of a word on the Urban Dictionary"
+    )
     async def define(self, ctx: commands.Context, *, query: str):
-        """Look up the definition of a word on the Urban Dictionary"""
+        """Look up the definition of `query` on the Urban Dictionary."""
         async with ctx.typing():
             status_code, definitions = await urban_dictionary.lookup(self.client.http_session, query)
             if not definitions:
@@ -30,10 +32,17 @@ class Other(commands.Cog):
 
             await ctx.reply(embed=definitions[0].to_embed(), mention_author=False)
 
-    @commands.hybrid_command(name="google", description="Google search", usage="[Query]")
+    @commands.hybrid_command(name="google", description="Google search")
     @app_commands.describe(query="Search query")
     async def google(self, ctx: commands.Context, *, query: str):
-        """Google something"""
+        """Show the Google search results for `query`.
+
+        The `query`-argument can contain spaces and does not require quotes around it. For example:
+        ```
+        didier query didier source github
+        didier query "didier source github"
+        ```
+        """
         async with ctx.typing():
             results = await google.google_search(self.client.http_session, query)
             embed = GoogleSearch(results).to_embed()
@@ -43,9 +52,9 @@ class Other(commands.Cog):
         async with self.client.postgres_session as session:
             return await get_link_by_name(session, name.lower())
 
-    @commands.command(name="Link", aliases=["Links"], usage="[Name]")
+    @commands.command(name="Link", aliases=["Links"])
     async def link_msg(self, ctx: commands.Context, name: str):
-        """Message command to get the link to something"""
+        """Get the link to the resource named `name`."""
         link = await self._get_link(name)
         if link is None:
             return await ctx.reply(f"Found no links matching `{name}`.", mention_author=False)
@@ -53,10 +62,10 @@ class Other(commands.Cog):
         target_message = await self.client.get_reply_target(ctx)
         await target_message.reply(link.url, mention_author=False)
 
-    @app_commands.command(name="link", description="Get the link to something")
+    @app_commands.command(name="link")
-    @app_commands.describe(name="The name of the link")
+    @app_commands.describe(name="The name of the resource")
     async def link_slash(self, interaction: discord.Interaction, name: str):
-        """Slash command to get the link to something"""
+        """Get the link to something."""
         link = await self._get_link(name)
         if link is None:
             return await interaction.response.send_message(f"Found no links matching `{name}`.", ephemeral=True)

didier/cogs/school.py

@@ -43,6 +43,9 @@ class School(commands.Cog):
 
         If no day is provided, this defaults to the schedule for the current day. When invoked during a weekend,
         it will skip forward to the next weekday instead.
+
+        Schedules are personalized based on your roles in the server. If your schedule doesn't look right, make sure
+        that you've got the correct roles selected. In case you do, ping D STIJN.
         """
         if day_dt is None:
             day_dt = date.today()
@@ -68,9 +71,9 @@ class School(commands.Cog):
     )
     @app_commands.rename(day_dt="date")
     async def menu(self, ctx: commands.Context, day_dt: Optional[app_commands.Transform[date, DateTransformer]] = None):
-        """Show the menu in the Ghent University restaurants.
+        """Show the menu in the Ghent University restaurants on `date`.
 
-        If no day is provided, this defaults to the schedule for the current day.
+        If no value for `date` is provided, this defaults to the schedule for the current day.
         Menus are shown in Dutch by default, as a lot of dishes have very weird translations.
         """
         if day_dt is None:
@@ -85,11 +88,22 @@ class School(commands.Cog):
             await ctx.reply(embed=embed, mention_author=False)
 
     @commands.hybrid_command(
-        name="fiche", description="Sends the link to the study guide for [Course]", aliases=["guide", "studiefiche"]
+        name="fiche", description="Sends the link to study guides", aliases=["guide", "studiefiche"]
     )
     @app_commands.describe(course="The name of the course to fetch the study guide for (aliases work too)")
     async def study_guide(self, ctx: commands.Context, course: str, *, flags: StudyGuideFlags):
-        """Create links to study guides"""
+        """Sends the link to the study guide for `course`.
+
+        The value for `course` can contain spaces, but must be wrapped in "quotes".
+
+        Aliases (nicknames) for courses are also accepted, given that they are known and in the database.
+
+        Example usage:
+        ```
+        didier fiche ad2
+        didier fiche "algoritmen en datastructuren 2"
+        ```
+        """
         async with self.client.postgres_session as session:
             ufora_course = await ufora_courses.get_course_by_name(session, course)
 

didier/utils/types/string.py

@@ -1,6 +1,6 @@
 import math
 import re
-from typing import Optional
+from typing import Optional, Union
 
 __all__ = ["abbreviate", "leading", "pluralize", "re_find_all", "re_replace_with_list", "get_edu_year_name"]
 
@@ -46,7 +46,7 @@ def pluralize(word: str, amount: int, plural_form: Optional[str] = None) -> str:
     return plural_form or (word + "s")
 
 
-def re_find_all(pattern: str, string: str, flags: re.RegexFlag = 0) -> list[str]:
+def re_find_all(pattern: str, string: str, flags: Union[int, re.RegexFlag] = 0) -> list[str]:
     """Find all matches of a regex in a string"""
     matches = []