Lots more help improvements

rocketbot/cogs/autokickcog.py

@@ -38,7 +38,7 @@ class AutoKickCog(BaseCog, name='Auto Kick'):
 		bool,
 		default_value=False,
 		brief='autokick',
-		description='Whether this cog is enabled for a guild.',
+		description='Whether this module is enabled for a guild.',
 	)
 	SETTING_BAN_COUNT = CogSetting(
 		'bancount',

rocketbot/cogs/configcog.py

@@ -32,7 +32,15 @@ class ConfigCog(BaseCog, name='Configuration'):
 		default_permissions=MOD_PERMISSIONS,
 	)
 
-	@config.command()
+	@config.command(
+		description='Sets mod warnings to post in the current channel.',
+		extras={
+			'long_description': 'Run this command in the channel where bot messages intended '
+								'for server moderators should be sent. Other bot messages may '
+								'still be posted in the channel a command was invoked in. **If '
+								'no output channel is set, mod-related messages will not be posted!**',
+		},
+	)
 	async def set_warning_channel(self, interaction: Interaction) -> None:
 		"""
 		Sets mod warnings to post in the current channel.
@@ -51,14 +59,10 @@ class ConfigCog(BaseCog, name='Configuration'):
 			ephemeral=True,
 		)
 
-	@config.command()
+	@config.command(
+		description='Shows the configured mod warning channel, if any.'
+	)
 	async def get_warning_channel(self, interaction: Interaction) -> None:
-		"""
-		Shows the mod warning channel, if any.
-
-		Shows the configured channel (if any) where mod warnings and other bot
-		output will be posted.
-		"""
 		guild: Guild = interaction.guild
 		channel_id = Storage.get_config_value(guild, ConfigKey.WARNING_CHANNEL_ID)
 		if channel_id is None:
@@ -73,22 +77,23 @@ class ConfigCog(BaseCog, name='Configuration'):
 				ephemeral=True,
 			)
 
-	@config.command()
+	@config.command(
+		description='Sets the user or role to tag in warning messages.',
+		extras={
+			'long_description': 'Calling this without a value disables tagging in warnings.',
+		}
+	)
 	async def set_warning_mention(self,
 			interaction: Interaction,
 			mention: Optional[Union[User, Role]] = None) -> None:
 		"""
 		Sets a user/role to mention in warning messages.
 
-		Configures an role or other prefix to include at the beginning of
-		warning messages. The intent is to get the attention of certain users
-		in case action is needed. Leave blank to tag no one.
-
 		Parameters
 		----------
 		interaction: Interaction
 		mention: User or Role
-			The user or role to mention in warning messages
+			the user or role to mention in warning messages
 		"""
 		guild: Guild = interaction.guild
 		Storage.set_config_value(guild, ConfigKey.WARNING_MENTION, mention.mention if mention else None)
@@ -103,11 +108,10 @@ class ConfigCog(BaseCog, name='Configuration'):
 				ephemeral=True,
 			)
 
-	@config.command()
+	@config.command(
+		description='Shows the configured user or role tagged in warning messages.',
+	)
 	async def get_warning_mention(self, interaction: Interaction) -> None:
-		"""
-		Shows the configured user/role to mention in warning messages.
-		"""
 		guild: Guild = interaction.guild
 		mention: str = Storage.get_config_value(guild, ConfigKey.WARNING_MENTION)
 		if mention is None:

rocketbot/cogs/crosspostcog.py

@@ -35,15 +35,6 @@ class CrossPostCog(BaseCog, name='Crosspost Detection'):
 	"""
 	Detects a user posting in multiple channels in a short period
 	of time: a common pattern for spammers.
