[Code Quality] Add docstrings to _api_get, _api_delete, _api_post, _api_post_form in api_client.py

[github-actions]

Description

api_client.py exports four HTTP wrapper functions via __all__ — _api_get, _api_delete, _api_post, _api_post_form — that are the primary interface used by main.py for all Control D API calls. None of the four has a docstring:

def _api_get(client: httpx.Client, url: str) -> httpx.Response:
    with _api_stats_lock:
        _api_stats["control_d_api_calls"] += 1
    return _retry_request(lambda: client.get(url))

Without docstrings, a developer reading main.py cannot quickly understand:

• That calls are automatically retried with exponential backoff (inherited from _retry_request)
• That API call counts are tracked in _api_stats for the summary report
• What exceptions propagate to the caller (httpx.HTTPStatusError, httpx.TimeoutException, httpx.ConnectError, RuntimeError)
• The difference between _api_post (JSON body) and _api_post_form (form-encoded body)

Suggested Changes

Add a one-line docstring to each function explaining its purpose and retry/stats contract:

def _api_get(client: httpx.Client, url: str) -> httpx.Response:
    """Issue a GET request to *url*, tracking the call in _api_stats and retrying on transient errors."""
    ...

def _api_delete(client: httpx.Client, url: str) -> httpx.Response:
    """Issue a DELETE request to *url*, tracking the call in _api_stats and retrying on transient errors."""
    ...

def _api_post(client: httpx.Client, url: str, data: dict) -> httpx.Response:
    """Issue a POST request with a JSON body to *url*, tracking the call in _api_stats and retrying on transient errors."""
    ...

def _api_post_form(client: httpx.Client, url: str, data: dict) -> httpx.Response:
    """Issue a POST request with a form-encoded body to *url*, tracking the call in _api_stats and retrying on transient errors."""
    ...

Files Affected

• api_client.py — add docstrings to 4 functions (lines 302–329)

Success Criteria

• ✅ All four functions have a docstring
• ✅ Docstrings note the retry behaviour and stats tracking
• ✅ uv run ruff check api_client.py passes (no D-series violations added)
• ✅ All existing tests pass: uv run pytest tests/ -v

Source

Identified during code review of api_client.py in the context of Daily Backlog Burner discussion #493 modularization analysis. The four functions appear in __all__ and are the primary public API consumed by main.py, making them high-value documentation targets.

Priority

Low — Four one-line docstrings. Improves maintainability and on-boarding for new contributors, especially as modularization work (#473) increases the number of people reading this module.

🔍 Task mining by Discussion Task Miner - Code Quality Improvement Agent

To install this agentic workflow, run

gh aw add github/gh-aw/.github/workflows/discussion-task-miner.md@94662b1dee8ce96c876ba9f33b3ab8be32de82a4

• expires on Mar 6, 2026, 5:27 AM UTC

[linear]

ABH-540