[widget Audit] toga.OptionContainer

core/src/toga/widgets/optioncontainer.py

@@ -65,15 +65,12 @@ def __repr__(self):
         items = ", ".join(repr(option.text) for option in self)
         return f"<OptionList {items}>"
 
-    def __getitem__(self, item: int | str | OptionItem) -> OptionItem:
+    def __getitem__(self, index: int | str | OptionItem) -> OptionItem:
         """Obtain a specific tab of content."""
-        return self._options[self.index(item)]
+        return self._options[self.index(index)]
 
     def __delitem__(self, index: int | str | OptionItem):
-        """Remove the specified tab of content.
-
-        The currently selected item cannot be deleted.
-        """
+        """Same as :any:`remove`."""
         self.remove(index)
 
     def remove(self, index: int | str | OptionItem):
@@ -95,16 +92,12 @@ def remove(self, index: int | str | OptionItem):
         # Refresh the widget
         self.interface.refresh()
 
-    def __iter__(self):
-        """Obtain an iterator over all tabs in the OptionContainer."""
-        return iter(self._options)
-
     def __len__(self) -> int:
         """The number of tabs of content in the OptionContainer."""
         return len(self._options)
 
     def index(self, value: str | int | OptionItem):
-        """Find the index of the tab that matches the given specifier
+        """Find the index of the tab that matches the given value.
 
         :param value: The value to look for. An integer is returned as-is;
             if an :any:`OptionItem` is provided, that item's index is returned;
@@ -231,7 +224,11 @@ def content(self) -> OptionList:
 
     @property
     def current_tab(self) -> OptionItem:
-        """The currently selected tab of content."""
+        """The currently selected tab of content.
+
+        The getter of this property always returns an ``OptionItem``. The setter also
+        accepts an ``int`` index, or a ``str`` label.
+        """
         index = self._impl.get_current_tab_index()
         if index is None:
             return None

docs/conf.py

@@ -67,6 +67,10 @@
 
 autoclass_content = "both"
 autodoc_preserve_defaults = True
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+}
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/reference/api/containers/box.rst

@@ -49,5 +49,3 @@ Reference
 ---------
 
 .. autoclass:: toga.Box
-   :members:
-   :undoc-members:

docs/reference/api/containers/optioncontainer.rst

@@ -26,12 +26,12 @@ Usage
     pasta = toga.Box()
 
     container = toga.OptionContainer(
-        content=[("Pizza", first), ("Pasta", second)]
+        content=[("Pizza", pizza), ("Pasta", pasta)]
     )
 
     # Add another tab of content
     salad = toga.Box()
-    container.add("Salad", third)
+    container.content.append("Salad", salad)
 
 When retrieving or deleting items, or when specifying the
 currently selected item, you can specify an item using:
@@ -40,8 +40,8 @@ currently selected item, you can specify an item using:
 
   .. code-block:: python
 
-      # Make the second tab in the container new content
-      container.insert(1, "Soup", toga.Box())
+      # Insert a new second tab
+      container.content.insert(1, "Soup", toga.Box())
       # Make the third tab the currently active tab
       container.current_tab = 2
       # Delete the second tab
@@ -51,8 +51,8 @@ currently selected item, you can specify an item using:
 
   .. code-block:: python
 
-      # Insert content at the index currently occupied by a tab labeled "Pasta"
-      container.insert("Pasta", "Soup", toga.Box())
+      # Insert a tab at the index currently occupied by a tab labeled "Pasta"
+      container.content.insert("Pasta", "Soup", toga.Box())
       # Make the tab labeled "Pasta" the currently active tab
       container.current_tab = "Pasta"
       # Delete tab labeled "Pasta"
@@ -65,7 +65,7 @@ currently selected item, you can specify an item using:
       # Get a reference to the "Pasta" tab
       pasta_tab = container.content["Pasta"]
       # Insert content at the index currently occupied by the pasta tab
-      container.insert(pasta_tab, "Soup", toga.Box())
+      container.content.insert(pasta_tab, "Soup", toga.Box())
       # Make the pasta tab the currently active tab
       container.current_tab = pasta_tab
       # Delete the pasta tab
@@ -75,13 +75,9 @@ Reference
 ---------
 
 .. autoclass:: toga.OptionContainer
-   :members:
-   :undoc-members: app, window
+   :exclude-members: app, window
 
 .. autoclass:: toga.widgets.optioncontainer.OptionList
-   :members:
-   :undoc-members:
+    :special-members: __getitem__, __delitem__
 
 .. autoclass:: toga.widgets.optioncontainer.OptionItem
-   :members:
-   :undoc-members: refresh

docs/reference/api/containers/scrollcontainer.rst

@@ -30,6 +30,4 @@ Reference
 ---------
 
 .. autoclass:: toga.ScrollContainer
-   :members:
-   :undoc-members:
    :exclude-members: window, app

docs/reference/api/containers/splitcontainer.rst

@@ -65,6 +65,4 @@ Reference
 ---------
 
 .. autoclass:: toga.SplitContainer
-   :members:
-   :undoc-members:
    :exclude-members: HORIZONTAL, VERTICAL, window, app

docs/reference/api/widgets/widget.rst

@@ -15,6 +15,4 @@ Reference
 ---------
 
 .. autoclass:: toga.Widget
-   :members:
-   :undoc-members:
    :inherited-members:

docs/reference/data/widgets_by_platform.csv

@@ -26,7 +26,7 @@ Widget,General Widget,:class:`~toga.Widget`,The base widget,|y|,|y|,|y|,|y|,|y|,
 Box,Layout Widget,:class:`~toga.Box`,Container for components,|y|,|y|,|y|,|y|,|y|,|b|
 ScrollContainer,Layout Widget,:class:`~toga.ScrollContainer`,A container that can display a layout larger than the area of the container,|y|,|y|,|y|,|y|,|y|,
 SplitContainer,Layout Widget,:class:`~toga.SplitContainer`,A container that divides an area into two panels with a movable border,|y|,|y|,|y|,,,
-OptionContainer,Layout Widget,:class:`~toga.OptionContainer`,A container that can display multiple labeled tabs of content.,|b|,|b|,|b|,,,
+OptionContainer,Layout Widget,:class:`~toga.OptionContainer`,A container that can display multiple labeled tabs of content,|y|,|y|,|y|,,,
 App Paths,Resource,:class:`~toga.paths.Paths`,A mechanism for obtaining platform-appropriate filesystem locations for an application.,|y|,|y|,|y|,|y|,|y|,
 Font,Resource,:class:`~toga.Font`,Fonts,|b|,|b|,|b|,|b|,|b|,
 Command,Resource,:class:`~toga.Command`,Command,|b|,|b|,|b|,,|b|,