[PATCH BlueZ v1 13/15] doc/bluetoothctl-scan: Document arguments and add examples

[Luiz Augusto von Dentz <luiz.dentz@gmail.com>]

From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>

Add comprehensive parameter documentation for all scan filter commands
including uuids, rssi, pathloss, transport, duplicate-data, discoverable,
pattern, auto-connect and clear options. Documents filter parameters
and threshold values for device discovery.
---
 doc/bluetoothctl-scan.rst | 120 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 116 insertions(+), 4 deletions(-)

diff --git a/doc/bluetoothctl-scan.rst b/doc/bluetoothctl-scan.rst
index cee255131622..29fa67514479 100644
--- a/doc/bluetoothctl-scan.rst
+++ b/doc/bluetoothctl-scan.rst
@@ -27,6 +27,23 @@ uuids
 Set/Get UUIDs filter.
 
 :Usage: **> uuids [all/uuid1 uuid2 ...]**
+:[all/uuid1 uuid2 ...]: List of UUIDs to filter for during scanning (default: none, use "all" to scan for any UUID)
+:Example Show current UUID filter settings:
+	| **> uuids**
+:Example Filter for Generic Access service only:
+	| **> uuids 0x1800**
+:Example Filter for Battery service only:
+	| **> uuids 0x180F**
+:Example Filter for Generic Access and Battery services:
+	| **> uuids 0x1800 0x180F**
+:Example Filter for Device Info, Battery, and Environmental Sensing:
+	| **> uuids 0x180A 0x180F 0x181A**
+:Example Filter for Generic Access using full UUID:
+	| **> uuids 00001800-0000-1000-8000-00805f9b34fb**
+:Example Filter using mixed short and long forms:
+	| **> uuids 00001800-0000-1000-8000-00805f9b34fb 0000180f-0000-1000-8000-00805f9b34fb**
+:Example Remove UUID filtering (scan for all devices):
+	| **> uuids all**
 
 rssi
 ----
@@ -41,7 +58,19 @@ If one or more discovery filters have been set, the RSSI delta-threshold imposed
 by starting discovery by default will not be applied.
 
 :Usage: **> rssi [rssi]**
-:Example: **> rssi -60**
+:[rssi]: Minimum RSSI threshold value in dBm (optional, shows current if omitted)
+:Example Show current RSSI filter setting:
+	| **> rssi**
+:Example Only report devices with RSSI ≥ -60 dBm (close range):
+	| **> rssi -60**
+:Example Report devices with RSSI ≥ -80 dBm (medium range):
+	| **> rssi -80**
+:Example Report devices with RSSI ≥ -90 dBm (extended range):
+	| **> rssi -90**
+:Example Report only very close devices (RSSI ≥ -40 dBm):
+	| **> rssi -40**
+:Example Report devices with very weak signals (maximum sensitivity):
+	| **> rssi -100**
 
 pathloss
 --------
@@ -55,7 +84,19 @@ If one or more discovery filters have been set, the RSSI delta-threshold
 imposed by starting discovery by default will not be applied.
 
 :Usage: **> pathloss [pathloss]**
-:Example: **> pathloss 4**
+:[pathloss]: Maximum pathloss threshold value in dB (optional, shows current if omitted)
+:Example Show current pathloss filter setting:
+	| **> pathloss**
+:Example Report devices with maximum 4 dB pathloss (very close):
+	| **> pathloss 4**
+:Example Report devices with maximum 10 dB pathloss (close range):
+	| **> pathloss 10**
+:Example Report devices with maximum 20 dB pathloss (medium range):
+	| **> pathloss 20**
+:Example Report devices with maximum 30 dB pathloss (extended range):
+	| **> pathloss 30**
+:Example Report devices with maximum 50 dB pathloss (maximum range):
+	| **> pathloss 50**
 
 transport
 ---------
@@ -79,6 +120,15 @@ If "auto" transport is requested, the scan will use LE, BREDR, or both,
 depending on what's currently enabled on the controller.
 
 :Usage: **> transport [auto/bredr/le]**
+:[auto/bredr/le]: Transport type for scanning (optional, shows current if omitted)
+:Example Show current transport filter setting:
+	| **> transport**
+:Example Use automatic transport selection (LE + BR/EDR):
+	| **> transport auto**
+:Example Scan only Low Energy devices:
+	| **> transport le**
+:Example Scan only BR/EDR (Classic Bluetooth) devices:
+	| **> transport bredr**
 
 duplicate-data
 --------------
