Trim doc-heavy small methods in remote_build/controller.py

[bdraco]

What does this implement/fix?

Your screenshot of _fire_offloader_pair_peer_revoked was the
key data point: a 5-line typed-payload event-firer with an
11-line docstring explaining receiver-side REJECTED semantics.
The signal-to-noise ratio on these small helpers was the actual
readability problem after the previous two trim passes.

Reduced the docstring on every method where the docstring was
≥5 lines AND ≥2× the body's code-line count. Each collapses
to a single-line summary; the surrounding context that the
caller already knows (receiver-side state machine, four-cause
collapse, etc.) is removed — that context belongs at the call
site, not on a typed-payload firer.

controller.py: 3186 → 2837 lines (−349).
Prose-to-code ratio: 0.98 → 0.72.

Affected methods

• Event firers (the screenshot category):
  _fire_offloader_pair_status_changed,
  _fire_offloader_pair_pin_mismatch,
  _fire_offloader_pair_peer_revoked,
  _fire_pair_status_changed.
• Snapshot accessors (one-line list-comprehension wrappers
  that had multi-paragraph docstrings):
  peer_queue_status_snapshot,
  offloader_remote_jobs_snapshot, pairings_snapshot,
  peers_snapshot, offloader_alerts_snapshot,
  hosts_snapshot, remote_builds_enabled_snapshot,
  get_pairing, approved_peer_label.
• Internal getters: get_submit_job_receiver,
  get_artifacts_download_sender.
• WS commands with bloated docstrings for trivial bodies:
  get_identity, get_offloader_settings.
• Trivial helpers: _serialize_pairings,
  _serialize_peers, _schedule_pairings_save,
  _close_peer_link_resolver, _track_task,
  _dismiss_offloader_alert,
  _clear_pending_peers_on_window_close,
  _commit_endpoint_rebind,
  _respawn_peer_link_at_new_endpoint,
  _upsert_host, _spawn_pair_status_listener,
  is_pairing_window_open, _pairing_window_remaining,
  _on_offloader_peer_link_closed,
  _on_offloader_queue_status_changed,
  _current_settings_view, build_scheduler_snapshot.

Behaviour preservation

Strictly mechanical — no code lines changed; only docstring
lines removed. All 3117 tests pass.

Related issue or feature (if applicable):

• Follow-up to Trim controller.py prose: 4594 → 3723 lines (−871) #630 / Trim controller.py prose, pass 2: 3723 → 3186 (−537) #633 ("trim controller.py prose"). Pass
  3 specifically targets the small-method-bloated-docstring
  problem the earlier passes left behind.

Types of changes

• Bugfix (non-breaking change which fixes an issue) — bugfix
• New feature (non-breaking change which adds functionality) — new-feature
• Enhancement to an existing feature — enhancement
• Breaking change (fix or feature that would cause existing functionality to not work as expected) — breaking-change
• Refactor (no behaviour change) — refactor
• Documentation only — docs
• Maintenance / chore — maintenance
• CI / workflow change — ci
• Dependencies bump — dependencies

Frontend coordination

• No frontend change needed
• Companion frontend PR: esphome/device-builder-dashboard-frontend#

Checklist

• The code change is tested and works locally.
• Pre-commit hooks pass (ruff, codespell, yaml/json/python checks).
• Tests have been added or updated under tests/ where applicable.
• components.json has not been hand-edited (regenerate via script/sync_components.py if a sync is needed).
• Architecture-level changes are reflected in docs/ARCHITECTURE.md and/or docs/API.md.

[codspeed-hq]

Merging this PR will not alter performance

✅ 12 untouched benchmarks

---

_{Comparing trim-event-firers (4b228d1) with main (2ef488e)}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.21%. Comparing base (2ef488e) to head (4b228d1).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #634   +/-   ##
=======================================
  Coverage   99.21%   99.21%           
=======================================
  Files          90       90           
  Lines       10757    10757           
=======================================
  Hits        10673    10673           
  Misses         84       84           

Flag	Coverage Δ
py3.12	99.19% <ø> (ø)
py3.14	99.21% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...ice_builder/controllers/remote_build/controller.py	99.67% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR reduces verbosity in RemoteBuildController by trimming overlong docstrings on small, mostly self-explanatory helper methods, improving scan-ability of the remote-build controller without changing runtime behavior.

Changes:

• Collapses docstrings on many small helpers (event firers, snapshot accessors, internal getters, and trivial utilities) to shorter summaries.
• Removes receiver/offloader state-machine narrative from typed-payload “event firer” helpers and similar short wrappers.
• Keeps only concise intent-focused documentation where needed, reducing overall file size substantially.