tmux-python / tmux-python/libtmux

docs(docstrings): Add Examples/Returns sections to property aliases

Open
#640 0 comments 0 reactions 0 assignees View on GitHub

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.py
  • src/libtmux/window.py
  • src/libtmux/session.py
  • src/libtmux/server.py

What to add

For each property alias (e.g. session_name, window_id, pane_id, etc.):

  1. Returns section — document the return type and what the value represents
  2. Examples section — add a working doctest showing usage with the doctest_namespace fixtures

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.