@@ -91,6 +141,13 @@ When enabled, PropertiesChanged signals will be generated for ManufacturerData
 and ServiceData every time they are discovered.
 
 :Usage: **> duplicate-data [on/off]**
+:[on/off]: Enable or disable duplicate advertisement data reporting (optional, shows current if omitted)
+:Example Show current duplicate data filter setting:
+	| **> duplicate-data**
+:Example Enable reporting of duplicate advertisement data:
+	| **> duplicate-data on**
+:Example Disable duplicate data reporting (filter duplicates):
+	| **> duplicate-data off**
 
 discoverable
 ------------
@@ -103,6 +160,13 @@ If the adapter is already discoverable, setting this filter won't have any
 effect.
 
 :Usage: **> discoverable [on/off]**
+:[on/off]: Make adapter discoverable during scanning (optional, shows current if omitted)
+:Example Show current discoverable filter setting:
+	| **> discoverable**
+:Example Make adapter discoverable during scanning:
+	| **> discoverable on**
+:Example Keep adapter non-discoverable during scanning:
+	| **> discoverable off**
 
 pattern
 -------
@@ -120,7 +184,21 @@ When set, it disregards device discoverable flags.
        string "" pattern will match any device found.
 
 :Usage: **> pattern [value]**
-
+:[value]: Pattern to match device address prefix or name (optional, shows current if omitted)
+:Example Show current pattern filter setting:
+	| **> pattern**
+:Example Discover devices with "Samsung" in the name:
+	| **> pattern Samsung**
+:Example Discover devices with "iPhone" in the name:
+	| **> pattern iPhone**
+:Example Discover devices with "Headphones" in the name:
+	| **> pattern Headphones**
+:Example Discover devices with addresses starting with 00:11:22:
+	| **> pattern 00:11:22**
+:Example Discover devices with addresses starting with AA:BB:CC:
+	| **> pattern AA:BB:CC**
+:Example Clear pattern filter (match any device):
+	| **> pattern ""**
 
 auto-connect
 ------------
@@ -131,13 +209,47 @@ Connect to discovered devices automatically if pattern filter has been set and
 it matches the device address or name and the device is connectable.
 
 :Usage: **> auto-connect [on/off]**
+:[on/off]: Automatically connect to discovered devices matching pattern filter (optional, shows current if omitted)
+:Example Show current auto-connect filter setting:
+	| **> auto-connect**
+:Example Enable automatic connection to matching devices:
+	| **> auto-connect on**
+:Example Disable automatic connection (manual connection required):
+	| **> auto-connect off**
 
 clear
 -----
 
 Clears discovery filter.
 
-:Usage: **> clear [uuids/rssi/pathloss/transport/duplicate-data/discoverable/pattern]**
+:Usage: **> clear [uuids/rssi/pathloss/transport/duplicate-data/discoverable/pattern/auto-connect]**
+:[uuids/rssi/pathloss/transport/duplicate-data/discoverable/pattern/auto-connect]: Specific filter(s) to clear (optional, clears all if omitted)
+:Example Clear all discovery filters:
+	| **> clear**
+:Example Clear only UUID filter:
+	| **> clear uuids**
+:Example Clear only RSSI filter:
+	| **> clear rssi**
+:Example Clear only pathloss filter:
+	| **> clear pathloss**
+:Example Clear only transport filter:
+	| **> clear transport**
+:Example Clear only duplicate data filter:
+	| **> clear duplicate-data**
+:Example Clear only discoverable filter:
+	| **> clear discoverable**
+:Example Clear only pattern filter:
+	| **> clear pattern**
+:Example Clear only auto-connect filter:
+	| **> clear auto-connect**
+:Example Clear UUID and RSSI filters:
+	| **> clear uuids rssi**
+:Example Clear transport and pattern filters:
+	| **> clear transport pattern**
+:Example Clear pattern and auto-connect filters:
+	| **> clear pattern auto-connect**
+:Example Clear RSSI, pathloss, and discoverable filters:
+	| **> clear rssi pathloss discoverable**
 
 RESOURCES
 =========
-- 
2.52.0