From 066953f1ac7a99d9d532bee4d0e875e00dcf5092 Mon Sep 17 00:00:00 2001 From: bobloy Date: Tue, 8 Dec 2020 17:36:59 -0500 Subject: [PATCH] More docstrings into the `set` command --- redbot/core/core_commands.py | 113 ++++++++++++++++++++++++++++++++--- 1 file changed, 106 insertions(+), 7 deletions(-) diff --git a/redbot/core/core_commands.py b/redbot/core/core_commands.py index c7a58b18f..50c9fd590 100644 --- a/redbot/core/core_commands.py +++ b/redbot/core/core_commands.py @@ -1316,7 +1316,10 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): @commands.guild_only() @checks.is_owner() async def leave(self, ctx: commands.Context): - """Leaves the current server.""" + """Leaves the current server. + + Note: This command is interactive. + """ await ctx.send(_("Are you sure you want me to leave this server? (y/n)")) pred = MessagePredicate.yes_or_no(ctx) @@ -1660,7 +1663,12 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): @commands.command(name="shutdown") @checks.is_owner() async def _shutdown(self, ctx: commands.Context, silently: bool = False): - """Shuts down the bot.""" + """Shuts down the bot. + + Allows [botname] to shut down gracefully. + + This is the recommended method for shutting down the bot. + """ wave = "\N{WAVING HAND SIGN}" skin = "\N{EMOJI MODIFIER FITZPATRICK TYPE-3}" with contextlib.suppress(discord.HTTPException): @@ -1674,8 +1682,8 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): """Attempts to restart [botname]. Makes [botname] quit with exit code 26. - The restart is not guaranteed: it must be dealt - with by the process manager in use.""" + The restart is not guaranteed: it must be dealt with by the process manager in use. + """ with contextlib.suppress(discord.HTTPException): if not silently: await ctx.send(_("Restarting...")) @@ -1683,7 +1691,7 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): @commands.group(name="set") async def _set(self, ctx: commands.Context): - """Changes [botname]'s settings.""" + """Commands for changing [botname]'s settings.""" @_set.command("showsettings") async def set_showsettings(self, ctx: commands.Context): @@ -1755,6 +1763,15 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): Set to -1 to disable this feature. This is applied only the current server and not globally. + + Examples: + - `[p]set deletedelay` - Shows the current delete delay setting. + - `[p]set deletedelay 60` - Sets the delete delay to the max of 60 seconds. + - `[p]set deletedelay -1` - Disables deleting command messages. + + **Arguments:** + + - `[time]` The seconds to wait before deleting the command message. Use -1 to disable. """ guild = ctx.guild if time is not None: @@ -1785,7 +1802,17 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): Use without a description to reset. This is shown in a few locations, including the help menu. + The maximum description length is 250 characters to ensure it displays properly. + The default is "Red V3". + + Examples: + - `[p]set description` - Resets the description to the default setting. + - `[p]set description MyBot: A Red V3 Bot` + + **Arguments:** + + - `[time]` The seconds to wait before deleting the command message. Use -1 to disable. """ if not description: await ctx.bot._config.description.clear() @@ -1809,6 +1836,21 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): async def addadminrole(self, ctx: commands.Context, *, role: discord.Role): """ Adds an admin role for this guild. + + Admins have all the same access and Mods, plus additional admin level commands like: + - `[p]set serverprefix` + - `[p]addrole` + - `[p]ban` + - `[p]ignore guild` + And more. + + Examples: + - `[p]set addadminrole @Admins` + - `[p]set addadminrole Super Admins` + + **Arguments:** + + - `` The role to add as an admin. """ async with ctx.bot._config.guild(ctx.guild).admin_role() as roles: if role.id in roles: @@ -1821,7 +1863,21 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): @commands.guild_only() async def addmodrole(self, ctx: commands.Context, *, role: discord.Role): """ - Adds a mod role for this guild. + Adds a moderator role for this guild. + + This grants access to moderator level commands like: + - `[p]mute` + - `[p]cleanup` + - `[p]customcommand create` + And more. + + Examples: + - `[p]set addmodrole @Mods` + - `[p]set addmodrole Loyal Helpers` + + **Arguments:** + + - `` The role to add as a moderator. """ async with ctx.bot._config.guild(ctx.guild).mod_role() as roles: if role.id in roles: @@ -1835,6 +1891,14 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): async def removeadminrole(self, ctx: commands.Context, *, role: discord.Role): """ Removes an admin role for this guild. + + Examples: + - `[p]set removeadminrole @Admins` + - `[p]set removeadminrole Super Admins` + + **Arguments:** + + - `` The role to remove from being an admin. """ async with ctx.bot._config.guild(ctx.guild).admin_role() as roles: if role.id not in roles: @@ -1848,6 +1912,14 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): async def removemodrole(self, ctx: commands.Context, *, role: discord.Role): """ Removes a mod role for this guild. + + Examples: + - `[p]set removemodrole @Mods` + - `[p]set removemodrole Loyal Helpers` + + **Arguments:** + + - `` The role to remove from being a moderator. """ async with ctx.bot._config.guild(ctx.guild).mod_role() as roles: if role.id not in roles: @@ -1880,6 +1952,10 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): """ Toggle whether to enable fuzzy command search for the server. + This allows the bot to identify potential misspelled commands and offer corrections. + + Note: This can be processor intensive and may be unsuitable for larger servers. + Default is for fuzzy command search to be disabled. """ current_setting = await ctx.bot._config.guild(ctx.guild).fuzzy() @@ -1896,6 +1972,8 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): """ Toggle whether to enable fuzzy command search in DMs. + This allows the bot to identify potential misspelled commands and offer corrections. + Default is for fuzzy command search to be disabled. """ current_setting = await ctx.bot._config.fuzzy() @@ -1915,6 +1993,17 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): Acceptable values for the colour parameter can be found at: https://discordpy.readthedocs.io/en/stable/ext/commands/api.html#discord.ext.commands.ColourConverter + + Examples: + - `[p]set colour dark red` + - `[p]set colour blurple` + - `[p]set colour 0x5DADE2` + - `[p]set color 0x#FDFEFE` + - `[p]set color #7F8C8D` + + **Arguments:** + + - `[colour]` The colour to use for embeds. Leave blank to set to the default value (red). """ if colour is None: ctx.bot._color = discord.Color.red() @@ -1929,7 +2018,17 @@ class Core(commands.commands._RuleDropper, commands.Cog, CoreLogic): async def avatar(self, ctx: commands.Context, url: str = None): """Sets [botname]'s avatar - Supports either an attachment or an image URL.""" + Supports either an attachment or an image URL. + + Examples: + - `[p]set avatar` - With an image attachment, this will set the avatar. + - `[p]set avatar` - Without an attachment, this will show the command help. + - `[p]set avatar https://links.flaree.xyz/k95` - Sets the avatar to the provided url. + + **Arguments:** + + - `[url]` An image url to be used as an avatar. Leave blank when uploading an attachment. + """ if len(ctx.message.attachments) > 0: # Attachments take priority data = await ctx.message.attachments[0].read() elif url is not None: