docs(docstrings): Add Returns/Raises sections for RST field list compliance

why: Sphinx/Napoleon requires proper field list structure to avoid
"Field list ends without a blank line" warnings when processing NumPy-style
docstrings.

what:
- Add Raises sections to EnvironmentMixin methods (common.py)
- Add Returns sections to capture_pane, display_message, set_width, set_height (pane.py)
- Fix attached_sessions Returns format (server.py)
- Add Raises section to kill_window (session.py)
- Add Returns/Raises sections to split, select_layout, move_window (window.py)
- Standardize parameter descriptions (capitalize, add periods)

Author: tony

src/libtmux/common.py

@@ -65,9 +65,14 @@ def set_environment(self, name: str, value: str) -> None:
         Parameters
         ----------
         name : str
-            the environment variable name. such as 'PATH'.
+            The environment variable name, e.g. 'PATH'.
         value : str
-            environment value.
+            Environment value.
+
+        Raises
+        ------
+        ValueError
+            If tmux returns an error.
         """
         args = ["set-environment"]
         if self._add_option:
@@ -92,7 +97,12 @@ def unset_environment(self, name: str) -> None:
         Parameters
         ----------
         name : str
-            the environment variable name. such as 'PATH'.
+            The environment variable name, e.g. 'PATH'.
+
+        Raises
+        ------
+        ValueError
+            If tmux returns an error.
         """
         args = ["set-environment"]
         if self._add_option:
@@ -116,7 +126,12 @@ def remove_environment(self, name: str) -> None:
         Parameters
         ----------
         name : str
-            the environment variable name. such as 'PATH'.
+            The environment variable name, e.g. 'PATH'.
+
+        Raises
+        ------
+        ValueError
+            If tmux returns an error.
         """
         args = ["set-environment"]
         if self._add_option:

src/libtmux/pane.py

@@ -341,6 +341,11 @@ def capture_pane(
             Negative numbers are lines in the history.
             ``-`` is the end of the visible pane.
             Default: None
+
+        Returns
+        -------
+        str | list[str]
+            Captured pane content.
         """
         cmd = ["capture-pane", "-p"]
         if start is not None:
@@ -428,6 +433,11 @@ def display_message(
         get_text : bool, optional
             Returns only text without displaying a message in
             target-client status line.
+
+        Returns
+        -------
+        str | list[str] | None
+            Message output if get_text is True, otherwise None.
         """
         if get_text:
             return self.cmd("display-message", "-p", cmd).stdout
@@ -710,7 +720,12 @@ def set_width(self, width: int) -> Pane:
         Parameters
         ----------
         width : int
-            pane width, in cells
+            Pane width, in cells.
+
+        Returns
+        -------
+        :class:`Pane`
+            Self, for method chaining.
         """
         self.resize_pane(width=width)
         return self
@@ -721,7 +736,12 @@ def set_height(self, height: int) -> Pane:
         Parameters
         ----------
         height : int
-            height of pain, in cells
+            Pane height, in cells.
+
+        Returns
+        -------
+        :class:`Pane`
+            Self, for method chaining.
         """
         self.resize_pane(height=height)
         return self

src/libtmux/server.py

@@ -313,7 +313,7 @@ def cmd(
 
     @property
     def attached_sessions(self) -> list[Session]:
-        """Return active :class:`Session`s.
+        """Return active :class:`Session` instances.
 
         Examples
         --------
@@ -322,7 +322,8 @@ def attached_sessions(self) -> list[Session]:
 
         Returns
         -------
-        list of :class:`Session`
+        list[:class:`Session`]
+            Sessions that are attached.
         """
         return self.sessions.filter(session_attached__noeq="1")
 

src/libtmux/session.py

@@ -578,7 +578,12 @@ def kill_window(self, target_window: str | None = None) -> None:
         Parameters
         ----------
         target_window : str, optional
-            window to kill
+            Window to kill.
+
+        Raises
+        ------
+        :exc:`libtmux.exc.LibTmuxException`
+            If tmux returns an error.
         """
         if target_window:
             if isinstance(target_window, int):

src/libtmux/window.py

@@ -284,27 +284,32 @@ def split(
         Parameters
         ----------
         attach : bool, optional
-            make new window the current window after creating it, default
+            Make new window the current window after creating it, default
             True.
         start_directory : str or PathLike, optional
-            specifies the working directory in which the new window is created.
+            Specifies the working directory in which the new window is created.
         direction : PaneDirection, optional
-            split in direction. If none is specified, assume down.
-        full_window_split: bool, optional
-            split across full window width or height, rather than active pane.
-        zoom: bool, optional
-            expand pane
+            Split in direction. If none is specified, assume down.
+        full_window_split : bool, optional
+            Split across full window width or height, rather than active pane.
+        zoom : bool, optional
+            Expand pane.
         shell : str, optional
-            execute a command on splitting the window.  The pane will close
+            Execute a command on splitting the window. The pane will close
             when the command exits.
 
-            NOTE: When this command exits the pane will close.  This feature
+            NOTE: When this command exits the pane will close. This feature
             is useful for long-running processes where the closing of the
             window upon completion is desired.
-        size: int, optional
+        size : int, optional
             Cell/row or percentage to occupy with respect to current window.
-        environment: dict, optional
+        environment : dict, optional
             Environmental variables for new pane. Passthrough to ``-e``.
+
+        Returns
+        -------
+        :class:`Pane`
+            The newly created pane.
         """
         active_pane = self.active_pane or self.panes[0]
         return active_pane.split(
@@ -409,7 +414,7 @@ def select_layout(self, layout: str | None = None) -> Window:
         Parameters
         ----------
         layout : str, optional
-            string of the layout, 'even-horizontal', 'tiled', etc. Entering
+            String of the layout, 'even-horizontal', 'tiled', etc. Entering
             None (leaving this blank) is same as ``select-layout`` with no
             layout. In recent tmux versions, it picks the most recently
             set layout.
@@ -430,7 +435,17 @@ def select_layout(self, layout: str | None = None) -> Window:
                 Panes are spread out as evenly as possible over the window in
                 both rows and columns.
             'custom'
-                custom dimensions (see :term:`tmux(1)` manpages).
+                Custom dimensions (see :term:`tmux(1)` manpages).
+
+        Returns
+        -------
+        :class:`Window`
+            Self, for method chaining.
+
+        Raises
+        ------
+        :exc:`libtmux.exc.LibTmuxException`
+            If tmux returns an error.
         """
         cmd = ["select-layout"]
 
@@ -539,11 +554,21 @@ def move_window(
         Parameters
         ----------
         destination : str, optional
-            the ``target window`` or index to move the window to, default:
-            empty string
+            The ``target window`` or index to move the window to, default:
+            empty string.
         session : str, optional
-            the ``target session`` or index to move the window to, default:
+            The ``target session`` or index to move the window to, default:
             current session.
+
+        Returns
+        -------
+        :class:`Window`
+            Self, for method chaining.
+
+        Raises
+        ------
+        :exc:`libtmux.exc.LibTmuxException`
+            If tmux returns an error.
         """
         session = session or self.session_id
         proc = self.cmd(