[PATCH BlueZ v3 08/37] doc/bluetoothctl-gatt: Add :Uses: fields and document arguments

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

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

Add :Uses: fields to link commands to their corresponding D-Bus API
methods, and document command arguments with usage examples.
---
 doc/bluetoothctl-gatt.rst | 249 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 244 insertions(+), 5 deletions(-)

diff --git a/doc/bluetoothctl-gatt.rst b/doc/bluetoothctl-gatt.rst
index 6c72302ae935..493c7cf3b2c1 100644
--- a/doc/bluetoothctl-gatt.rst
+++ b/doc/bluetoothctl-gatt.rst
@@ -18,6 +18,10 @@ SYNOPSIS
 
 **bluetoothctl** [--options] [gatt.commands]
 
+This submenu interacts with GATT services, characteristics, and descriptors
+using the **org.bluez.GattService(5)**, **org.bluez.GattCharacteristic(5)**,
+**org.bluez.GattDescriptor(5)**, and **org.bluez.GattManager(5)** interfaces.
+
 
 Generic Attribute Commands
 ==========================
@@ -30,7 +34,24 @@ encompassing services, characteristics, and handles. This command provides
 a comprehensive overview of the available Bluetooth attributes, which can
 be further interacted with using other commands.
 
-:Usage: **> list-attributes <attribute/UUID> <dev/local>**
+:Usage: **> list-attributes [dev/local]**
+:[dev/local]: Device MAC address, object path, or "local" to list locally registered attributes (optional, lists all if omitted)
+:Example List attributes for specific service:
+	| **> list-attributes /org/bluez/hci0/dev_00_11_22_33_44_55/service001a**
+:Example List attributes for specific characteristic:
+	| **> list-attributes /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c**
+:Example List attributes for service on different device:
+	| **> list-attributes /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service0020**
+:Example List all Generic Access service attributes:
+	| **> list-attributes 0x1800**
+:Example List all Battery Service attributes:
+	| **> list-attributes 0x180F**
+:Example List all Device Name characteristic attributes:
+	| **> list-attributes 0x2A00**
+:Example List attributes using full UUID:
+	| **> list-attributes 00001801-0000-1000-8000-00805f9b34fb**
+:Example List attributes for custom service UUID:
+	| **> list-attributes 12345678-1234-5678-9abc-123456789abc**
 
 select-attribute
 ----------------
@@ -41,7 +62,25 @@ must select it with this command. This establishes a context for many
 other commands (read, write, notify, etc.), specifying the attribute
 they should operate on.
 
-:Usage: **> select-attribute <attribute/UUID/local>**
+:Usage: **> select-attribute <attribute/UUID/local> [attribute/UUID]**
+:<attribute/UUID/local>: GATT attribute path, UUID, or "local" to select from local attributes
+:[attribute/UUID]: Additional attribute path or UUID when using "local" (optional)
+:Example Select specific characteristic:
+	| **> select-attribute /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c**
+:Example Select specific descriptor:
+	| **> select-attribute /org/bluez/hci0/dev_00_11_22_33_44_55/service0020/char0022/desc0024**
+:Example Select service on different device:
+	| **> select-attribute /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF/service001a**
+:Example Select Device Name characteristic:
+	| **> select-attribute 0x2A00**
+:Example Select Battery Level characteristic:
+	| **> select-attribute 0x2A19**
+:Example Select Client Characteristic Configuration descriptor:
+	| **> select-attribute 0x2902**
+:Example Select Temperature characteristic using full UUID:
+	| **> select-attribute 00002a6e-0000-1000-8000-00805f9b34fb**
+:Example Select custom characteristic:
+	| **> select-attribute 12345678-1234-5678-9abc-123456789abc**
 
 attribute-info
 --------------
@@ -52,6 +91,17 @@ attribute. This command is useful for understanding the properties and
 capabilities of an attribute.
 
 :Usage: **> attribute-info [attribute/UUID]**
+:[attribute/UUID]: GATT attribute path or UUID to get info for (optional, uses current if omitted)
+:Example Show information for currently selected attribute:
+	| **> attribute-info**
+:Example Show info for specific characteristic:
+	| **> attribute-info /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c**
+:Example Show info for Battery Level characteristic:
+	| **> attribute-info 0x2A19**
+:Example Show info for Device Name characteristic:
+	| **> attribute-info 0x2A00**
+:Example Show info for Temperature characteristic:
+	| **> attribute-info 00002a6e-0000-1000-8000-00805f9b34fb**
 
 read
 ----
@@ -61,6 +111,18 @@ beforehand with select-attribute. The optional offset parameter can be
 used for attributes that allow partial reads.
 
 :Usage: **> read [offset]**