-
-	These used to be identical text, but more recent attacks have had small
-	variations, such as different imgur URLs. It's reasonable to treat
-	posting in many channels in a short period as suspicious on its own,
-	regardless of whether they are identical.
-
-	Repeated posts in the same channel aren't currently detected, as this can
-	often be for a reason or due to trying a failed post when connectivity is
-	poor. Minimum message length can be enforced for detection.
 	"""
 	SETTING_ENABLED = CogSetting(
 		'enabled',
@@ -121,6 +112,18 @@ class CrossPostCog(BaseCog, name='Crosspost Detection'):
 			bot,
 			config_prefix='crosspost',
 			short_description='Manages crosspost detection and handling.',
+			long_description='Detects a user posting in multiple channels in a short period of '
+							 'time: a common pattern for spammers.\n'
+							 '\n'
+							 "These used to be identical text, but more recent attacks have had "
+							 "small variations, such as different imgur URLs. It's reasonable to "
+							 "treat posting in many channels in a short period as suspicious on its "
+							 "own, regardless of whether they are identical.\n"
+							 "\n"
+							 "Repeated posts in the same channel aren't currently detected, as "
+							 "this can often be for a reason or due to trying a failed post when "
+							 "connectivity is poor. Minimum message length can be enforced for "
+							 "detection.",
 		)
 		self.add_setting(CrossPostCog.SETTING_ENABLED)
 		self.add_setting(CrossPostCog.SETTING_WARN_COUNT)

rocketbot/cogs/generalcog.py

@@ -1,20 +1,18 @@
 """
 Cog for handling most ungrouped commands and basic behaviors.
 """
-import re
 from datetime import datetime, timedelta, timezone
-from typing import Optional, Union
+from typing import Optional
 
-from discord import Interaction, Message, User, Permissions, AppCommandType
-from discord.app_commands import Command, Group, command, default_permissions, guild_only, Transform, Choice, \
-	autocomplete
+from discord import Interaction, Message, User
+from discord.app_commands import command, default_permissions, guild_only, Transform
 from discord.errors import DiscordException
 from discord.ext.commands import Cog
 
 from config import CONFIG
 from rocketbot.bot import Rocketbot
 from rocketbot.cogs.basecog import BaseCog, BotMessage
-from rocketbot.utils import describe_timedelta, TimeDeltaTransformer, dump_stacktrace, MOD_PERMISSIONS
+from rocketbot.utils import describe_timedelta, TimeDeltaTransformer
 from rocketbot.storage import ConfigKey, Storage
 
 class GeneralCog(BaseCog, name='General'):
@@ -66,8 +64,9 @@ class GeneralCog(BaseCog, name='General'):
 	@command(
 		description='Posts a test warning.',
 		extras={
-			'long_description': 'Simulates a warning. The configured warning channel '
-								'and mod mention will be used.',
+			'long_description': 'If a warning channel is configured, it will be posted '
+								'there. If a warning role/user is configured, they will be '
+								'tagged in the message.',
 		},
 	)
 	@guild_only()
@@ -90,14 +89,13 @@ class GeneralCog(BaseCog, name='General'):
 			)
 
 	@command(
-		description='Greets the user.',
+		description='Responds to the user with a greeting.',
 		extras={
-			'long_description': 'Replies to the command message. Useful to ensure the '
-								'bot is responsive. Message is only visible to the user.',
+			'long_description': 'Useful for checking bot responsiveness. Message '
+								'is only visible to the user.',
 		},
 	)
 	async def hello(self, interaction: Interaction):
-		"""Command handler"""
 		await interaction.response.send_message(
 			f'Hey, {interaction.user.name}!',
 		 	ephemeral=True,
@@ -106,8 +104,8 @@ class GeneralCog(BaseCog, name='General'):
 	@command(
 		description='Shuts down the bot.',
 		extras={
-			'long_description': 'Terminates the bot script. Only usable by a '
-								'server administrator.',
+			'long_description': 'For emergency use if the bot gains sentience. Only usable '
+								'by a server administrator.',
 		},
 	)
 	@guild_only()
@@ -118,32 +116,32 @@ class GeneralCog(BaseCog, name='General'):
 		await self.bot.close()
 
 	@command(
-		description='Mass deletes messages.',
+		description='Mass deletes recent messages by a user.',
 		extras={
-			'long_description': 'Deletes recent messages by the given user. The user ' +
-				'can be either an @ mention or a numeric user ID. The age is ' +
-				'a duration, such as "30s", "5m", "1h30m". Only the most ' +
-				'recent 100 messages in each channel are searched.',
+			'long_description': 'The age is a duration, such as "30s", "5m", "1h30m", "7d". '
+								'Only the most recent 100 messages in each channel are searched.\n\n'
+								"The author can be a numeric ID if they aren't showing up in autocomplete.",
 			'usage': '<user:id|mention> <age:timespan>',
 		},
 	)
 	@guild_only()
 	@default_permissions(manage_messages=True)
-	async def delete_messages(self, interaction: Interaction, user: User, age: Transform[timedelta, TimeDeltaTransformer]) -> None:
+	async def delete_messages(self, interaction: Interaction, author: User, age: Transform[timedelta, TimeDeltaTransformer]) -> None:
 		"""
 		Mass deletes messages.
 
 		Parameters
 		----------
 		interaction: :class:`Interaction`
-		user: :class:`User`
-			user to delete messages from
+		author: :class:`User`
+			author of messages to delete
 		age: :class:`timedelta`
