Merge pull request #1578 from davep/prop-chop-doc

Add some extra docstrings to widgets

src/textual/binding.py

@@ -28,17 +28,17 @@ class Binding:
     """The configuration of a key binding."""
 
     key: str
-    """str: Key to bind. This can also be a comma-separated list of keys to map multiple keys to a single action."""
+    """Key to bind. This can also be a comma-separated list of keys to map multiple keys to a single action."""
     action: str
-    """str: Action to bind to."""
+    """Action to bind to."""
     description: str
-    """str: Description of action."""
+    """Description of action."""
     show: bool = True
-    """bool: Show the action in Footer, or False to hide."""
+    """Show the action in Footer, or False to hide."""
     key_display: str | None = None
-    """str | None: How the key should be shown in footer."""
+    """How the key should be shown in footer."""
     priority: bool = False
-    """bool: Enable priority binding for this key."""
+    """Enable priority binding for this key."""
 
 
 @rich.repr.auto

src/textual/widgets/_button.py

@@ -195,8 +195,13 @@ class Button(Static, can_focus=True):
         self.variant = self.validate_variant(variant)
 
     label: Reactive[RenderableType] = Reactive("")
+    """The text label that appears within the button."""
+
     variant = Reactive.init("default")
+    """The variant name for the button."""
+
     disabled = Reactive(False)
+    """The disabled state of the button; `True` if disabled, `False` if not."""
 
     def __rich_repr__(self) -> rich.repr.Result:
         yield from super().__rich_repr__()

src/textual/widgets/_checkbox.py

@@ -57,9 +57,6 @@ class Checkbox(Widget, can_focus=True):
         "checkbox--switch",
     }
 
-    value = reactive(False, init=False)
-    slider_pos = reactive(0.0)
-
     def __init__(
         self,
         value: bool = False,
@@ -84,6 +81,12 @@ class Checkbox(Widget, can_focus=True):
             self._reactive_value = value
         self._should_animate = animate
 
+    value = reactive(False, init=False)
+    """The value of the checkbox; `True` for on and `False` for off."""
+
+    slider_pos = reactive(0.0)
+    """The position of the slider."""
+
     def watch_value(self, value: bool) -> None:
         target_slider_pos = 1.0 if value else 0.0
         if self._should_animate:

src/textual/widgets/_input.py

@@ -113,6 +113,17 @@ class Input(Widget, can_focus=True):
         id: str | None = None,
         classes: str | None = None,
     ) -> None:
+        """Initialise the `Input` widget.
+
+        Args:
+            value (str | None, optional): An optional default value for the input.
+            placeholder (str, optional): Optional placeholder text for the input.
+            highlighter (Highlighter | None, optional): An optional highlighter for the input.
+            password (bool, optional): Flag to say if the field should obfuscate its content. Default is `False`.
+            name (str | None, optional): Optional name for the input widget.
+            id (str | None): Optional ID for the widget.
+            classes (str | None): Optional initial classes for the widget.
+        """
         super().__init__(name=name, id=id, classes=classes)
         if value is not None:
             self.value = value
@@ -127,7 +138,7 @@ class Input(Widget, can_focus=True):
 
     @property
     def _cursor_offset(self) -> int:
-        """Get the cell offset of the cursor."""
+        """The cell offset of the cursor."""
         offset = self._position_to_cell(self.cursor_position)
         if self._cursor_at_end:
             offset += 1
@@ -135,7 +146,7 @@ class Input(Widget, can_focus=True):
 
     @property
     def _cursor_at_end(self) -> bool:
-        """Check if the cursor is at the end"""
+        """Flag to indicate if the cursor is at the end"""
         return self.cursor_position >= len(self.value)
 
     def validate_cursor_position(self, cursor_position: int) -> int:
@@ -170,7 +181,7 @@ class Input(Widget, can_focus=True):
 
     @property
     def cursor_width(self) -> int:
-        """Get the width of the input (with extra space for cursor at the end)."""
+        """The width of the input (with extra space for cursor at the end)."""
         if self.placeholder and not self.value:
             return cell_len(self.placeholder)
         return self._position_to_cell(len(self.value)) + 1