+:Uses: **org.bluez.GattCharacteristic(5)** method **ReadValue**
+:[offset]: Byte offset to start reading from (optional, defaults to 0)
+:Example Read attribute value from offset 0:
+	| **> read**
+:Example Read attribute value from offset 0 (explicit):
+	| **> read 0**
+:Example Read attribute value starting from offset 4:
+	| **> read 4**
+:Example Read attribute value starting from offset 10:
+	| **> read 10**
+:Example Read attribute value starting from offset 16:
+	| **> read 16**
 
 write
 -----
@@ -70,7 +132,25 @@ be selected in advance using select-attribute. Data must be provided in
 hexadecimal format. Optional offset and type parameters can accommodate
 specific write requirements.
 
-:Usage: **> write <data=xx xx ...> [offset] [type]**
+:Usage: **> write <data="xx xx ..."> [offset] [type]**
+:Uses: **org.bluez.GattCharacteristic(5)** method **WriteValue**
+:<xx xx ...>: Hexadecimal data bytes to write to the attribute
+:[offset]: Byte offset to start writing at (optional, defaults to 0)
+:[type]: Write type - request, command, or reliable (optional, defaults to request)
+:Example Write "Hello" to attribute (ASCII bytes):
+	| **> write "48 65 6C 6C 6F"**
+:Example Write binary data to attribute:
+	| **> write "01 02 03 04"**
+:Example Write single byte value:
+	| **> write "FF"**
+:Example Write 2 bytes starting at offset 4:
+	| **> write "01 02" 4**
+:Example Write with write request (default):
+	| **> write "48 65 6C 6C 6F" 0 request**
+:Example Write with write command (no response):
+	| **> write "01 02 03" 0 command**
+:Example Write with reliable write:
+	| **> write "FF EE DD" 0 reliable**
 
 acquire-write
 -------------
@@ -80,6 +160,9 @@ is useful for applications that need a file descriptor to perform
 write operations.
 
 :Usage: **> acquire-write**
+:Uses: **org.bluez.GattCharacteristic(5)** method **AcquireWrite**
+:Example Acquire write file descriptor for current attribute:
+	| **> acquire-write**
 
 release-write
 -------------
@@ -89,6 +172,8 @@ command is necessary to clean up resources after you're done with the
 write operation.
 
 :Usage: **> release-write**
+:Example Release write file descriptor for current attribute:
+	| **> release-write**
 
 acquire-notify
 --------------
@@ -98,6 +183,9 @@ This enables applications to listen for notifications on attribute
 value changes.
 
 :Usage: **> acquire-notify**
+:Uses: **org.bluez.GattCharacteristic(5)** method **AcquireNotify**
+:Example Acquire notify file descriptor for current attribute:
+	| **> acquire-notify**
 
 release-notify
 --------------
@@ -106,6 +194,8 @@ Releases the Notify file descriptor obtained with acquire-notify. Ensures
 resources are freed once notification listening is no longer needed.
 
 :Usage: **> release-notify**
+:Example Release notify file descriptor for current attribute:
+	| **> release-notify**
 
 notify
 ------
@@ -116,6 +206,12 @@ command allows applications to be notified of attribute changes without
 polling.
 
 :Usage: **> notify <on/off>**
+:Uses: **org.bluez.GattCharacteristic(5)** methods **StartNotify**, **StopNotify**
+:<on/off>: Enable or disable notifications for the current attribute
+:Example Enable notifications for current attribute:
+	| **> notify on**
+:Example Disable notifications for current attribute:
+	| **> notify off**
 
 clone
 -----
@@ -124,6 +220,21 @@ Creates a clone of a device or attribute. This can be useful for creating
 a backup or working with a copy for testing purposes.
 
 :Usage: **> clone [dev/attribute/UUID]**
+:[dev/attribute/UUID]: Device MAC address, attribute path, or UUID to clone (optional, clones current if omitted)
+:Example Clone entire device GATT database:
+	| **> clone 00:11:22:33:44:55**
+:Example Clone another device:
+	| **> clone AA:BB:CC:DD:EE:FF**
+:Example Clone specific service:
+	| **> clone /org/bluez/hci0/dev_00_11_22_33_44_55/service001a**
+:Example Clone specific characteristic:
+	| **> clone /org/bluez/hci0/dev_00_11_22_33_44_55/service001a/char001c**
+:Example Clone Generic Access service:
+	| **> clone 0x1800**
+:Example Clone Battery Service:
+	| **> clone 0x180F**
+:Example Clone Battery Level characteristic:
+	| **> clone 0x2A19**
 
 register-application
 --------------------
@@ -133,6 +244,18 @@ management of services, characteristics, and descriptors under this
 application.
 
 :Usage: **> register-application [UUID ...]**