-			maximum age of messages to delete
+			maximum age of messages to delete (e.g. 30s, 5m, 1h30s, 7d)
 		"""
-		member_id = user.id
+		member_id = author.id
 		cutoff: datetime = datetime.now(timezone.utc) - age
 
+		# Finding and deleting messages takes time but interaction needs a timely acknowledgement.
 		resp = await interaction.response.defer(ephemeral=True, thinking=True)
 
 		def predicate(message: Message) -> bool:
@@ -159,10 +157,10 @@ class GeneralCog(BaseCog, name='General'):
 		if len(deleted_messages) > 0:
 			await resp.resource.edit(
 				content=f'{CONFIG["success_emoji"]} Deleted {len(deleted_messages)} '
-						f'messages by {user.mention} from the past {describe_timedelta(age)}.',
+						f'messages by {author.mention} from the past {describe_timedelta(age)}.',
 			)
 		else:
 			await resp.resource.edit(
-				content=f'{CONFIG["success_emoji"]} No messages found for {user.mention} '
+				content=f'{CONFIG["success_emoji"]} No messages found for {author.mention} '
 						'from the past {describe_timedelta(age)}.',
 			)

rocketbot/cogs/helpcog.py

@@ -4,7 +4,6 @@ from typing import Union, Optional
 
 from discord import Interaction, Permissions, AppCommandType
 from discord.app_commands import Group, Command, autocomplete, guild_only, command, Choice
-from discord.ext.commands import cog
 
 from config import CONFIG
 from rocketbot.bot import Rocketbot
@@ -13,99 +12,29 @@ from rocketbot.utils import MOD_PERMISSIONS, dump_stacktrace
 
 HelpTopic = Union[Command, Group, BaseCog]
 
-def choice_from_obj(obj: HelpTopic, include_full_command: bool = False) -> Choice:
-	if isinstance(obj, BaseCog):
-		return Choice(name=f'⚙ {obj.qualified_name}', value=f'cog:{obj.qualified_name}')
-	if isinstance(obj, Group):
-		return Choice(name=f'/{obj.name}', value=f'cmd:{obj.name}')
-	if isinstance(obj, Command):
-		if obj.parent:
+def choice_from_topic(topic: HelpTopic, include_full_command: bool = False) -> Choice:
+	if isinstance(topic, BaseCog):
+		return Choice(name=f'⚙ {topic.qualified_name}', value=f'cog:{topic.qualified_name}')
+	if isinstance(topic, Group):
+		return Choice(name=f'/{topic.name}', value=f'cmd:{topic.name}')
+	if isinstance(topic, Command):
+		if topic.parent:
 			if include_full_command:
-				return Choice(name=f'/{obj.parent.name} {obj.name}', value=f'subcmd:{obj.parent.name}.{obj.name}')
-			return Choice(name=f'{obj.name}', value=f'subcmd:{obj.name}')
-		return Choice(name=f'/{obj.name}', value=f'cmd:{obj.name}')
+				return Choice(name=f'/{topic.parent.name} {topic.name}', value=f'subcmd:{topic.parent.name}.{topic.name}')
+			return Choice(name=f'{topic.name}', value=f'subcmd:{topic.name}')
+		return Choice(name=f'/{topic.name}', value=f'cmd:{topic.name}')
 	return Choice(name='', value='')
 
-async def command_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
-	"""Autocomplete handler for top-level command names."""
-	choices: list[Choice] = []
-	try:
-		if current.startswith('/'):
-			current = current[1:]
-		current = current.lower().strip()
-		user_permissions = interaction.permissions
-		cmds = HelpCog.shared.get_command_list(user_permissions)
-		return [
-			Choice(name=f'/{cmdname} command', value=f'cmd:{cmdname}')
-			for cmdname in sorted(cmds.keys())
-			if len(current) == 0 or current in cmdname
-		][:25]
-	except BaseException as e:
-		dump_stacktrace(e)
-	return choices
-
-async def subcommand_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
-	"""Autocomplete handler for subcommand names. Command taken from previous command token."""
-	try:
-		current = current.lower().strip()
-		cmd_name = interaction.namespace.get('topic', None)
-		cmd = HelpCog.shared.object_for_help_symbol(cmd_name)
-		if isinstance(cmd, Command):
-			# No subcommands
-			return []
-		user_permissions = interaction.permissions
-		if cmd is None or not isinstance(cmd, Group):
-			return []
-		grp = cmd
-		subcmds = HelpCog.shared.get_subcommand_list(grp, user_permissions)
-		if subcmds is None:
-			return []
-		return [
-			choice_from_obj(subcmd)
-			for subcmd_name, subcmd in sorted(subcmds.items())
-			if len(current) == 0 or current in subcmd_name
-		][:25]
-	except BaseException as e:
-		dump_stacktrace(e)
-	return []
-
-async def cog_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
-	"""Autocomplete handler for cog names."""
-	try:
-		current = current.lower().strip()
-		return [
-			choice_from_obj(cog)
-			for cog in sorted(HelpCog.shared.bot.cogs.values(), key=lambda c: c.qualified_name)
-			if isinstance(cog, BaseCog) and
-			   can_use_cog(cog, interaction.permissions) and
-			   (len(cog.get_commands()) > 0 or len(cog.settings) > 0) and \
-			   (len(current) == 0 or current in cog.qualified_name.lower())
-		]
-	except BaseException as e:
-		dump_stacktrace(e)
-	return []
-
-async def topic_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
-	"""Autocomplete handler that combines slash commands and cog names."""
-	command_choices = await command_autocomplete(interaction, current)
-	cog_choices = await cog_autocomplete(interaction, current)
-	return (command_choices + cog_choices)[:25]
-
-async def subtopic_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
-	"""Autocomplete handler for subtopic names. Currently just handles subcommands."""
-	subcommand_choices = await subcommand_autocomplete(interaction, current)
-	return subcommand_choices[:25]
-
 async def search_autocomplete(interaction: Interaction, current: str) -> list[Choice[str]]:
 	try:
 		if len(current) == 0:
 			return [
-				choice_from_obj(obj, include_full_command=True)
-				for obj in HelpCog.shared.all_accessible_objects(interaction.permissions)
+				choice_from_topic(topic, include_full_command=True)
+				for topic in HelpCog.shared.all_accessible_topics(interaction.permissions)
 			]
 		return [
-			choice_from_obj(obj, include_full_command=True)
-			for obj in HelpCog.shared.objects_for_keywords(current, interaction.permissions)
+			choice_from_topic(topic, include_full_command=True)
+			for topic in HelpCog.shared.topics_for_keywords(current, interaction.permissions)
 		]
 	except BaseException as e:
 		dump_stacktrace(e)
@@ -118,22 +47,22 @@ class HelpCog(BaseCog, name='Help'):
 		super().__init__(
 			bot,
 			config_prefix='help',
-			short_description='Provides help on using commands and modules.'
+			short_description='Provides help on using this bot.'
 		)
 		HelpCog.shared = self
 
 	def __create_help_index(self) -> None:
 		"""
