add comments/docstrings

Author: krittick

examples/app_commands/slash_autocomplete.py

@@ -85,19 +85,24 @@
     "yellowgreen",
 ]
 
-BASIC_ALLOWED = [123, 444, 55782]  # this would be a list of discord user IDs
+BASIC_ALLOWED = [...]  # this would normally be a list of discord user IDs for the purpose of this example
 
 
-# Simple example of using logic in a basic_autocomplete callback. In this case, we're only returning any results if the user's ID exists in the BASIC_ALLOWED list
 async def color_searcher(ctx: discord.AutocompleteContext):
+    """Returns a list of matching colors from the LOTS_OF_COLORS list
+    In this example, we've added logic to only display any results in the returned list if the user's ID exists in the BASIC_ALLOWED list.
+    This is to demonstrate passing a callback in the discord.utils.basic_autocomplete function.
+    """
     return [color for color in LOTS_OF_COLORS if ctx.interaction.user.id in BASIC_ALLOWED]
 
 
 async def get_colors(ctx: discord.AutocompleteContext):
+    """Returns a list of colors that begin with the characters entered so far."""
     return [color for color in COLORS if color.startswith(ctx.value.lower())]
 
 
 async def get_animals(ctx: discord.AutocompleteContext):
+    """Returns an animal that is (mostly) the color selected for the "color" option."""
     picked_color = ctx.options["color"]
     if picked_color == "red":
         return ["cardinal", "ladybug"]
@@ -123,15 +128,21 @@ async def autocomplete_example(
     color: Option(str, "Pick a color!", autocomplete=get_colors),
     animal: Option(str, "Pick an animal!", autocomplete=get_animals),
 ):
+    """This demonstrates using the ctx.options parameter to to create slash command options that are dependent on the values entered for other options."""
     await ctx.respond(f"You picked {color} for the color, which allowed you to choose {animal} for the animal.")
 
 
 @slash_command(name="ac_basic_example", guild_ids=[...])
 async def autocomplete_basic_example(
     ctx: discord.ApplicationContext,
-    color: Option(str, "Pick a color from this big list", autocomplete=discord.utils.basic_autocomplete(color_searcher)),
-    animal: Option(str, "Pick an animal from this small list", autocomplete=discord.utils.basic_autocomplete(["snail", "python", "cricket", "orca"])),
+    color: Option(str, "Pick a color from this big list", autocomplete=discord.utils.basic_autocomplete(color_searcher)),  # Demonstrates passing a callback to discord.utils.basic_autocomplete
+    animal: Option(str, "Pick an animal from this small list", autocomplete=discord.utils.basic_autocomplete(["snail", "python", "cricket", "orca"])),  # Demonstrates passing a static iterable discord.utils.basic_autocomplete
 ):
+    """This demonstrates using the discord.utils.basic_autocomplete helper function.
+    For the `color` option, a callback is passed, where additional logic can be added to determine which values are returned.
+    For the `animal` option, a static iterable is passed.
+    While a small amount of values for `animal` are used in this example, iterables of any length can be passed to discord.utils.basic_autocomplete
+    Note that the basic_autocomplete function itself will still only return a maximum of 25 items."""
     await ctx.respond(f"You picked {color} as your color, and {animal} as your animal!")
 
 bot.run("TOKEN")