improved docs

API.md

@@ -3,6 +3,7 @@
 This page documents the public Core API surface and how V3 maps to the legacy API in this codebase.
 
 Core (legacy / V1)
+--------------------------
 - Located at `connections/core.h` and implemented in `connections/core.cc`.
 - Key operations:
   - Advertising / Discovery: `StartAdvertising`, `StopAdvertising`, `StartDiscovery`, `StopDiscovery`.
@@ -12,28 +13,32 @@ Core (legacy / V1)
   - Misc: `SetCustomSavePath`, `GetLocalEndpointId`, `Dump()`.
 
 V3 API
+---------------------------
 - Exposed as `StartAdvertisingV3`, `StartDiscoveryV3`, `RequestConnectionV3`, `AcceptConnectionV3`, etc. and uses V3-specific types:
   - `v3::AdvertisingOptions`, `v3::DiscoveryOptions`, `v3::ConnectionListener`, `v3::ConnectionsDevice` / `NearbyDevice`.
 - V3 provides richer structures (e.g. `v3::BandwidthInfo`) and strongly-typed device representations.
 
-V3 -> V1 mapping (how it works in core.cc)
+**V3 -> V1 mapping (how it works in core.cc)**
 - The V3 methods convert v3 options/objects into the legacy `AdvertisingOptions`/`DiscoveryOptions` and `ConnectionRequestInfo` and then call the V1 implementation (e.g. `StartAdvertisingV3` constructs an old AdvertisingOptions then calls `router_->StartAdvertising`). See `Core::StartAdvertisingV3` and `Core::StartDiscoveryV3`.
 - Because V3 currently bridges to the legacy routing stack, the code contains compatibility glue. The Core header warns: "Do NOT mix with the V1 APIs above" for safety; calling both styles in one process can produce undefined behavior.
 
 What about V2?
+--------------------------
 - The codebase contains references to `core_v2` in comments (e.g. some internal headers mention `cpp/core_v2/core.h`), but in this repository the first-class APIs are V1 (legacy) and V3. There is no complete `core_v2` directory in `nearby_latest`—it appears to be a referenced or historical intermediate.
 
 Usage patterns and examples (high level)
+----------------------------
 1. Advertising & discovery: call `StartAdvertising(...)` on one device and `StartDiscovery(...)` on another with matching service_id.
 2. Connection: the scanner receives an endpoint -> call `RequestConnection(endpoint_id, ...)`; the advertiser receives `OnConnectionInitiated` and calls `AcceptConnection(endpoint_id, payload_listener)`.
 3. Once accepted, use `SendPayload` to send files/streams/bytes.
 4. To improve throughput, call `InitiateBandwidthUpgrade(endpoint_id)` to attempt a BWU via BwuManager.
 
-References
+**References**
 - `connections/core.h`, `connections/core.cc`
 - `connections/implementation/service_controller_router.*` (routing/mapping)
 - `connections/v3/*` for V3 data structures
 
 Notes & cautions
+--------------------------
 - Prefer V3 for new integrations where possible, but note the code currently bridges V3 to the legacy routing stack.
-- Do not mix V1 and V3 calls within the same Core usage pattern unless you understand the bridging and lifetime semantics.
+- Do not mix V1 and V3 calls within the same Core usage pattern unless you understand the bridging and lifetime semantics.