-		Populates self.obj_index and self.keyword_index. Bails if already
+		Populates self.topic_index and self.keyword_index. Bails if already
 		populated. Intended to be run on demand so all cogs and commands have
 		had time to get set up and synced.
 		"""
-		if getattr(self, 'obj_index', None) is not None:
+		if getattr(self, 'topic_index', None) is not None:
 			return
-		self.obj_index: dict[str, HelpTopic] = {}
+		self.topic_index: dict[str, HelpTopic] = {}
 		self.keyword_index: dict[str, set[HelpTopic]] = {}
 
-		def add_text_to_index(obj, text: str):
+		def add_text_to_index(topic: HelpTopic, text: str):
 			words = [
 				word
 				for word in re.split(r"[^a-zA-Z']+", text.lower())
@@ -141,20 +70,20 @@ class HelpCog(BaseCog, name='Help'):
 			]
 			for word in words:
 				matches = self.keyword_index.get(word, set())
-				matches.add(obj)
+				matches.add(topic)
 				self.keyword_index[word] = matches
 
 		cmds = self.all_commands()
 		for cmd in cmds:
-			self.obj_index[f'cmd:{cmd.name}'] = cmd
-			self.obj_index[f'/{cmd.name}'] = cmd
+			self.topic_index[f'cmd:{cmd.name}'] = cmd
+			self.topic_index[f'/{cmd.name}'] = cmd
 			add_text_to_index(cmd, cmd.name)
 			if cmd.description:
 				add_text_to_index(cmd, cmd.description)
 			if isinstance(cmd, Group):
 				for subcmd in cmd.commands:
-					self.obj_index[f'subcmd:{cmd.name}.{subcmd.name}'] = subcmd
-					self.obj_index[f'/{cmd.name} {subcmd.name}'] = subcmd
+					self.topic_index[f'subcmd:{cmd.name}.{subcmd.name}'] = subcmd
+					self.topic_index[f'/{cmd.name} {subcmd.name}'] = subcmd
 					add_text_to_index(subcmd, cmd.name)
 					add_text_to_index(subcmd, subcmd.name)
 					if subcmd.description:
@@ -163,14 +92,14 @@ class HelpCog(BaseCog, name='Help'):
 			if not isinstance(cog, BaseCog):
 				continue
 			key = f'cog:{cog_qname}'
-			self.obj_index[key] = cog
+			self.topic_index[key] = cog
 			add_text_to_index(cog, cog.qualified_name)
 			if cog.description:
 				add_text_to_index(cog, cog.description)
 
-	def object_for_help_symbol(self, symbol: str) -> Optional[HelpTopic]:
+	def topic_for_help_symbol(self, symbol: str) -> Optional[HelpTopic]:
 		self.__create_help_index()
-		return self.obj_index.get(symbol, None)
+		return self.topic_index.get(symbol, None)
 
 	def all_commands(self) -> list[Union[Command, Group]]:
 		# PyCharm not interpreting conditional return type correctly.
@@ -202,20 +131,20 @@ class HelpCog(BaseCog, name='Help'):
 			if can_use_cog(cog, permissions)
 		]
 
-	def all_accessible_objects(self, permissions: Optional[Permissions], *,
-							   include_cogs: bool = True,
-							   include_commands: bool = True,
-							   include_subcommands: bool = True) -> list[HelpTopic]:
-		objs = []
+	def all_accessible_topics(self, permissions: Optional[Permissions], *,
+							  include_cogs: bool = True,
+							  include_commands: bool = True,
+							  include_subcommands: bool = True) -> list[HelpTopic]:
+		topics = []
 		if include_cogs:
-			objs += self.all_accessible_cogs(permissions)
+			topics += self.all_accessible_cogs(permissions)
 		if include_commands:
-			objs += self.all_accessible_commands(permissions)
+			topics += self.all_accessible_commands(permissions)
 		if include_subcommands:
-			objs += self.all_accessible_subcommands(permissions)
-		return objs
+			topics += self.all_accessible_subcommands(permissions)
+		return topics
 
-	def objects_for_keywords(self, search: str, permissions: Optional[Permissions]) -> list[HelpTopic]:
+	def topics_for_keywords(self, search: str, permissions: Optional[Permissions]) -> list[HelpTopic]:
 		self.__create_help_index()
 
 		# Break into words (or word fragments)
@@ -229,53 +158,55 @@ class HelpCog(BaseCog, name='Help'):
 		# to known indexed keywords, then collecting those associated results. Should
 		# just keep corpuses of searchable, normalized text for each topic and do a
 		# direct `in` test.
-		matching_objects_set = None
+		matching_topics_set = None
 		for word in words:
 			word_matches = set()
 			for k in self.keyword_index.keys():
 				if word in k:
-					objs = self.keyword_index.get(k, None)
-					if objs is not None:
-						word_matches.update(objs)
-			if matching_objects_set is None:
-				matching_objects_set = word_matches
+					topics = self.keyword_index.get(k, None)
+					if topics is not None:
+						word_matches.update(topics)
+			if matching_topics_set is None:
+				matching_topics_set = word_matches
 			else:
-				matching_objects_set = matching_objects_set & word_matches
+				matching_topics_set = matching_topics_set & word_matches
 
 		# Filter by accessibility
-		accessible_objects = [
-			obj
-			for obj in matching_objects_set or {}
-			if ((isinstance(obj, Command) or isinstance(obj, Group)) and can_use_command(obj, permissions)) or \
-			   (isinstance(obj, BaseCog) and can_use_cog(obj, permissions))
+		accessible_topics = [
+			topic
+			for topic in matching_topics_set or {}
+			if ((isinstance(topic, Command) or isinstance(topic, Group)) and can_use_command(topic, permissions)) or \
+			   (isinstance(topic, BaseCog) and can_use_cog(topic, permissions))
 		]
 
 		# Sort and return
-		return sorted(accessible_objects, key=lambda obj: (
-			isinstance(obj, Command),
-			isinstance(obj, BaseCog),
-			obj.qualified_name if isinstance(obj, BaseCog) else obj.name
+		return sorted(accessible_topics, key=lambda topic: (
+			isinstance(topic, Command),
+			isinstance(topic, BaseCog),
+			topic.qualified_name if isinstance(topic, BaseCog) else topic.name
 		))
 
-	@command(name='help')
+	@command(
+		name='help',
+		description='Shows help for using commands and module configuration.',
+		extras={
+			'long_description': '`/help` will show a list of top-level topics.\n'
+								'\n'
+								"`/help /<command_name>` will show help about a specific command or list a command's subcommands.\n"
+								'\n'
+								'`/help /<command_name> <subcommand_name>` will show help about a specific subcommand.\n'
+								'\n'
+								'`/help <module_name>` will show help about configuring a module.\n'
+								'\n'
+								'`/help <keywords>` will do a text search for topics.',
+		}
+	)
 	@guild_only()
 	@autocomplete(search=search_autocomplete)
 	async def help_command(self, interaction: Interaction, search: Optional[str]) -> None:
 		"""
 		Shows help for using commands and subcommands and configuring modules.
 
