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 11/11] doc/admin-policy-api: Rename to org.bluez.AdminPolicy*.rst
Date:   Mon,  9 Oct 2023 16:29:33 -0700
Message-ID: <20231009232933.500652-11-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 admin-policy-api.txt to org.bluez.AdminPolicy*.rst and
generate manpages org.bluez.AdminPolicy*.5.
---
 Makefile.am                         | 12 ++++--
 doc/admin-policy-api.txt            | 65 -----------------------------
 doc/org.bluez.AdminPolicySet.rst    | 52 +++++++++++++++++++++++
 doc/org.bluez.AdminPolicyStatus.rst | 49 ++++++++++++++++++++++
 4 files changed, 110 insertions(+), 68 deletions(-)
 delete mode 100644 doc/admin-policy-api.txt
 create mode 100644 doc/org.bluez.AdminPolicySet.rst
 create mode 100644 doc/org.bluez.AdminPolicyStatus.rst

diff --git a/Makefile.am b/Makefile.am
index ae44937a50e1..53dd12615560 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -363,7 +363,9 @@ man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
 		doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.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
+		doc/org.bluez.BatteryProvider.5 doc/org.bluez.Battery.5 \
+		doc/org.bluez.AdminPolicySet.5 \
+		doc/org.bluez.AdminPolicyStatus.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 \
@@ -384,7 +386,9 @@ manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
 		doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.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
+		doc/org.bluez.BatteryProvider.5 doc/org.bluez.Battery.5 \
+		doc/org.bluez.AdminPolicySet.5 \
+		doc/org.bluez.AdminPolicyStatus.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 \
@@ -442,7 +446,9 @@ EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.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
+		doc/org.bluez.BatteryProvider.rst doc/org.bluez.Battery.rst \
+		doc/org.bluez.AdminPolicySet.rst \
+		doc/org.bluez.AdminPolicyStatus.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/admin-policy-api.txt b/doc/admin-policy-api.txt
deleted file mode 100644
index 3f116901dbd7..000000000000
--- a/doc/admin-policy-api.txt
+++ /dev/null
@@ -1,65 +0,0 @@
-BlueZ D-Bus Admin Policy API description
-***********************************
-
-This API provides methods to control the behavior of bluez as an administrator.
-
-Interface AdminPolicySet1 provides methods to set policies. Once the policy is
-set successfully, it will affect all clients and stay persistently even after
-restarting Bluetooth Daemon. The only way to clear it is to overwrite the
-policy with the same method.
-
-Interface AdminPolicyStatus1 provides readonly properties to indicate the
-current values of admin policy.
-
-
-Admin Policy Set hierarchy
-=================
-
-Service		org.bluez
-Interface	org.bluez.AdminPolicySet1
-Object path	[variable prefix]/{hci0,hci1,...}
-
-Methods		void SetServiceAllowList(array{string} UUIDs)
-
-			This method sets the service allowlist by specifying
-			service UUIDs.
-
-			When SetServiceAllowList is called, bluez will block
-			incoming and outgoing connections to the service not in
-			UUIDs for all of the clients.
-
-			Any subsequent calls to this method will supersede any
-			previously set allowlist values.  Calling this method
-			with an empty array will allow any service UUIDs to be
-			used.
-
-			The default value is an empty array.
-
-			Possible errors: org.bluez.Error.InvalidArguments
-					 org.bluez.Error.Failed
-
-
-Admin Policy Status hierarchy
-=================
-
-Service		org.bluez
-Interface	org.bluez.AdminPolicyStatus1
-Object path	[variable prefix]/{hci0,hci1,...}
-
-Properties	array{string} ServiceAllowList [readonly]
-
-			Current value of service allow list.
-
-
-
-Admin Policy Status hierarchy
-=================
-
-Service		org.bluez
-Interface	org.bluez.AdminPolicyStatus1
-Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
-
-Properties	bool IsAffectedByPolicy [readonly]
-
-			Indicate if there is any auto-connect profile in this
-			device is not allowed by admin policy.
diff --git a/doc/org.bluez.AdminPolicySet.rst b/doc/org.bluez.AdminPolicySet.rst
new file mode 100644
index 000000000000..7ce4efcfed99
--- /dev/null
+++ b/doc/org.bluez.AdminPolicySet.rst
@@ -0,0 +1,52 @@
+========================
+org.bluez.AdminPolicySet
+========================
+
+--------------------------------------------
+BlueZ D-Bus AdminPolicySet API documentation
+--------------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Description
+============
+
+This API provides methods to control the behavior of **bluetoothd(8)** as an
+administrator.
+
+Interface AdminPolicySet1 provides methods to set policies. Once the policy is
+set successfully, it will affect all clients and stay persistently even after
+restarting **bluetoothd(8)**. The only way to clear it is to overwrite the
+policy with the same method.
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.AdminPolicySet1 [experimental]
+:Object path:	[variable prefix]/{hci0,hci1,...}
+
+Methods
+-------
+
+void SetServiceAllowList(array{string} UUIDs)
+`````````````````````````````````````````````
+
+	Sets the service allowlist by specifying service UUIDs.
+
+	When called, **bluetoothd(8)** will block incoming and outgoing
+	connections to the service not in UUIDs for all of the clients.
+
+	Any subsequent calls to this method will supersede any previously set
+	allowlist values.  Calling this method with an empty array will allow
+	any service UUIDs to be used.
+
+	The default value is an empty array.
+
+	Possible errors:
+
+	:org.bluez.Error.InvalidArguments:
+	:org.bluez.Error.Failed:
diff --git a/doc/org.bluez.AdminPolicyStatus.rst b/doc/org.bluez.AdminPolicyStatus.rst
new file mode 100644
index 000000000000..ad2dc58dec0a
--- /dev/null
+++ b/doc/org.bluez.AdminPolicyStatus.rst
@@ -0,0 +1,49 @@
+===========================
+org.bluez.AdminPolicyStatus
+===========================
+
+-----------------------------------------------
+BlueZ D-Bus AdminPolicyStatus API documentation
+-----------------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Description
+===========
+
+Interface AdminPolicyStatus1 provides readonly properties to indicate the
+current values of admin policy affecting the Adapter and Device objects.
+
+Interface
+=========
+
+Adapter
+-------
+
+:Service:	org.bluez
+:Interface:	org.bluez.AdminPolicyStatus1 [experimental]
+:Object path:	[variable prefix]/{hci0,hci1,...}
+
+Device
+------
+
+:Service:	org.bluez
+:Interface:	org.bluez.AdminPolicyStatus1 [experimental]
+:Object path:	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+Properties
+----------
+
+array{string} ServiceAllowList [readonly, adapter-only]
+```````````````````````````````````````````````````````
+
+	Current value of service allow list.
+
+bool IsAffectedByPolicy [readonly, device-only]
+```````````````````````````````````````````````
+
+	Indicate if there is any auto-connect profile in this device is not
+	allowed by admin policy.
-- 
2.41.0