+:Uses: **org.bluez.GattManager(5)** method **RegisterApplication**
+:[UUID ...]: Optional list of service UUIDs to register with the application
+:Example Register GATT application without specific UUIDs:
+	| **> register-application**
+:Example Register application with Battery Service:
+	| **> register-application 0x180F**
+:Example Register with Generic Access and Battery Service:
+	| **> register-application 0x1800 0x180F**
+:Example Register application with custom service UUID:
+	| **> register-application 12345678-1234-5678-9abc-123456789abc**
+:Example Register with multiple standard services:
+	| **> register-application 0x1800 0x180F 0x180A**
 
 unregister-application
 ----------------------
@@ -140,6 +263,9 @@ unregister-application
 Removes a previously registered application from the Bluetooth system.
 
 :Usage: **> unregister-application**
+:Uses: **org.bluez.GattManager(5)** method **UnregisterApplication**
+:Example Unregister current GATT application:
+	| **> unregister-application**
 
 register-service
 ----------------
@@ -148,6 +274,24 @@ Adds a new service under a registered application. This command is
 crucial for defining new services that devices can offer.
 
 :Usage: **> register-service <UUID> [handle]**
+:<UUID>: Service UUID to register (16-bit, 32-bit, or 128-bit format)
+:[handle]: Specific attribute handle to assign (optional, auto-assigned if omitted)
+:Example Register Generic Access service (auto handle):
+	| **> register-service 0x1800**
+:Example Register Battery Service (auto handle):
+	| **> register-service 0x180F**
+:Example Register Device Information service (auto handle):
+	| **> register-service 0x180A**
+:Example Register Generic Access service at handle 1:
+	| **> register-service 0x1800 0x0001**
+:Example Register Battery Service at handle 16:
+	| **> register-service 0x180F 0x0010**
+:Example Register Device Info service at handle 32:
+	| **> register-service 0x180A 0x0020**
+:Example Register custom service (auto handle):
+	| **> register-service 12345678-1234-5678-9abc-123456789abc**
+:Example Register custom service at specific handle:
+	| **> register-service 12345678-1234-5678-9abc-123456789abc 0x0050**
 
 unregister-service
 ------------------
@@ -156,6 +300,17 @@ Removes a service from a registered application, effectively ceasing
 its availability.
 
 :Usage: **> unregister-service <UUID/object>**
+:<UUID/object>: Service UUID or object path of the service to unregister
+:Example Unregister Generic Access service:
+	| **> unregister-service 0x1800**
+:Example Unregister Battery Service:
+	| **> unregister-service 0x180F**
+:Example Unregister custom service:
+	| **> unregister-service 12345678-1234-5678-9abc-123456789abc**
+:Example Unregister service by object path:
+	| **> unregister-service /org/bluez/example/service0**
+:Example Unregister another service:
+	| **> unregister-service /org/bluez/example/service1**
 
 register-includes
 -----------------
@@ -163,14 +318,28 @@ register-includes
 Marks a service as included within another service, allowing for
 service hierarchies and complex service structures.
 
-:Usage: **>r egister-includes <UUID> [handle]**
+:Usage: **> register-includes <UUID> [handle]**
+:<UUID>: Service UUID to register as included service
+:[handle]: Specific attribute handle to assign (optional, auto-assigned if omitted)
+:Example Register Generic Access as included service:
+	| **> register-includes 0x1800**
+:Example Register Battery Service as included at handle 21:
+	| **> register-includes 0x180F 0x0015**
+:Example Register custom service as included:
+	| **> register-includes 12345678-1234-5678-9abc-123456789abc**
 
 unregister-includes
 -------------------
 
 Removes an included service relationship, simplifying the service structure.
 
-:Usage: **> unregister-includes <Service-UUID><Inc-UUID>**
+:Usage: **> unregister-includes <Service-UUID> <Inc-UUID>**
+:<Service-UUID>: Parent service UUID that contains the included service
+:<Inc-UUID>: Included service UUID to remove from the parent service
+:Example Unregister Battery Service inclusion from Generic Access:
+	| **> unregister-includes 0x1800 0x180F**
+:Example Unregister Device Info inclusion from custom service:
+	| **> unregister-includes 12345678-1234-5678-9abc-123456789abc 0x180A**
 
 register-characteristic
 -----------------------
@@ -179,6 +348,31 @@ Introduces a new characteristic under a service, specifying its properties
 and access permissions with flags.
 
 :Usage: **> register-characteristic <UUID> <Flags=read,write,notify...> [handle]**
