Document Bluetooth replay callback changes

[cryptomilk]

Proposed change

Document Bluetooth replay callback changes

Type of change

• Document existing features within Home Assistant
• Document new or changing features for which there is an existing pull request elsewhere
• Spelling or grammatical corrections, or rewording for improved clarity
• Editing or restructuring documentation guidelines
• Changes to the backend of this documentation
• Remove stale or deprecated documentation

Checklist

• I have read and followed the documentation guidelines.
• I have verified that my changes render correctly in the documentation.

Additional information

• Link to relevant existing code or pull request: bluetooth: prioritize recent advertisements during history replay core#174539

Summary by CodeRabbit

• Documentation
  • Added a new Bluetooth API documentation subsection, “Controlling history replay order.”
  • Documented the replay option for Bluetooth callback subscriptions, including available replay modes, the default (oldest-first), and how to disable replay.
  • Included a Python example demonstrating registration with replay set to play back the newest-first history.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c860f8c9-055e-4c79-b2af-a242fcc20e6e

📥 Commits

Reviewing files that changed from the base of the PR and between 509857d and 6a426b8.

📒 Files selected for processing (1)

• docs/core/bluetooth/api.md

✅ Files skipped from review due to trivial changes (1)

• docs/core/bluetooth/api.md

---

📝 Walkthrough

Walkthrough

A new Bluetooth API documentation subsection adds replay ordering details for callback registration, covers BluetoothCallbackReplay modes, and shows an example using NEWEST_FIRST.

Changes

Bluetooth API Documentation

Layer / File(s)	Summary
Replay order control documentation docs/core/bluetooth/api.md	Adds a new subsection documenting the replay keyword argument and BluetoothCallbackReplay enum options (OLDEST_FIRST as default, NEWEST_FIRST, DISABLED), with a usage example.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Suggested reviewers

• silamon

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the documented Bluetooth replay callback changes.
Description check	✅ Passed	The description follows the template, includes the change summary, type of change, checklist, and a relevant Core PR link.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[bluetoothbot]

PR Review — Document Bluetooth replay callback changes

Accurate, well-scoped docs addition. Merge-ready; only minor style nits.

Verified against the referenced core PR (home-assistant/core#174539): the enum name BluetoothCallbackReplay, its three members (OLDEST_FIRST default, NEWEST_FIRST, DISABLED), the replay keyword argument, the stated default, and the from homeassistant.components.bluetooth import BluetoothCallbackReplay import path (it is in __all__) are all correct. The table is clear and the example mirrors the existing callback-registration examples.

• Suggestion: double blank lines around the table and code fence may trip markdownlint MD012
• Suggestion: example mixes direct and namespaced import styles, unlike the rest of the file

---

🟢 Suggestions

1. Double blank lines around the table will trip markdownlint
docs/core/bluetooth/api.md:100-113

There are two consecutive blank lines both before the | Value | Behavior | table and before the python fence.

Why it matters: the repo's markdown linting (MD012 – no-multiple-blanks) flags consecutive blank lines, which can fail CI on this docs repo. It's purely cosmetic but easy to trip.

Fix: collapse each pair to a single blank line.

keyword argument, which accepts a `BluetoothCallbackReplay` value:


| Value | Behavior |

2. Mixed import styles in the example
docs/core/bluetooth/api.md:104-113

The example imports BluetoothCallbackReplay directly (from homeassistant.components.bluetooth import BluetoothCallbackReplay) but then mixes namespaced and direct access in the same call: bluetooth.BluetoothScanningMode.ACTIVE (namespaced) alongside replay=BluetoothCallbackReplay.NEWEST_FIRST (direct).

Why it matters: every other example in this file uses the bluetooth.-namespaced style only, so the lone direct import reads as inconsistent and may nudge integration authors toward an unnecessary second import line.

Fix: either drop the direct import and use replay=bluetooth.BluetoothCallbackReplay.NEWEST_FIRST to match the surrounding examples, or keep the direct import but apply it consistently. The namespaced form is the lighter change.

from homeassistant.components import bluetooth
from homeassistant.components.bluetooth import BluetoothCallbackReplay

---

Checklist

• Documented API matches the referenced source PR
• Example code is correct and consistent with existing docs — suggestion ＃2
• Markdown formatting conforms to repo lint rules — suggestion ＃1
• Change matches the PR's stated scope

---

Automated review by Kōan (Claude) HEAD=509857d 2 min 13s

[bluetoothbot]

No blocking issues found.

[bdraco]

I think its worth fixing the mixed imports because people will copy this.

[cryptomilk]

Done