Bluetooth: Host: Document bt_le_scan_update()

This function is used in many places, but just by reading its
name it is not obvious why it is needed.
By adding some documentation it will hopefully become a bit more
clear that this function is mainly used for auto connection
establishment.

Signed-off-by: Rubin Gerritsen <rubin.gerritsen@nordicsemi.no>

subsys/bluetooth/host/hci_core.h

@@ -468,6 +468,29 @@ uint8_t bt_get_phy(uint8_t hci_phy);
  * @return CTE type (@ref bt_df_cte_type).
  */
 int bt_get_df_cte_type(uint8_t hci_cte_type);
+
+/** Start or restart scanner if needed
+ *
+ * Examples of cases where it may be required to start/restart a scanner:
+ * - When the auto-connection establishement feature is used:
+ *   - When the host sets a connection context for auto-connection establishment.
+ *   - When a connection was established.
+ *     The host may now be able to retry to automatically set up a connection.
+ *   - When a connection was disconnected/lost.
+ *     The host may now be able to retry to automatically set up a connection.
+ *   - When the application stops explicit scanning.
+ *     The host may now be able to retry to automatically set up a connection.
+ *   - The application tries to connect to another device, but fails.
+ *     The host may now be able to retry to automatically set up a connection.
+ * - When the application wants to connect to a device, but we need
+ *   to fallback to host privacy.
+ * - When the application wants to establish a periodic sync to a device
+ *   and the application has not already started scanning.
+ *
+ * @param fast_scan Use fast scan parameters or slow scan parameters
+ *
+ * @return 0 in case of success, or a negative error code on failure.
+ */
 int bt_le_scan_update(bool fast_scan);
 
 int bt_le_create_conn(const struct bt_conn *conn);

subsys/bluetooth/host/scan.c

@@ -318,6 +318,9 @@ static int start_passive_scan(bool fast_scan)
 int bt_le_scan_update(bool fast_scan)
 {
 	if (atomic_test_bit(bt_dev.flags, BT_DEV_EXPLICIT_SCAN)) {
+		/* The application has already explicitly started scanning.
+		 * We should keep the scanner running to avoid changing scan parameters.
+		 */
 		return 0;
 	}
 
@@ -348,12 +351,14 @@ int bt_le_scan_update(bool fast_scan)
 
 			bt_conn_unref(conn);
 
+			/* Start/Restart the scanner */
 			return start_passive_scan(fast_scan);
 		}
 	}
 
 #if defined(CONFIG_BT_PER_ADV_SYNC)
 	if (get_pending_per_adv_sync()) {
+		/* Start/Restart the scanner. */
 		return start_passive_scan(fast_scan);
 	}
 #endif