[PATCH BlueZ v1 12/15] doc/bluetoothctl-player: 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 media player commands
including show, select, play, equalizer, repeat, shuffle, scan, search,
queue and folder navigation. Documents player paths, item selection
and media control parameters.
---
 doc/bluetoothctl-player.rst | 103 ++++++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/doc/bluetoothctl-player.rst b/doc/bluetoothctl-player.rst
index 1c5d436b31db..cd454bc5a8e2 100644
--- a/doc/bluetoothctl-player.rst
+++ b/doc/bluetoothctl-player.rst
@@ -27,6 +27,8 @@ list
 List available players.
 
 :Usage: **> list**
+:Example Display all available media players (local and remote):
+	| **> list**
 
 show
 ----
@@ -34,6 +36,11 @@ show
 Show player information.
 
 :Usage: **> show [player]**
+:[player]: Media player path or identifier (optional, shows currently selected player if omitted)
+:Example Show information for currently selected player:
+	| **> show**
+:Example Show remote player information:
+	| **> show /org/bluez/hci0/dev_00_11_22_33_44_55/player0**
 
 select
 ------
@@ -41,6 +48,9 @@ select
 Select default player.
 
 :Usage: **> select <player>**
+:<player>: Media player path or identifier to select as default
+:Example Select remote Bluetooth media player:
+	| **> select /org/bluez/hci0/dev_00_11_22_33_44_55/player0**
 
 play
 ----
@@ -48,6 +58,15 @@ play
 Start playback.
 
 :Usage: **> play [item]**
+:[item]: Media item path to play (optional, starts playback of current item if omitted)
+:Example Start playback on current player:
+	| **> play**
+:Example Play specific item from media browser:
+	| **> play /org/bluez/item/1**
+:Example Play named track item:
+	| **> play /org/bluez/item/track_001**
+:Example Play track from specific album folder:
+	| **> play /org/bluez/item/album_rock/track_05**
 
 pause
 -----
@@ -55,6 +74,8 @@ pause
 Pause playback.
 
 :Usage: **> pause**
+:Example Pause current playback:
+	| **> pause**
 
 stop
 ----
@@ -62,6 +83,8 @@ stop
 Stop playback.
 
 :Usage: **> stop**
+:Example Stop current playback:
+	| **> stop**
 
 next
 ----
@@ -69,6 +92,8 @@ next
 Jump to next item.
 
 :Usage: **> next**
+:Example Skip to next track:
+	| **> next**
 
 previous
 --------
@@ -76,6 +101,8 @@ previous
 Jump to previous item.
 
 :Usage: **> previous**
+:Example Go back to previous track:
+	| **> previous**
 
 fast-forward
 ------------
@@ -83,6 +110,8 @@ fast-forward
 Fast forward playback.
 
 :Usage: **> fast-forward**
+:Example Enable fast forward mode:
+	| **> fast-forward**
 
 rewind
 ------
@@ -90,6 +119,8 @@ rewind
 Rewind playback.
 
 :Usage: **> rewind**
+:Example Enable rewind mode:
+	| **> rewind**
 
 equalizer
 ---------
@@ -97,6 +128,11 @@ equalizer
 Enable/Disable equalizer.
 
 :Usage: **> equalizer <on/off>**
+:<on/off>: Enable (on) or disable (off) the equalizer
+:Example Enable equalizer:
+	| **> equalizer on**
+:Example Disable equalizer:
+	| **> equalizer off**
 
 repeat
 ------
@@ -104,6 +140,15 @@ repeat
 Set repeat mode.
 
 :Usage: **> repeat <singletrack/alltrack/group/off>**
+:<singletrack/alltrack/group/off>: Set repeat mode - singletrack (current track), alltrack (all tracks), group (current group/album), or off (no repeat)
+:Example Disable repeat mode:
+	| **> repeat off**
+:Example Repeat current track:
+	| **> repeat singletrack**
+:Example Repeat entire playlist/queue:
+	| **> repeat alltrack**
+:Example Repeat current group/album:
+	| **> repeat group**
 
 shuffle
 -------
@@ -111,6 +156,13 @@ shuffle
 Set shuffle mode.
 
 :Usage: **> shuffle <alltracks/group/off>**
+:<alltracks/group/off>: Set shuffle mode - alltracks (shuffle all tracks), group (shuffle within current group), or off (no shuffle)
+:Example Disable shuffle mode:
+	| **> shuffle off**
+:Example Shuffle all tracks in playlist:
+	| **> shuffle alltracks**
+:Example Shuffle tracks within current group:
+	| **> shuffle group**
 
 scan
 ----
@@ -118,6 +170,13 @@ scan
 Set scan mode.
 
 :Usage: **> scan <alltracks/group/off>**
+:<alltracks/group/off>: Set scan mode - alltracks (scan through all tracks), group (scan within current group), or off (no scan)
+:Example Disable scan mode:
+	| **> scan off**
+:Example Scan through all tracks:
+	| **> scan alltracks**
+:Example Scan through current group only:
+	| **> scan group**
 
 change-folder
 -------------
@@ -125,6 +184,15 @@ change-folder
 Change current folder.
 
 :Usage: **> change-folder <item>**
+:<item>: Folder path to navigate to, or ".." to go up one directory level
+:Example Navigate to Albums folder:
+	| **> change-folder /org/bluez/item/Albums**
+:Example Navigate to Artists folder:
+	| **> change-folder /org/bluez/item/Artists**
+:Example Navigate to Playlists folder:
+	| **> change-folder /org/bluez/item/Playlists**
+:Example Go up one directory level:
+	| **> change-folder ..**
 
 list-items
 ----------
@@ -132,6 +200,18 @@ list-items
 List items of current folder.
 
 :Usage: **> list-items [start] [end]**
+:[start]: Starting index for item list (optional, defaults to 0)
+:[end]: Ending index for item list (optional, lists all items from start if omitted)
+:Example List all items in current folder:
+	| **> list-items**
+:Example List first 10 items (0-10):
+	| **> list-items 0 10**
+:Example List items 5 through 15:
+	| **> list-items 5 15**
+:Example List items 10 through 20:
+	| **> list-items 10 20**
+:Example List first 50 items:
+	| **> list-items 0 50**
 
 search
 ------
@@ -139,6 +219,15 @@ search
 Search items containing string.
 
 :Usage: **> search <string>**
+:<string>: Search term to find matching items (songs, albums, artists, etc.)
+:Example Search for Beatles songs/albums:
+	| **> search "The Beatles"**
+:Example Search for items containing "rock":
+	| **> search "rock"**
+:Example Search for items from 2023:
+	| **> search "2023"**
+:Example Search for playlists:
+	| **> search "playlist"**
 
 queue
 -----
@@ -146,6 +235,13 @@ queue
 Add item to playlist queue.
 
 :Usage: **> queue <item>**
+:<item>: Media item path to add to the playback queue
+:Example Add specific track to queue:
+	| **> queue /org/bluez/item/track_001**
+:Example Add entire album to queue:
+	| **> queue /org/bluez/item/album_rock**
+:Example Add playlist to queue:
+	| **> queue /org/bluez/item/playlist_favorites**
 
 show-item
 ---------
@@ -153,6 +249,13 @@ show-item
 Show item information.
 
 :Usage: **> show-item <item>**
+:<item>: Media item path to display detailed information for
+:Example Show details of specific track:
+	| **> show-item /org/bluez/item/track_001**
+:Example Show details of album:
+	| **> show-item /org/bluez/item/album_rock**
+:Example Show details of artist:
+	| **> show-item /org/bluez/item/artist_beatles**
 
 RESOURCES
 =========
-- 
2.52.0