2023-10-09 23:30:02

by Luiz Augusto von Dentz

[permalink] [raw]
Subject: [PATCH v2 09/11] doc/battery-api: Rename to org.bluez.Battery*.rst

From: Luiz Augusto von Dentz <[email protected]>

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