+:<UUID>: Characteristic UUID to register (16-bit, 32-bit, or 128-bit format)
+:<Flags=read,write,notify...>: Comma-separated list of characteristic properties and permissions
+:[handle]: Specific attribute handle to assign (optional, auto-assigned if omitted)
+:Example Register Device Name (read-only):
+	| **> register-characteristic 0x2A00 read**
+:Example Register Battery Level (read + notifications):
+	| **> register-characteristic 0x2A19 read,notify**
+:Example Register Heart Rate Measurement (notify-only):
+	| **> register-characteristic 0x2A37 notify**
+:Example Register Device Name (read + write):
+	| **> register-characteristic 0x2A00 read,write**
+:Example Register Battery Level (read + write + notify):
+	| **> register-characteristic 0x2A19 read,write,notify**
+:Example Register Temperature (read + indications):
+	| **> register-characteristic 0x2A6E read,indicate**
+:Example Register Device Name at handle 3:
+	| **> register-characteristic 0x2A00 read 0x0003**
+:Example Register Battery Level at handle 19:
+	| **> register-characteristic 0x2A19 read,notify 0x0013**
+:Example Register custom characteristic with full capabilities:
+	| **> register-characteristic 12345678-1234-5678-9abc-123456789abc read,write,notify**
+:Example Register custom write-only characteristic:
+	| **> register-characteristic ABCD1234-ABCD-1234-ABCD-123456789ABC write-without-response**
+:Example Register with all flags:
+	| **> register-characteristic 0x2A00 read,write,write-without-response,notify,indicate**
 
 unregister-characteristic
 -------------------------
@@ -186,6 +380,17 @@ unregister-characteristic
 Eliminates a characteristic from a service, removing its functionality.
 
 :Usage: **> unregister-characteristic <UUID/object>**
+:<UUID/object>: Characteristic UUID or object path of the characteristic to unregister
+:Example Unregister Device Name characteristic:
+	| **> unregister-characteristic 0x2A00**
+:Example Unregister Battery Level characteristic:
+	| **> unregister-characteristic 0x2A19**
+:Example Unregister custom characteristic:
+	| **> unregister-characteristic 12345678-1234-5678-9abc-123456789abc**
+:Example Unregister characteristic by object path:
+	| **> unregister-characteristic /org/bluez/example/service0/char0**
+:Example Unregister another characteristic:
+	| **> unregister-characteristic /org/bluez/example/service1/char1**
 
 register-descriptor
 -------------------
@@ -194,6 +399,29 @@ Adds a descriptor to a characteristic, further defining its behavior and
 access controls.
 
 :Usage: **> register-descriptor <UUID> <Flags=read,write...> [handle]**
+:<UUID>: Descriptor UUID to register (16-bit, 32-bit, or 128-bit format)
+:<Flags=read,write...>: Comma-separated list of descriptor properties and permissions
+:[handle]: Specific attribute handle to assign (optional, auto-assigned if omitted)
+:Example Register Client Characteristic Configuration:
+	| **> register-descriptor 0x2902 read,write**
+:Example Register Characteristic User Description:
+	| **> register-descriptor 0x2901 read**
+:Example Register Characteristic Presentation Format:
+	| **> register-descriptor 0x2904 read**
+:Example Register CCCD at handle 5:
+	| **> register-descriptor 0x2902 read,write 0x0005**
+:Example Register User Description at handle 21:
+	| **> register-descriptor 0x2901 read 0x0015**
+:Example Register custom descriptor:
+	| **> register-descriptor 12345678-1234-5678-9abc-123456789abc read,write**
+:Example Register custom read-only descriptor:
+	| **> register-descriptor ABCD1234-ABCD-1234-ABCD-123456789ABC read**
+:Example Register Valid Range descriptor:
+	| **> register-descriptor 0x2906 read**
+:Example Register External Report Reference:
+	| **> register-descriptor 0x2907 read**
+:Example Register Report Reference:
+	| **> register-descriptor 0x2908 read**
 
 unregister-descriptor
 ---------------------
@@ -201,6 +429,17 @@ unregister-descriptor
 Removes a descriptor from a characteristic, simplifying its behavior.
 
 :Usage: **> unregister-descriptor <UUID/object>**
+:<UUID/object>: Descriptor UUID or object path of the descriptor to unregister
+:Example Unregister Client Characteristic Configuration:
+	| **> unregister-descriptor 0x2902**
+:Example Unregister Characteristic User Description:
+	| **> unregister-descriptor 0x2901**
+:Example Unregister custom descriptor:
+	| **> unregister-descriptor 12345678-1234-5678-9abc-123456789abc**
+:Example Unregister descriptor by object path:
+	| **> unregister-descriptor /org/bluez/example/service0/char0/desc0**
+:Example Unregister another descriptor:
+	| **> unregister-descriptor /org/bluez/example/service1/char1/desc1**
 
 RESOURCES
 =========
-- 
2.52.0