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

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

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

Add parameter documentation for telephony commands including show,
select, dial, show-call, answer and hangup. Documents audio gateway
paths, phone numbers and call object parameters for telephony
operations.
---
 doc/bluetoothctl-telephony.rst | 66 +++++++++++++++++++++++++++++++---
 1 file changed, 62 insertions(+), 4 deletions(-)

diff --git a/doc/bluetoothctl-telephony.rst b/doc/bluetoothctl-telephony.rst
index a6870e781a7a..ae79ab0036d8 100644
--- a/doc/bluetoothctl-telephony.rst
+++ b/doc/bluetoothctl-telephony.rst
@@ -27,34 +27,69 @@ list
 List available audio gateways.
 
 :Usage: **> list**
+:Example Display all available HFP audio gateways:
+	| **> list**
 
 show
 ----
 
 Show audio gateway information.
 
-:Usage: **> show [audiogw]**
+:Usage: **> show [telephony]**
+:[telephony]: Audio gateway device path (optional, shows current if omitted)
+:Example Show information for currently selected audio gateway:
+	| **> show**
+:Example Show information for specific audio gateway device:
+	| **> show /org/bluez/hci0/dev_00_11_22_33_44_55**
+:Example Show information for another audio gateway:
+	| **> show /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF**
 
 select
 ------
 
 Select default audio gateway.
 
-:Usage: **> select <audiogw>**
+:Usage: **> select <telephony>**
+:<telephony>: Audio gateway device path to set as default
+:Example Select specific audio gateway as default:
+	| **> select /org/bluez/hci0/dev_00_11_22_33_44_55**
+:Example Select different audio gateway as default:
+	| **> select /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF**
 
 dial
 ----
 
 Dial number.
 
-:Usage: **> dial <number> [audiogw]**
+:Usage: **> dial <number> [telephony]**
+:<number>: Phone number to dial
+:[telephony]: Audio gateway device path (optional, uses current if omitted)
+:Example Dial number using currently selected audio gateway:
+	| **> dial 555-1234**
+:Example Dial international number using current audio gateway:
+	| **> dial +1-555-123-4567**
+:Example Dial emergency number using current audio gateway:
+	| **> dial 911**
+:Example Dial number using specific audio gateway:
+	| **> dial 555-1234 /org/bluez/hci0/dev_00_11_22_33_44_55**
+:Example Dial UK number using specific audio gateway:
+	| **> dial +44-20-7946-0958 /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF**
+:Example Dial with caller ID blocking:
+	| **> dial *67-555-1234**
+:Example Dial with caller ID hiding (GSM format):
+	| **> dial #31#555-1234**
 
 hangup-all
 ----------
 
 Hangup all calls.
 
-:Usage: **> hangup-all**
+:Usage: **> hangup-all [telephony]**
+:[telephony]: Audio gateway device path (optional, uses current if omitted)
+:Example Terminate all active and waiting calls on current gateway:
+	| **> hangup-all**
+:Example Terminate all calls on specific audio gateway:
+	| **> hangup-all /org/bluez/hci0/dev_00_11_22_33_44_55**
 
 list-calls
 ----------
@@ -62,6 +97,8 @@ list-calls
 List available calls.
 
 :Usage: **> list-calls**
+:Example Display all active, waiting, and held calls:
+	| **> list-calls**
 
 show-call
 ---------
@@ -69,6 +106,13 @@ show-call
 Show call information.
 
 :Usage: **> show-call <call>**
+:<call>: Call object path to display information for
+:Example Show information for specific call:
+	| **> show-call /org/bluez/hci0/dev_00_11_22_33_44_55/call1**
+:Example Show information for another call:
+	| **> show-call /org/bluez/hci0/dev_00_11_22_33_44_55/call2**
+:Example Show call information from different device:
+	| **> show-call /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/call1**
 
 answer
 ------
@@ -76,6 +120,13 @@ answer
 Answer call.
 
 :Usage: **> answer <call>**
+:<call>: Call object path to answer
+:Example Answer incoming call:
+	| **> answer /org/bluez/hci0/dev_00_11_22_33_44_55/call1**
+:Example Answer waiting call:
+	| **> answer /org/bluez/hci0/dev_00_11_22_33_44_55/call2**
+:Example Answer call from different device:
+	| **> answer /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/call1**
 
 hangup
 ------
@@ -83,6 +134,13 @@ hangup
 Hangup call.
 
 :Usage: **> hangup <call>**
+:<call>: Call object path to terminate
+:Example Terminate specific active call:
+	| **> hangup /org/bluez/hci0/dev_00_11_22_33_44_55/call1**
+:Example Terminate waiting or held call:
+	| **> hangup /org/bluez/hci0/dev_00_11_22_33_44_55/call2**
+:Example Terminate call from different device:
+	| **> hangup /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/call1**
 
 RESOURCES
 =========
-- 
2.52.0