-		`/help` will show a list of top-level topics.
-
-		`/help /<command_name>` will show help about a specific command or
-		list a command's subcommands.
-
-		`/help /<command_name> <subcommand_name>` will show help about a
-		specific subcommand.
-
-		`/help <module_name>` will show help about configuring a module.
-
-		`/help <keywords>` will do a text search for topics.
-
 		Parameters
 		----------
 		interaction: Interaction
@@ -285,27 +216,24 @@ class HelpCog(BaseCog, name='Help'):
 		if search is None:
 			await self.__send_general_help(interaction)
 			return
-		obj = self.object_for_help_symbol(search)
-		if obj:
-			await self.__send_object_help(interaction, obj)
+		topic = self.topic_for_help_symbol(search)
+		if topic:
+			await self.__send_topic_help(interaction, topic)
 			return
-		matches = self.objects_for_keywords(search, interaction.permissions)
+		matches = self.topics_for_keywords(search, interaction.permissions)
 		await self.__send_keyword_help(interaction, matches)
 
-	async def __send_object_help(self, interaction: Interaction, obj: HelpTopic) -> None:
-		if isinstance(obj, Command):
-			if obj.parent:
-				await self.__send_subcommand_help(interaction, obj.parent, obj)
-			else:
-				await self.__send_command_help(interaction, obj)
+	async def __send_topic_help(self, interaction: Interaction, topic: HelpTopic) -> None:
+		if isinstance(topic, Command):
+			await self.__send_command_help(interaction, topic)
 			return
-		if isinstance(obj, Group):
-			await self.__send_command_help(interaction, obj)
+		if isinstance(topic, Group):
+			await self.__send_command_help(interaction, topic)
 			return
-		if isinstance(obj, BaseCog):
-			await self.__send_cog_help(interaction, obj)
+		if isinstance(topic, BaseCog):
+			await self.__send_cog_help(interaction, topic)
 			return
-		self.log(interaction.guild, f'No help for object {obj}')
+		self.log(interaction.guild, f'No help for topic object {topic}')
 		await interaction.response.send_message(
 			f'{CONFIG["failure_emoji"]} Failed to get help info.',
 			ephemeral=True,
@@ -361,15 +289,15 @@ class HelpCog(BaseCog, name='Help'):
 			ephemeral=True,
 		)
 
