docs(docstrings): Add Examples/Returns sections to property aliases
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 62/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Stale
- Tech stack
- python
- Domain
- documentation
Research direction
Review the property aliases in src/libtmux/pane.py, src/libtmux/window.py, src/libtmux/session.py, and src/libtmux/server.py, using the existing doctest_namespace fixtures as the usage context. For each alias, document its return type and value, then add a working doctest in the requested Examples and Returns sections. Done means all affected aliases have both sections and the doctests pass.
Written by the indexing model from the issue text.
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.
- Dominant language
- Python
- Stars
- 1.2k
- Forks
- 127
- Avg merge
- 2h 13m
- Merged PRs (30d)
- 1
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from tmux-python/libtmux
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
tmux-python/libtmux#759 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
tmux-python/libtmux#745 · 2 comments ·
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
tmux-python/libtmux#744 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
tmux-python/libtmux#731 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
tmux-python/libtmux#654 ·
All issues in tmux-python/libtmux
Similar issues
-
documentation help wanted
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
simonw/sqlite-utils#872 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100