tmux-python / tmux-python/libtmux
docs(docstrings): Add Examples/Returns sections to property aliases
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.2k
- Forks
- 127
- Avg merge
- 2h 13m
- Merged PRs (30d)
- 1
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.
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.
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.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 62/100