Adjust external app docs based on jpelgrom comments

[TimoPtr]

Summary

This PR tries to adjust the documentation of the Outgoing/Incoming/Events we have in the FrontendScreen to aligned with the comments from @jpelgrom in #6872 (comment)

[Copilot]

Pull request overview

Updates KDoc/documentation around the frontend external bus message types and handler events, aligning wording with feedback from PR #6872 discussion to better describe request/response expectations between the Android app and Home Assistant frontend.

Changes:

• Refines KDoc for outgoing command messages (Improv + barcode scan) to clarify intent and response behavior.
• Refines KDoc for incoming external bus messages to emphasize whether a response is expected and how correlation via id works.
• Minor KDoc tweak for the handler event describing Improv scanning responsibilities.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
app/src/main/kotlin/io/homeassistant/companion/android/frontend/handler/FrontendHandlerEvent.kt	Adjusts Improv scan event documentation to better describe ViewModel responsibility.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/externalbus/outgoing/CommandMessage.kt	Updates outgoing message KDoc wording for Improv discovery and barcode scan results/aborts.
app/src/main/kotlin/io/homeassistant/companion/android/frontend/externalbus/incoming/IncomingExternalBusMessage.kt	Updates incoming message KDoc wording, especially around “no response expected” vs correlated id responses.

Comments suppressed due to low confidence (1)

app/src/main/kotlin/io/homeassistant/companion/android/frontend/externalbus/outgoing/CommandMessage.kt:138

• The KDoc was simplified, but now the forAction boolean in invoke(id, forAction) is no longer documented anywhere. This makes it hard to know when to pass true vs false, and what effect it has (it changes the reason sent to the frontend). Please document the meaning of forAction (and the resulting reason values) in the KDoc.

/**
 * Notifies the frontend that the user closed the scanner without producing a result.
 *
 * Sent in response to a [io.homeassistant.companion.android.frontend.externalbus.incoming.BarcodeScanMessage]
 * when the user cancels.
 *
 * @see CommandMessage
 */
object BarcodeScanAbortedMessage {
    operator fun invoke(id: Int, forAction: Boolean): OutgoingExternalBusMessage = CommandMessage(
        id = id,
        command = "bar_code/aborted",
        payload = frontendExternalBusJson.encodeToJsonElement(
            ScanAbortedPayload(reason = if (forAction) REASON_ALTERNATIVE_OPTIONS else REASON_CANCELED),
        ),

[jpelgrom]

Thanks for updating these

[github-actions]

Test Results

  267 files    297 suites   12m 7s ⏱️
2 142 tests 2 141 ✅ 1 💤 0 ❌
2 291 runs  2 290 ✅ 1 💤 0 ❌

Results for commit 4f83e11.

♻️ This comment has been updated with latest results.