-	async def __send_keyword_help(self, interaction: Interaction, matching_objects: Optional[list[HelpTopic]]) -> None:
+	async def __send_keyword_help(self, interaction: Interaction, matching_topics: Optional[list[HelpTopic]]) -> None:
 		matching_commands = [
 			cmd
-			for cmd in matching_objects or []
+			for cmd in matching_topics or []
 			if isinstance(cmd, Command) or isinstance(cmd, Group)
 		]
 		matching_cogs = [
 			cog
-			for cog in matching_objects or []
+			for cog in matching_topics or []
 			if isinstance(cog, BaseCog)
 		]
 		if len(matching_commands) + len(matching_cogs) == 0:
@@ -379,9 +307,9 @@ class HelpCog(BaseCog, name='Help'):
 				delete_after=10,
 			)
 			return
-		if len(matching_objects) == 1:
-			obj = matching_objects[0]
-			await self.__send_object_help(interaction, obj)
+		if len(matching_topics) == 1:
+			topic = matching_topics[0]
+			await self.__send_topic_help(interaction, topic)
 			return
 
 		text = '## :information_source: Matching Help Topics'
@@ -393,7 +321,7 @@ class HelpCog(BaseCog, name='Help'):
 				else:
 					text += f'\n- `/{cmd.name}`'
 		if len(matching_cogs) > 0:
-			text += '\n### Cogs'
+			text += '\n### Modules'
 			for cog in matching_cogs:
 				text += f'\n- {cog.qualified_name}'
 		await interaction.response.send_message(
@@ -405,37 +333,53 @@ class HelpCog(BaseCog, name='Help'):
 		text = ''
 		if addendum is not None:
 			text += addendum + '\n\n'
-		text += f'## :information_source: Command Help\n`/{command_or_group.name}`\n\n{command_or_group.description}'
+		if command_or_group.parent:
+			text += f'## :information_source: Subcommand Help'
+			text += f'\n`/{command_or_group.parent.name} {command_or_group.name}`'
+		else:
+			text += f'## :information_source: Command Help'
+			if isinstance(command_or_group, Group):
+				text += f'\n`/{command_or_group.name} subcommand_name`'
+			else:
+				text += f'\n`/{command_or_group.name}`'
+		if isinstance(command_or_group, Command):
+			optional_nesting = 0
+			for param in command_or_group.parameters:
+				text += '  '
+				if not param.required:
+					text += '['
+					optional_nesting += 1
+				text += f'_{param.name}_'
+			if optional_nesting > 0:
+				text += ']' * optional_nesting
+		text += f'\n\n{command_or_group.description}'
+		if command_or_group.extras.get('long_description'):
+			text += f'\n\n{command_or_group.extras["long_description"]}'
 		if isinstance(command_or_group, Group):
 			subcmds: dict[str, Command] = self.get_subcommand_list(command_or_group, permissions=interaction.permissions)
 			if len(subcmds) > 0:
 				text += '\n### Subcommands:'
 				for subcmd_name, subcmd in sorted(subcmds.items()):
 					text += f'\n- `{subcmd_name}`: {subcmd.description}'
+				text += f'\n-# To use a subcommand, type it after the command. e.g. `/{command_or_group.name} subcommand_name`'
+				text += f'\n-# Get help on a subcommand by typing `/help /{command_or_group.name} subcommand_name`'
 		else:
 			params = command_or_group.parameters
 			if len(params) > 0:
 				text += '\n### Parameters:'
 				for param in params:
 					text += f'\n- `{param.name}`: {param.description}'
-		await interaction.response.send_message(text, ephemeral=True)
-
-	async def __send_subcommand_help(self, interaction: Interaction, group: Group, subcommand: Command) -> None:
-		text = f'## :information_source: Subcommand Help'
-		text += f'\n`/{group.name} {subcommand.name}`'
-		text += f'\n\n{subcommand.description}'
-		params = subcommand.parameters
-		if len(params) > 0:
-			text += '\n### Parameters:'
-			for param in params:
-				text += f'\n- `{param.name}`: {param.description}'
+					if not param.required:
+						text += ' (optional)'
 		await interaction.response.send_message(text, ephemeral=True)
 
 	async def __send_cog_help(self, interaction: Interaction, cog: BaseCog) -> None:
 		text = f'## :information_source: Module Help'
 		text += f'\n**{cog.qualified_name}** module'
-		if cog.description is not None:
-			text += f'\n\n{cog.description}'
+		if cog.short_description is not None:
+			text += f'\n\n{cog.short_description}'
+		if cog.long_description is not None:
+			text += f'\n\n{cog.long_description}'
 
 		cmds = [
 			cmd

rocketbot/cogs/joinraidcog.py

@@ -34,7 +34,7 @@ class JoinRaidCog(BaseCog, name='Join Raids'):
 		bool,
 		default_value=False,
 		brief='join raid detection',
-		description='Whether this cog is enabled for a guild.',
+		description='Whether this module is enabled for a guild.',
 	)
 	SETTING_JOIN_COUNT = CogSetting(
 		'joincount',
@@ -65,6 +65,9 @@ class JoinRaidCog(BaseCog, name='Join Raids'):
 			bot,
 			config_prefix='joinraid',
 			short_description='Manages join raid detection and handling.',
+			long_description='Join raids consist of an unusual number of users joining in '
+							 'a short period of time and have shown a pattern of DMing '
+							 'members with spam or scams.'
 		)
 		self.add_setting(JoinRaidCog.SETTING_ENABLED)
 		self.add_setting(JoinRaidCog.SETTING_JOIN_COUNT)

rocketbot/cogs/logcog.py

@@ -43,7 +43,7 @@ class LoggingCog(BaseCog, name='Logging'):
 		bool,
 		default_value=False,
 		brief='logging',
-		description='Whether this cog is enabled for a guild.',
+		description='Whether this module is enabled for a guild.',
 	)
 
 	STATE_EVENT_BUFFER = 'LoggingCog.eventBuffer'

