Received-SPF: pass (google.com: domain of linux-bluetooth-owner@vger.kernel.org designates 2620:137:e000::3:7 as permitted sender) client-ip=2620:137:e000::3:7;
From:   Luiz Augusto von Dentz <luiz.dentz@gmail.com>
To:     linux-bluetooth@vger.kernel.org
Subject: [PATCH v2 09/11] doc/battery-api: Rename to org.bluez.Battery*.rst
Date:   Mon,  9 Oct 2023 16:29:31 -0700
Message-ID: <20231009232933.500652-9-luiz.dentz@gmail.com>
In-Reply-To: <20231009232933.500652-1-luiz.dentz@gmail.com>
References: <20231009232933.500652-1-luiz.dentz@gmail.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

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

This renames battery-api.txt to org.bluez.Battery*.rst and generate
manpages org.bluez.Battery*.5.
---
 Makefile.am                              | 18 ++++---
 doc/battery-api.txt                      | 69 ------------------------
 doc/org.bluez.Battery.rst                | 39 ++++++++++++++
 doc/org.bluez.BatteryProvider.rst        | 32 +++++++++++
 doc/org.bluez.BatteryProviderManager.rst | 50 +++++++++++++++++
 5 files changed, 133 insertions(+), 75 deletions(-)
 delete mode 100644 doc/battery-api.txt
 create mode 100644 doc/org.bluez.Battery.rst
 create mode 100644 doc/org.bluez.BatteryProvider.rst
 create mode 100644 doc/org.bluez.BatteryProviderManager.rst

diff --git a/Makefile.am b/Makefile.am
index 0b62852a7a20..239d2da7bb05 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -361,7 +361,9 @@ man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
 		doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
 		doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \
 		doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \
-		doc/org.bluez.Network.5 doc/org.bluez.Input.5
+		doc/org.bluez.Network.5 doc/org.bluez.Input.5 \
+		doc/org.bluez.BatteryProviderManager.5 \
+		doc/org.bluez.BatteryProvider.5 doc/org.bluez.Battery.5
 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
 		doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
 		doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
@@ -378,7 +380,9 @@ manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
 		doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
 		doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \
 		doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \
-		doc/org.bluez.Network.5 doc/org.bluez.Input.5
+		doc/org.bluez.Network.5 doc/org.bluez.Input.5\
+		doc/org.bluez.BatteryProviderManager.5 \
+		doc/org.bluez.BatteryProvider.5 doc/org.bluez.Battery.5
 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \
 		doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \
 		doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \
@@ -429,10 +433,12 @@ EXTRA_DIST += doc/mgmt-api.txt \
 		doc/sap-api.txt
 
 EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
-	      doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \
-	      doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \
-	      doc/org.bluez.Profile.rst doc/org.bluez.NetworkServer.rst \
-	      doc/org.bluez.Network.rst doc/org.bluez.Input.rst
+		doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \
+		doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \
+		doc/org.bluez.Profile.rst doc/org.bluez.NetworkServer.rst \
+		doc/org.bluez.Network.rst doc/org.bluez.Input.rst \
+		doc/org.bluez.BatteryProviderManager.rst \
+		doc/org.bluez.BatteryProvider.rst doc/org.bluez.Battery.rst
 
 EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \
 		doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \
