From 9f1cb16d1654b31ffb30dc4d0b364a83a65e0d8e Mon Sep 17 00:00:00 2001
From: Hyundo Moon <hdmoon@google.com>
Date: Thu, 25 Mar 2021 10:00:07 +0900
Subject: [PATCH] System MR2: Supplement Javadoc for startScan/stopScan

Also does the same for MR2Manager#startScan/stopScan.

Bug: 183605044
Test: Builds successfully
Change-Id: I514c667a686706ff80c1d16619b557fff5ca569b
---
 media/java/android/media/MediaRouter2.java      | 17 +++++++++++++++++
 .../java/android/media/MediaRouter2Manager.java | 17 +++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/media/java/android/media/MediaRouter2.java b/media/java/android/media/MediaRouter2.java
index 8daa303890126..e7266e7a16df7 100644
--- a/media/java/android/media/MediaRouter2.java
+++ b/media/java/android/media/MediaRouter2.java
@@ -194,6 +194,14 @@ public final class MediaRouter2 {
 
     /**
      * Starts scanning remote routes.
+     * <p>
+     * Route discovery can happen even when the {@link #startScan()} is not called.
+     * This is because the scanning could be started before by other apps.
+     * Therefore, calling this method after calling {@link #stopScan()} does not necessarily mean
+     * that the routes found before are removed and added again.
+     * <p>
+     * Use {@link RouteCallback} to get the route related events.
+     * <p>
      * Note that calling start/stopScan is applied to all system routers in the same process.
      *
      * @see #stopScan()
@@ -208,6 +216,15 @@ public final class MediaRouter2 {
 
     /**
      * Stops scanning remote routes to reduce resource consumption.
+     * <p>
+     * Route discovery can be continued even after this method is called.
+     * This is because the scanning is only turned off when all the apps stop scanning.
+     * Therefore, calling this method does not necessarily mean the routes are removed.
+     * Also, for the same reason it does not mean that {@link RouteCallback#onRoutesAdded(List)}
+     * is not called afterwards.
+     * <p>
+     * Use {@link RouteCallback} to get the route related events.
+     * <p>
      * Note that calling start/stopScan is applied to all system routers in the same process.
      *
      * @see #startScan()
diff --git a/media/java/android/media/MediaRouter2Manager.java b/media/java/android/media/MediaRouter2Manager.java
index 6fefbe15abaee..758a8130a62e8 100644
--- a/media/java/android/media/MediaRouter2Manager.java
+++ b/media/java/android/media/MediaRouter2Manager.java
@@ -148,6 +148,14 @@ public final class MediaRouter2Manager {
 
     /**
      * Starts scanning remote routes.
+     * <p>
+     * Route discovery can happen even when the {@link #startScan()} is not called.
+     * This is because the scanning could be started before by other apps.
+     * Therefore, calling this method after calling {@link #stopScan()} does not necessarily mean
+     * that the routes found before are removed and added again.
+     * <p>
+     * Use {@link Callback} to get the route related events.
+     * <p>
      * @see #stopScan()
      */
     public void startScan() {
@@ -163,6 +171,15 @@ public final class MediaRouter2Manager {
 
     /**
      * Stops scanning remote routes to reduce resource consumption.
+     * <p>
+     * Route discovery can be continued even after this method is called.
+     * This is because the scanning is only turned off when all the apps stop scanning.
+     * Therefore, calling this method does not necessarily mean the routes are removed.
+     * Also, for the same reason it does not mean that {@link Callback#onRoutesAdded(List)}
+     * is not called afterwards.
+     * <p>
+     * Use {@link Callback} to get the route related events.
+     *
      * @see #startScan()
      */
     public void stopScan() {