docs(session): Document deprecated legacy APIs

Author: tony

src/libtmux/session.py

@@ -594,37 +594,75 @@ def name(self) -> t.Optional[str]:
     # Legacy: Redundant stuff we want to remove
     #
     def get(self, key: str, default: t.Optional[t.Any] = None) -> t.Any:
-        """.. deprecated:: 0.16."""
+        """Return key-based lookup. Deprecated by attributes.
+
+        .. deprecated:: 0.16
+
+           Deprecated by attribute lookup.e.g. ``session['session_name']`` is now
+           accessed via ``session.session_name``.
+
+        """
         warnings.warn("Session.get() is deprecated", stacklevel=2)
         return getattr(self, key, default)
 
     def __getitem__(self, key: str) -> t.Any:
-        """.. deprecated:: 0.16."""
+        """Return item lookup by key. Deprecated in favor of attributes.
+
+        .. deprecated:: 0.16
+
+           Deprecated in favor of attributes. e.g. ``session['session_name']`` is now
+           accessed via ``session.session_name``.
+
+        """
         warnings.warn(
             f"Item lookups, e.g. session['{key}'] is deprecated", stacklevel=2
         )
         return getattr(self, key)
 
     def get_by_id(self, id: str) -> t.Optional[Window]:
-        """.. deprecated:: 0.16."""
+        """Return window by id. Deprecated in favor of :meth:`.windows.get()`.
+
+        .. deprecated:: 0.16
+
+           Deprecated by :meth:`.windows.get()`.
+
+        """
         warnings.warn("Session.get_by_id() is deprecated", stacklevel=2)
         return self.windows.get(window_id=id, default=None)
 
     def where(self, kwargs: t.Dict[str, t.Any]) -> t.List[Window]:
-        """.. deprecated:: 0.16."""
+        """Filter through windows, return list of :class:`Window`.
+
+        .. deprecated:: 0.16
+
+           Deprecated by :meth:`.windows.filter()`.
+
+        """
         warnings.warn("Session.where() is deprecated", stacklevel=2)
         try:
             return self.windows.filter(**kwargs)
         except IndexError:
             return []
 
     def find_where(self, kwargs: t.Dict[str, t.Any]) -> t.Optional[Window]:
-        """.. deprecated:: 0.16."""
+        """Filter through windows, return first :class:`Window`.
+
+        .. deprecated:: 0.16
+
+           Slated to be removed in favor of :meth:`.windows.get()`.
+
+        """
         warnings.warn("Session.find_where() is deprecated", stacklevel=2)
         return self.windows.get(default=None, **kwargs)
 
     def _list_windows(self) -> t.List["WindowDict"]:
-        """.. deprecated:: 0.16."""
+        """Return list of windows (deprecated in favor of :meth:`.windows`).
+
+        .. deprecated:: 0.16
+
+           Slated to be removed in favor of :attr:`.windows`.
+
+        """
         warnings.warn("Session._list_windows() is deprecated", stacklevel=2)
         return [w.__dict__ for w in self.windows]
 
@@ -633,6 +671,9 @@ def _windows(self) -> t.List["WindowDict"]:
         """Property / alias to return :meth:`Session._list_windows`.
 
         .. deprecated:: 0.16
+
+           Slated to be removed in favor of :attr:`.windows`.
+
         """
         warnings.warn("Session._windows is deprecated", stacklevel=2)
         return self._list_windows()
@@ -641,6 +682,9 @@ def list_windows(self) -> t.List["Window"]:
         """Return a list of :class:`Window` from the ``tmux(1)`` session.
 
         .. deprecated:: 0.16
+
+           Slated to be removed in favor of :attr:`.windows`.
+
         """
         warnings.warn("Session.list_windows() is deprecated", stacklevel=2)
         return self.windows
@@ -650,6 +694,9 @@ def children(self) -> QueryList["Window"]:  # type:ignore
         """Was used by TmuxRelationalObject (but that's longer used in this class).
 
         .. deprecated:: 0.16
+
+           Slated to be removed in favor of :attr:`.windows`.
+
         """
         warnings.warn("Session.children is deprecated", stacklevel=2)
         return self.windows