Clear out ambiguity in broadcastradio@2.0 comments.

Bug: 76798863
Test: it builds
Change-Id: Icd13a187d3a002e6d1d0af8d360de31a75949b69

2 files changed, 13 insertions, 5 deletions

diff --git a/broadcastradio/2.0/ITunerCallback.hal b/broadcastradio/2.0/ITunerCallback.hal
index ede8350ef..b20a0b2d9 100644
--- a/broadcastradio/2.0/ITunerCallback.hal
+++ b/broadcastradio/2.0/ITunerCallback.hal
@@ -17,12 +17,14 @@ package android.hardware.broadcastradio@2.0;
 
 interface ITunerCallback {
     /**
-     * Method called by the HAL when a tuning operation fails
+     * Method called by the HAL when a tuning operation fails asynchronously
      * following a step(), scan() or tune() command.
      *
-     * @param result OK if tune succeeded;
-     *               TIMEOUT in case of time out.
-     * @param selector A ProgramSelector structure passed from tune(),
+     * This callback is only called when the step(), scan() or tune() command
+     * returned OK at first.
+     *
+     * @param result TIMEOUT in case of time out.
+     * @param selector A ProgramSelector structure passed from tune() call;
      *                 empty for step() and scan().
      */
     oneway onTuneFailed(Result result, ProgramSelector selector);
diff --git a/broadcastradio/2.0/types.hal b/broadcastradio/2.0/types.hal
index a9b960098..1ce61dfe9 100644
--- a/broadcastradio/2.0/types.hal
+++ b/broadcastradio/2.0/types.hal
@@ -351,10 +351,16 @@ struct ProgramInfo {
      * related content (i.e. DAB soft-links). This field is a list of pointers
      * to other programs on the program list.
      *
-     * Please note, that these identifiers does not have to exist on the program
+     * This is not a list of programs that carry the same content (i.e.
+     * DAB hard-links, RDS AF). Switching to programs from this list usually
+     * require user action.
+     *
+     * Please note, that these identifiers do not have to exist on the program
      * list - i.e. DAB tuner may provide information on FM RDS alternatives
      * despite not supporting FM RDS. If the system has multiple tuners, another
      * one may have it on its list.
+     *
+     * This field is optional (can be empty).
      */
     vec<ProgramIdentifier> relatedContent;