docs(docstrings): Add Examples/Returns sections to property aliases #640
Description
Summary
Many property aliases across the core ORM classes lack Examples and Returns sections in their docstrings. Adding these would improve API discoverability and provide inline usage documentation.
Affected files
src/libtmux/pane.pysrc/libtmux/window.pysrc/libtmux/session.pysrc/libtmux/server.py
What to add
For each property alias (e.g. session_name, window_id, pane_id, etc.):
- Returns section — document the return type and what the value represents
- Examples section — add a working doctest showing usage with the
doctest_namespacefixtures
Example of the desired pattern:
@property
def pane_id(self) -> str | None:
"""Unique pane ID.
Returns
-------
str or None
Pane ID in the format ``%N``, e.g. ``%0``.
Examples
--------
>>> pane.pane_id # doctest: +ELLIPSIS
'%...'
"""Context
Found during code review of PR #636. This is a documentation-only enhancement with no functional changes.