diff --git a/doc/battery-api.txt b/doc/battery-api.txt
deleted file mode 100644
index c03d64fc64b6..000000000000
--- a/doc/battery-api.txt
+++ /dev/null
@@ -1,69 +0,0 @@
-BlueZ D-Bus Battery API description
-***********************************
-
-
-Battery hierarchy
-=================
-
-Service		org.bluez
-Interface	org.bluez.Battery1
-Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
-
-Properties	byte Percentage [readonly]
-
-			The percentage of battery left as an unsigned 8-bit integer.
-
-		string Source [readonly, optional]
-
-			Describes where the battery information comes from
-			This property is informational only and may be useful
-			for debugging purposes.
-			Providers from BatteryProvider1 may make use of this
-			property to indicate where the battery report comes from
-			(e.g. "HFP 1.7", "HID", or the profile UUID).
-
-
-Battery Provider Manager hierarchy
-==================================
-A battery provider starts by registering itself as a battery provider with the
-RegisterBatteryProvider method passing an object path as the provider ID. Then,
-it can start exposing org.bluez.BatteryProvider1 objects having the path
-starting with the given provider ID. It can also remove objects at any time.
-The objects and their properties exposed by battery providers will be reflected
-on org.bluez.Battery1 interface.
-
-BlueZ will stop monitoring these exposed and removed objects after
-UnregisterBatteryProvider is called for that provider ID.
-
-Service		org.bluez
-Interface	org.bluez.BatteryProviderManager1
-Object path	/org/bluez/{hci0,hci1,...}
-
-Methods		void RegisterBatteryProvider(object provider)
-
-			This registers a battery provider. A registered
-			battery provider can then expose objects with
-			org.bluez.BatteryProvider1 interface described below.
-
-		void UnregisterBatteryProvider(object provider)
-
-			This unregisters a battery provider. After
-			unregistration, the BatteryProvider1 objects provided
-			by this client are ignored by BlueZ.
-
-
-Battery Provider hierarchy
-==========================
-
-Service		<client D-Bus address>
-Interface	org.bluez.BatteryProvider1
-Object path	{provider_root}/{unique battery object path}
-
-Properties	Objects provided on this interface contain the same properties
-		as org.bluez.Battery1 interface. Additionally, this interface
-		needs to have the Device property indicating the object path
-		of the device this battery provides.
-
-		object Device [readonly]
-
-			The object path of the device that has this battery.
diff --git a/doc/org.bluez.Battery.rst b/doc/org.bluez.Battery.rst
new file mode 100644
index 000000000000..d7e903c496ec
--- /dev/null
+++ b/doc/org.bluez.Battery.rst
@@ -0,0 +1,39 @@
+=================
+org.bluez.Battery
+=================
+
+-------------------------------------
+BlueZ D-Bus Battery API documentation
+-------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.Battery1
+:Object path:	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+Properties
+----------
+
+byte Percentage [readonly]
+``````````````````````````
+
+	The percentage of battery left as an unsigned 8-bit integer.
+
+string Source [readonly, optional]
+``````````````````````````````````
+
+	Describes where the battery information comes from.
+
+	This property is informational only and may be useful for debugging
+	purposes.
+
+	Providers from **org.bluez.BatteryProvider(5)** may make use
+	of this property to indicate where the battery report comes from
+	(e.g. "HFP 1.7", "HID", or the profile UUID).
diff --git a/doc/org.bluez.BatteryProvider.rst b/doc/org.bluez.BatteryProvider.rst
new file mode 100644
index 000000000000..b8d8b1c2ddd0
--- /dev/null
+++ b/doc/org.bluez.BatteryProvider.rst
@@ -0,0 +1,32 @@
+=========================
+org.bluez.BatteryProvider
+=========================
+
+---------------------------------------------
+BlueZ D-Bus BatteryProvider API documentation
+---------------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	<client D-Bus address>
+:Interface:	org.bluez.BatteryProvider1
+:Object path:	{provider_root}/{unique battery object path}
+
+Properties
+----------
+
+Objects provided on this interface contain the same properties as
+**org.bluez.Battery(5)** interface. Additionally, this interface needs to have
+the Device property indicating the object path of the device this battery
+provides.
+
+object Device [readonly]
+````````````````````````
+
+	The object path of the device that has this battery.
diff --git a/doc/org.bluez.BatteryProviderManager.rst b/doc/org.bluez.BatteryProviderManager.rst
new file mode 100644
index 000000000000..ab5cf2d4cadc
--- /dev/null
+++ b/doc/org.bluez.BatteryProviderManager.rst
@@ -0,0 +1,50 @@
+================================
+org.bluez.BatteryProviderManager
+================================
+
+----------------------------------------------------
+BlueZ D-Bus BatteryProviderManager API documentation
+----------------------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Description
+============
+
+A battery provider starts by registering itself as a battery provider with the
+**RegisterBatteryProvider()** method passing an object path as the provider ID.
+Then, it can start exposing **org.bluez.BatteryProvider(5)** objects having the
+path starting with the given provider ID. It can also remove objects at any
+time.
+The objects and their properties exposed by battery providers will be reflected
+on **org.bluez.Battery(5)** interface.
+
+**bluetoothd(8)** will stop monitoring these exposed and removed objects after
+UnregisterBatteryProvider is called for that provider ID.
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.BatteryProviderManager1
+:Object path:	/org/bluez/{hci0,hci1,...}
+
+Methods
+-------
+
+void RegisterBatteryProvider(object provider)
+`````````````````````````````````````````````
+
+	Registers a battery provider. A registered battery provider can then
+	expose objects with **org.bluez.BatteryProvider(5)** interface.
+
+void UnregisterBatteryProvider(object provider)
+```````````````````````````````````````````````
+
+	Unregisters a battery provider previously registered with
+	**RegisterBatteryProvider()**. After unregistration, the
+	**org.bluez.BatteryProvider(5)** objects provided by this client are
+	ignored by **bluetoothd(8)**.
-- 
2.41.0