Add Docstring to Enum for Option descriptions, issue 1510 (#1699)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: BobDotCom <[email protected]>
Co-authored-by: Lala Sabathil <[email protected]>

Author: 4 people

discord/commands/options.py

@@ -178,7 +178,8 @@ def __init__(
         enum_choices = []
         input_type_is_class = isinstance(input_type, type)
         if input_type_is_class and issubclass(input_type, (Enum, DiscordEnum)):
-            description = inspect.getdoc(input_type)
+            if description is None:
+                description = inspect.getdoc(input_type)
             enum_choices = [OptionChoice(e.name, e.value) for e in input_type]
             value_class = enum_choices[0].value.__class__
             if all(isinstance(elem.value, value_class) for elem in enum_choices):

discord/enums.py

@@ -210,6 +210,8 @@ def try_value(cls, value):
 
 
 class ChannelType(Enum):
+    """Channel type"""
+
     text = 0
     private = 1
     voice = 2
@@ -228,6 +230,8 @@ def __str__(self):
 
 
 class MessageType(Enum):
+    """Message type"""
+
     default = 0
     recipient_add = 1
     recipient_remove = 2
@@ -256,6 +260,8 @@ class MessageType(Enum):
 
 
 class VoiceRegion(Enum):
+    """Voice region"""
+
     us_west = "us-west"
     us_east = "us-east"
     us_south = "us-south"
@@ -285,6 +291,8 @@ def __str__(self):
 
 
 class SpeakingState(Enum):
+    """Speaking state"""
+
     none = 0
     voice = 1
     soundshare = 2
@@ -298,6 +306,8 @@ def __int__(self):
 
 
 class VerificationLevel(Enum, comparable=True):
+    """Verification level"""
+
     none = 0
     low = 1
     medium = 2
@@ -309,6 +319,8 @@ def __str__(self):
 
 
 class ContentFilter(Enum, comparable=True):
+    """Content Filter"""
+
     disabled = 0
     no_role = 1
     all_members = 2
@@ -318,6 +330,8 @@ def __str__(self):
 
 
 class Status(Enum):
+    """Status"""
+
     online = "online"
     offline = "offline"
     idle = "idle"
@@ -331,6 +345,8 @@ def __str__(self):
 
 
 class DefaultAvatar(Enum):
+    """Default avatar"""
+
     blurple = 0
     grey = 1
     gray = 1
@@ -343,17 +359,23 @@ def __str__(self):
 
 
 class NotificationLevel(Enum, comparable=True):
+    """Notification level"""
+
     all_messages = 0
     only_mentions = 1
 
 
 class AuditLogActionCategory(Enum):
+    """Audit log action category"""
+
     create = 1
     delete = 2
     update = 3
 
 
 class AuditLogAction(Enum):
+    """Audit log action"""
+
     guild_update = 1
     channel_create = 10
     channel_update = 11
@@ -505,6 +527,8 @@ def target_type(self) -> Optional[str]:
 
 
 class UserFlags(Enum):
+    """User flags"""
+
     staff = 1
     partner = 2
     hypesquad = 4
@@ -529,6 +553,8 @@ class UserFlags(Enum):
 
 
 class ActivityType(Enum):
+    """Activity type"""
+
     unknown = -1
     playing = 0
     streaming = 1
@@ -542,17 +568,23 @@ def __int__(self):
 
 
 class TeamMembershipState(Enum):
+    """Team membership state"""
+
     invited = 1
     accepted = 2
 
 
 class WebhookType(Enum):
+    """Webhook Type"""
+
     incoming = 1
     channel_follower = 2
     application = 3
 
 
 class ExpireBehaviour(Enum):
+    """Expire Behaviour"""
+
     remove_role = 0
     kick = 1
 
@@ -561,11 +593,15 @@ class ExpireBehaviour(Enum):
 
 
 class StickerType(Enum):
+    """Sticker type"""
+
     standard = 1
     guild = 2
 
 
 class StickerFormatType(Enum):
+    """Sticker format Type"""
+
     png = 1
     apng = 2
     lottie = 3
@@ -581,12 +617,16 @@ def file_extension(self) -> str:
 
 
 class InviteTarget(Enum):
+    """Invite target"""
+
     unknown = 0
     stream = 1
     embedded_application = 2
 
 
 class InteractionType(Enum):
+    """Interaction type"""
+
     ping = 1
     application_command = 2
     component = 3
@@ -595,6 +635,8 @@ class InteractionType(Enum):
 
 
 class InteractionResponseType(Enum):
+    """Interaction response type"""
+
     pong = 1
     # ack = 2 (deprecated)
     # channel_message = 3 (deprecated)
@@ -607,6 +649,8 @@ class InteractionResponseType(Enum):
 
 
 class VideoQualityMode(Enum):
+    """Video quality mode"""
+
     auto = 1
     full = 2
 
@@ -615,6 +659,8 @@ def __int__(self):
 
 
 class ComponentType(Enum):
+    """Component type"""
+
     action_row = 1
     button = 2
     select = 3
@@ -625,6 +671,8 @@ def __int__(self):
 
 
 class ButtonStyle(Enum):
+    """Button style"""
+
     primary = 1
     secondary = 2
     success = 3
@@ -644,6 +692,8 @@ def __int__(self):
 
 
 class InputTextStyle(Enum):
+    """Input text style"""
+
     short = 1
     singleline = 1
     paragraph = 2
@@ -652,26 +702,34 @@ class InputTextStyle(Enum):
 
 
 class ApplicationType(Enum):
+    """Application type"""
+
     game = 1
     music = 2
     ticketed_events = 3
     guild_role_subscriptions = 4
 
 
 class StagePrivacyLevel(Enum):
+    """Stage privacy level"""
+
     # public = 1 (deprecated)
     closed = 2
     guild_only = 2
 
 
 class NSFWLevel(Enum, comparable=True):
+    """NSFW level"""
+
     default = 0
     explicit = 1
     safe = 2
     age_restricted = 3
 
 
 class SlashCommandOptionType(Enum):
+    """Slash command option type"""
+
     sub_command = 1
     sub_command_group = 2
     string = 3
@@ -743,6 +801,8 @@ def from_datatype(cls, datatype):
 
 
 class EmbeddedActivity(Enum):
+    """Embedded activity"""
+
     awkword = 879863881349087252
     betrayal = 773336526917861400
     checkers_in_the_park = 832013003968348200
@@ -777,6 +837,8 @@ class EmbeddedActivity(Enum):
 
 
 class ScheduledEventStatus(Enum):
+    """Scheduled event status"""
+
     scheduled = 1
     active = 2
     completed = 3
@@ -788,36 +850,48 @@ def __int__(self):
 
 
 class ScheduledEventPrivacyLevel(Enum):
+    """Scheduled event privacy level"""
+
     guild_only = 2
 
     def __int__(self):
         return self.value
 
 
 class ScheduledEventLocationType(Enum):
+    """Scheduled event location type"""
+
     stage_instance = 1
     voice = 2
     external = 3
 
 
 class AutoModTriggerType(Enum):
+    """Automod trigger type"""
+
     keyword = 1
     harmful_link = 2
     spam = 3
     keyword_preset = 4
 
 
 class AutoModEventType(Enum):
+    """Automod event type"""
+
     message_send = 1
 
 
 class AutoModActionType(Enum):
+    """Automod action type"""
+
     block_message = 1
     send_alert_message = 2
     timeout = 3
 
 
 class AutoModKeywordPresetType(Enum):
+    """Automod keyword preset type"""
+
     profanity = 1
     sexual_content = 2
     slurs = 3

docs/api.rst

@@ -1630,19 +1630,19 @@ of :class:`enum.Enum`.
 
     .. attribute:: news_thread
 
-        A news thread
+        A news thread.
 
         .. versionadded:: 2.0
 
     .. attribute:: public_thread
 
-        A public thread
+        A public thread.
 
         .. versionadded:: 2.0
 
     .. attribute:: private_thread
 
-        A private thread
+        A private thread.
 
         .. versionadded:: 2.0