chore: Improve Items documentation

discord/ui/action_row.py

@@ -87,10 +87,42 @@ class _ActionRowCallback:
 class ActionRow(Item[V]):
     """Represents a UI action row.
 
-    This object can be inherited.
+    This is a top-level layout component that can only be used on :class:`LayoutView`
+    and can contain :class:`Button` 's and :class:`Select` 's in it.
+
+    This can be inherited.
+
+    .. note::
+
+        Action rows can contain up to 5 components, which is, 5 buttons or 1 select.
 
     .. versionadded:: 2.6
 
+    Examples
+    --------
+
+    .. code-block:: python3
+
+        import discord
+        from discord import ui
+
+        # you can subclass it and add components with the decorators
+        class MyActionRow(ui.ActionRow):
+            @ui.button(label='Click Me!')
+            async def click_me(self, interaction: discord.Interaction, button: discord.ui.Button):
+                await interaction.response.send_message('You clicked me!')
+
+        # or use it directly on LayoutView
+        class MyView(ui.LayoutView):
+            row = ui.ActionRow()
+            # or you can use your subclass:
+            # row = MyActionRow()
+
+            # you can create items with row.button and row.select
+            @row.button(label='A button!')
+            async def row_button(self, interaction: discord.Interaction, button: discord.ui.Button):
+                await interaction.response.send_message('You clicked a button!')
+
     Parameters
     ----------
     id: Optional[:class:`int`]
@@ -127,7 +159,7 @@ class ActionRow(Item[V]):
         for func in self.__action_row_children_items__:
             item: Item = func.__discord_ui_model_type__(**func.__discord_ui_model_kwargs__)
             item.callback = _ActionRowCallback(func, self, item)  # type: ignore
-            item._parent = getattr(func, '__discord_ui_parent__', self)  # type: ignore
+            item._parent = getattr(func, '__discord_ui_parent__', self)
             setattr(self, func.__name__, item)
             children.append(item)
         return children

discord/ui/container.py

@@ -58,8 +58,41 @@ class _ContainerCallback:
 class Container(Item[V]):
     """Represents a UI container.
 
+    This is a top-level layout component that can only be used on :class:`LayoutView`
+    and can contain :class:`ActionRow` 's, :class:`TextDisplay` 's, :class:`Section` 's,
+    :class:`MediaGallery` 's, and :class:`File` 's in it.
+
+    This can be inherited.
+
+    .. note::
+
+        Containers can contain up to 10 top-level components.
+
     .. versionadded:: 2.6
 
+    Examples
+    --------
+
+    .. code-block:: python3
+
+        import discord
+        from discord import ui
+
+        # you can subclass it and add components as you would add them
+        # in a LayoutView
+        class MyContainer(ui.Container):
+            action_row = ui.ActionRow()
+
+            @action_row.button(label='A button in a container!')
+            async def a_button(self, interaction: discord.Interaction, button: discord.ui.Button):
+                await interaction.response.send_message('You clicked a button!')
+
+        # or use it directly on LayoutView
+        class MyView(ui.LayoutView):
+            container = ui.Container([ui.TextDisplay('I am a text display on a container!')])
+            # or you can use your subclass:
+            # container = MyContainer()
+
     Parameters
     ----------
     children: List[:class:`Item`]
@@ -123,7 +156,7 @@ class Container(Item[V]):
                 if getattr(raw, '__discord_ui_section__', False) and raw.accessory.is_dispatchable():  # type: ignore
                     self.__dispatchable.append(raw.accessory)  # type: ignore
                 elif getattr(raw, '__discord_ui_action_row__', False) and raw.is_dispatchable():
-                    raw._parent = self  # type: ignore
+                    raw._parent = self
                     self.__dispatchable.extend(raw._children)  # type: ignore
             else:
                 # action rows can be created inside containers, and then callbacks can exist here

discord/ui/file.py

@@ -42,8 +42,23 @@ __all__ = ('File',)
 class File(Item[V]):
     """Represents a UI file component.
 
+    This is a top-level layout component that can only be used on :class:`LayoutView`.
+
     .. versionadded:: 2.6
 
+    Example
+    -------
+
+    .. code-block:: python3
+
+        import discord
+        from discord import ui
+
+        class MyView(ui.LayoutView):
+            file = ui.File('attachment://file.txt')
+            # attachment://file.txt points to an attachment uploaded alongside
+            # this view
+
     Parameters
     ----------
     media: Union[:class:`str`, :class:`.UnfurledMediaItem`]

discord/ui/view.py

@@ -706,6 +706,10 @@ class View(BaseView):
 class LayoutView(BaseView):
     """Represents a layout view for components.
 
+    This object must be inherited to create a UI within Discord.
+
+    
+
     .. versionadded:: 2.6
 
     Parameters