rocketbot/cogs/patterncog.py

@@ -100,6 +100,7 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 			bot,
 			config_prefix='patterns',
 			short_description='Manages message pattern matching.',
+			long_description='Patterns are a powerful but complex topic. See <https://git.rixafrix.com/ialbert/python-app-rocketbot/src/branch/main/docs/patterns.md> for full documentation.'
 		)
 		PatternCog.shared = self
 
@@ -262,10 +263,20 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 		description='Manages message pattern matching.',
 		guild_only=True,
 		default_permissions=MOD_PERMISSIONS,
+		extras={
+			'long_description': 'Patterns are a powerful but complex topic. '
+								'See <https://git.rixafrix.com/ialbert/python-app-rocketbot/src/branch/main/docs/patterns.md> for full documentation.'
+		},
 	)
 
-	@pattern.command()
-	@rename(expression='if')
+	@pattern.command(
+		description='Adds or updates a custom pattern.',
+		extras={
+			'long_description': 'Patterns use a simplified expression language. Full '
+								'documentation found here: '
+								'<https://git.rixafrix.com/ialbert/python-app-rocketbot/src/branch/main/docs/patterns.md>',
+		},
+	)
 	@autocomplete(
 		name=pattern_name_autocomplete,
 		# actions=action_autocomplete
@@ -280,19 +291,15 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 		"""
 		Adds a custom pattern.
 
-		Adds a custom pattern. Patterns use a simplified
-		expression language. Full documentation found here:
-		https://git.rixafrix.com/ialbert/python-app-rocketbot/src/branch/main/docs/patterns.md
-
 		Parameters
 		----------
 		interaction : Interaction
 		name : str
-			A name for the pattern.
+			a name for the new or existing pattern
 		actions : str
-			One or more actions to take when a message matches the expression.
+			actions to take when a message matches
 		expression : str
-			Criteria for matching chat messages.
+			criteria for matching chat messages
 		"""
 		pattern_str = f'{actions} if {expression}'
 		guild = interaction.guild
@@ -313,7 +320,7 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 			)
 
 	@pattern.command(
-		description='Removes a custom pattern',
+		description='Removes a custom pattern.',
 		extras={
 			'usage': '<pattern_name>',
 		},
@@ -321,13 +328,13 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 	@autocomplete(name=pattern_name_autocomplete)
 	async def remove(self, interaction: Interaction, name: str):
 		"""
-		Command handler
+		Removes a custom pattern.
 
 		Parameters
 		----------
 		interaction: Interaction
 		name: str
-			Name of the pattern to remove.
+			name of the pattern to remove
 		"""
 		guild = interaction.guild
 		patterns = self.get_patterns(guild)
@@ -345,16 +352,9 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 			)
 
 	@pattern.command(
-		description='Lists all patterns',
+		description='Lists all patterns.',
 	)
 	async def list(self, interaction: Interaction) -> None:
-		"""
-		Command handler
-
-		Parameters
-		----------
-		interaction: Interaction
-		"""
 		guild = interaction.guild
 		patterns = self.get_patterns(guild)
 		if len(patterns) == 0:
@@ -369,26 +369,26 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 		await interaction.response.send_message(msg, ephemeral=True)
 
 	@pattern.command(
-		description='Sets a pattern\'s priority level',
+		description="Sets a pattern's priority level.",
 		extras={
-			'long_description': 'Sets the priority for a pattern. Messages are checked ' +
-				'against patterns with the highest priority first. Patterns with ' +
-				'the same priority may be checked in arbitrary order. Default ' +
-				'priority is 100.',
+			'long_description': 'Messages are checked against patterns with the '
+								'highest priority first. Patterns with the same '
+								'priority may be checked in arbitrary order. Default '
+								'priority is 100.',
 		},
 	)
 	@autocomplete(name=pattern_name_autocomplete, priority=priority_autocomplete)
 	async def setpriority(self, interaction: Interaction, name: str, priority: int) -> None:
 		"""
-		Command handler
+		Sets a pattern's priority level.
 
 		Parameters
 		----------
 		interaction: Interaction
 		name: str
-			A name for the pattern
+			the name of the pattern
 		priority: int
-			Priority for evaluating the pattern. Default is 100. Higher values match first.
+			evaluation priority
 		"""
 		guild = interaction.guild
 		patterns = self.get_patterns(guild)

