Apply suggestions from code review

docs review thanku

Co-authored-by: Ice Wolfy <44532864+Icebluewolf@users.noreply.github.com>
Co-authored-by: Paillat <jeremiecotti@ik.me>
Signed-off-by: UK <41271523+NeloBlivion@users.noreply.github.com>

Author: 3 people

discord/components.py

@@ -106,7 +106,8 @@ class Component:
     type: :class:`ComponentType`
         The type of component.
     id: :class:`int`
-        The component's ID. If not provided by the user, it is automatically incremented.
+        The component's ID. If not provided by the user, it is set sequentially by Discord.
+        The ID `0` is treated as if no ID was provided.
     """
 
     __slots__: tuple[str, ...] = ("type", "id")
@@ -170,7 +171,7 @@ def __init__(self, data: ComponentPayload):
 
     @property
     def width(self):
-        """Return the total item width that this action row uses."""
+        """Return the sum of the children's widths."""
         t = 0
         for item in self.children:
             t += 1 if item.type is ComponentType.button else 5
@@ -572,7 +573,7 @@ def to_dict(self) -> SelectOptionPayload:
 class Section(Component):
     """Represents a Section from Components V2.
 
-    This is a component that groups other components together.
+    This is a component that groups other components together with an additional component to the right as the accessory.
 
     This inherits from :class:`Component`.
 
@@ -688,7 +689,7 @@ def from_dict(cls, data: UnfurledMediaItemPayload, state=None) -> UnfurledMediaI
         r._state = state
         return r
 
-    def to_dict(self):
+    def to_dict(self) -> dict[str, str]:
         return {"url": self.url}
 
 
@@ -708,7 +709,7 @@ class Thumbnail(Component):
     description: Optional[:class:`str`]
         The thumbnail's description, up to 1024 characters.
     spoiler: Optional[:class:`bool`]
-        Whether the thumbnail is a spoiler.
+        Whether the thumbnail has the spoiler overlay.
     """
 
     __slots__: tuple[str, ...] = (
@@ -853,7 +854,7 @@ class FileComponent(Component):
     size: :class:`int`
         The file's size in bytes.
     spoiler: Optional[:class:`bool`]
-        Whether the file is a spoiler.
+        Whether the file has the spoiler overlay.
     """
 
     __slots__: tuple[str, ...] = (
@@ -886,7 +887,7 @@ def to_dict(self) -> FileComponentPayload:
 class Separator(Component):
     """Represents a Separator from Components V2.
 
-    This is a component that separates other components.
+    This is a component that visually separates components.
 
     This inherits from :class:`Component`.
 
@@ -895,7 +896,7 @@ class Separator(Component):
     Attributes
     ----------
     divider: :class:`bool`
-        Whether the separator is a divider (provide example?)
+        Whether the separator will show a horizontal line in addition to vertical spacing.
     spacing: Optional[:class:`SeparatorSpacingSize`]
         The separator's spacing size.
     """
@@ -937,8 +938,12 @@ class Container(Component):
 
     Attributes
     ----------
-    items: List[:class:`MediaGalleryItem`]
-        The media this gallery contains.
+    components: List[:class:`Component`]
+        The components contained in this container.
+    accent_color: Optional[:class:`Colour`]
+        The accent color of the container.
+    spoiler: Optional[:class:`bool`]
+        Whether the entire container has the spoiler overlay.
     """
 
     __slots__: tuple[str, ...] = (

discord/ui/container.py

@@ -52,7 +52,7 @@ class Container(Item[V]):
     colour: Union[:class:`Colour`, :class:`int`]
         The accent colour of the container. Aliased to ``color`` as well.
     spoiler: Optional[:class:`bool`]
-        Whether this container is a spoiler.
+        Whether this container has the spoiler overlay.
     id: Optional[:class:`int`]
         The container's ID.
     """
@@ -173,7 +173,7 @@ def remove_item(self, item: Item | str | int) -> Self:
         return self
 
     def get_item(self, id: str | int) -> Item | None:
-        """Get a top-level item from this container. Roughly equivalent to `utils.get(container.items, ...)`.
+        """Get an item from this container. Roughly equivalent to `utils.get(container.items, ...)`.
         If an ``int`` is provided, the item will be retrieved by ``id``, otherwise by ``custom_id``.
         This method will also search for nested items.
 
@@ -232,6 +232,8 @@ def add_text(self, content: str, id: int | None = None) -> Self:
         ----------
         content: :class:`str`
             The content of the TextDisplay
+        id: Optiona[:class:`int`]
+            The text displays' ID.
         """
 
         text = TextDisplay(content, id=id)
@@ -267,7 +269,7 @@ def add_file(self, url: str, spoiler: bool = False, id: int | None = None) -> Se
         url: :class:`str`
             The URL of this file's media. This must be an ``attachment://`` URL that references a :class:`~discord.File`.
         spoiler: Optional[:class:`bool`]
-            Whether the file is a spoiler. Defaults to ``False``.
+            Whether the file has the spoiler overlay. Defaults to ``False``.
         id: Optiona[:class:`int`]
             The file's ID.
         """
@@ -307,7 +309,7 @@ def copy_text(self) -> str:
 
     @property
     def spoiler(self) -> bool:
-        """Whether the container is a spoiler. Defaults to ``False``."""
+        """Whether the container has the spoiler overlay. Defaults to ``False``."""
         return self._underlying.spoiler
 
     @spoiler.setter

discord/ui/file.py

@@ -31,7 +31,7 @@ class File(Item[V]):
     url: :class:`str`
         The URL of this file. This must be an ``attachment://`` URL referring to a local file used with :class:`~discord.File`.
     spoiler: Optional[:class:`bool`]
-        Whether this file is a spoiler.
+        Whether this file has the spoiler overlay.
     id: Optional[:class:`int`]
         The file component's ID.
     """
@@ -73,7 +73,7 @@ def url(self, value: str) -> None:
 
     @property
     def spoiler(self) -> bool:
-        """Whether the file is a spoiler. Defaults to ``False``."""
+        """Whether the file has the spoiler overlay. Defaults to ``False``."""
         return self._underlying.spoiler
 
     @spoiler.setter

discord/ui/media_gallery.py

@@ -90,7 +90,7 @@ def add_item(
         description: Optional[:class:`str`]
             The media item's description, up to 1024 characters.
         spoiler: Optional[:class:`bool`]
-            Whether the media item is a spoiler.
+            Whether the media item has the spoiler overlay.
 
         Raises
         ------
@@ -99,7 +99,7 @@ def add_item(
         """
 
         if len(self.items) >= 10:
-            raise ValueError("maximum number of children exceeded")
+            raise ValueError("maximum number of items exceeded")
 
         item = MediaGalleryItem(url, description=description, spoiler=spoiler)
 

discord/ui/section.py

@@ -225,7 +225,7 @@ def set_thumbnail(
         description: Optional[:class:`str`]
             The thumbnail's description, up to 1024 characters.
         spoiler: Optional[:class:`bool`]
-            Whether the thumbnail is a spoiler. Defaults to ``False``.
+            Whether the thumbnail has the spoiler overlay. Defaults to ``False``.
         id: Optional[:class:`int`]
             The thumbnail's ID.
         """
@@ -289,7 +289,7 @@ def disable_all_items(self, *, exclusions: list[Item] | None = None) -> Self:
 
     def enable_all_items(self, *, exclusions: list[Item] | None = None) -> Self:
         """
-        Enables all buttons and select menus in the container.
+        Enables all buttons and select menus in the section.
         At the moment, this only enables :attr:`accessory` if it is a button.
 
         Parameters

discord/ui/thumbnail.py

@@ -30,7 +30,7 @@ class Thumbnail(Item[V]):
     description: Optional[:class:`str`]
         The thumbnail's description, up to 1024 characters.
     spoiler: Optional[:class:`bool`]
-        Whether the thumbnail is a spoiler. Defaults to ``False``.
+        Whether the thumbnail has the spoiler overlay. Defaults to ``False``.
     id: Optional[:class:`int`]
         The thumbnail's ID.
     """
@@ -90,7 +90,8 @@ def description(self, description: str | None) -> None:
 
     @property
     def spoiler(self) -> bool:
-        """Whether the thumbnail is a spoiler. Defaults to ``False``."""
+        """Whether the thumbnail has the spoiler overlay. Defaults to ``False``."""
+
         return self._underlying.spoiler
 
     @spoiler.setter