rocketbot/cogs/usernamecog.py

@@ -52,7 +52,7 @@ class UsernamePatternCog(BaseCog, name='Username Pattern'):
 		bool,
 		default_value=False,
 		brief='username pattern detection',
-		description='Whether new users are checked for common patterns.',
+		description='Whether new users are checked for username patterns.',
 	)
 
 	SETTING_PATTERNS = CogSetting('patterns', None, default_value=None)
@@ -62,6 +62,8 @@ class UsernamePatternCog(BaseCog, name='Username Pattern'):
 			bot,
 			config_prefix='username',
 			short_description='Manages username pattern detection.',
+			long_description='When new users join, if their username matches '
+							 'a configured pattern the mods will be alerted.'
 		)
 		self.add_setting(UsernamePatternCog.SETTING_ENABLED)
 
@@ -89,12 +91,18 @@ class UsernamePatternCog(BaseCog, name='Username Pattern'):
 		description='Manages username pattern detection.',
 		guild_only=True,
 		default_permissions=MOD_PERMISSIONS,
+		extras={
+			'long_description': 'When new users join, if their username matches '
+								'a configured pattern the mods will be alerted.',
+		},
 	)
 
 	@username.command(
-		description='Adds a username pattern to match against new members.',
+		description='Adds a username pattern.',
 		extras={
-			'long_description': 'Adds a username pattern.',
+			'long_description': 'When a user joins the server, if their username '
+								'matches a configured pattern the mods will be alerted. '
+								'Matching is currently a simple substring test.',
 			'usage': '<pattern>',
 		},
 	)
@@ -126,7 +134,6 @@ class UsernamePatternCog(BaseCog, name='Username Pattern'):
 	@username.command(
 		description='Removes a username pattern.',
 		extras={
-			'long_description': 'Removes an existing username pattern',
 			'usage': '<pattern>',
 		},
 	)

rocketbot/cogsetting.py

@@ -197,7 +197,7 @@ class CogSetting:
 			cog.log(interaction.guild, f'{interaction.user.name} set {key} to {new_value}')
 
 		setter: CommandCallback = setter_general
-		if self.datatype == int:
+		if self.datatype is int:
 			if self.min_value is not None or self.max_value is not None:
 				r_min = self.min_value
 				r_max = self.max_value
@@ -212,15 +212,15 @@ class CogSetting:
 				async def setter_int(interaction: Interaction, new_value: int) -> None:
 					await setter_general(interaction, new_value)
 				setter = setter_int
-		elif self.datatype == float:
+		elif self.datatype is float:
 			@rename(new_value=self.name)
 			@describe(new_value=self.brief)
 			async def setter_float(interaction: Interaction, new_value: float) -> None:
 				await setter_general(interaction, new_value)
 			setter = setter_float
-		elif self.datatype == timedelta:
+		elif self.datatype is timedelta:
 			@rename(new_value=self.name)
-			@describe(new_value=f'{self.brief} (e.g. 30s, 5m, 1h30s, or 7d)')
+			@describe(new_value=f'{self.brief} (e.g. 30s, 5m, 1h30s, 7d)')
 			async def setter_timedelta(interaction: Interaction, new_value: Transform[timedelta, TimeDeltaTransformer]) -> None:
 				await setter_general(interaction, new_value)
 			setter = setter_timedelta
@@ -231,7 +231,7 @@ class CogSetting:
 			async def setter_enum(interaction: Interaction, new_value: dt) -> None:
 				await setter_general(interaction, new_value)
 			setter = setter_enum
-		elif self.datatype == str:
+		elif self.datatype is str:
 			if self.enum_values is not None:
 				raise ValueError('Type for a setting with enum values should be typing.Literal')
 			else:
@@ -240,7 +240,7 @@ class CogSetting:
 				async def setter_str(interaction: Interaction, new_value: str) -> None:
 					await setter_general(interaction, new_value)
 				setter = setter_str
-		elif self.datatype == bool:
+		elif self.datatype is bool:
 			@rename(new_value=self.name)
 			@describe(new_value=self.brief)
 			async def setter_bool(interaction: Interaction, new_value: bool) -> None:
@@ -351,13 +351,13 @@ class CogSetting:
 			description='Shows a configuration value for this guild.',
 			default_permissions=MOD_PERMISSIONS,
 			extras={
-				'long_description': 'Settings are guild-specific. Shows the configured value or default value for a '
-									'variable for this guild. Use `/set` to change the value.',
+				'long_description': 'Settings are guild-specific. If no value is set, a default is used. Use `/set` to '
+									'change the value.',
 			},
 		)
 		cls.__enable_group = Group(
 			name='enable',
-			description='Enables a module for this guild',
+			description='Enables a module for this guild.',
 			default_permissions=MOD_PERMISSIONS,
 			extras={
 				'long_description': 'Modules are enabled on a per-guild basis and are off by default. Use `/disable` '