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 05/11] doc/network-api: Rename to org.bluez.Network{Server}.rst
Date:   Mon,  9 Oct 2023 16:29:27 -0700
Message-ID: <20231009232933.500652-5-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 network-api.txt to org.bluez.Network{Server}.rst and
generate manpages org.bluez.Network{Server}.5.
---
 Makefile.am                     | 11 +++--
 doc/network-api.txt             | 76 ------------------------------
 doc/org.bluez.Network.rst       | 83 +++++++++++++++++++++++++++++++++
 doc/org.bluez.NetworkServer.rst | 68 +++++++++++++++++++++++++++
 4 files changed, 158 insertions(+), 80 deletions(-)
 delete mode 100644 doc/network-api.txt
 create mode 100644 doc/org.bluez.Network.rst
 create mode 100644 doc/org.bluez.NetworkServer.rst

diff --git a/Makefile.am b/Makefile.am
index 64004004fb2a..797dc6b78fa5 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -360,7 +360,8 @@ man_MANS += src/bluetoothd.8
 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.Profile.5 doc/org.bluez.NetworkServer.5 \
+		doc/org.bluez.Network.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 \
@@ -370,7 +371,8 @@ manual_pages += src/bluetoothd.8
 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.Profile.5 doc/org.bluez.NetworkServer.5 \
+		doc/org.bluez.Network.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 \
@@ -411,13 +413,14 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
 				doc/settings-storage.txt
 
 EXTRA_DIST += doc/mgmt-api.txt \
-		doc/network-api.txt doc/health-api.txt \
+		doc/health-api.txt \
 		doc/sap-api.txt doc/input-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.Profile.rst doc/org.bluez.NetworkServer.rst \
+	      doc/org.bluez.Network.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/network-api.txt b/doc/network-api.txt
deleted file mode 100644
index 109da28bf10d..000000000000
--- a/doc/network-api.txt
+++ /dev/null
@@ -1,76 +0,0 @@
-BlueZ D-Bus Network API description
-***********************************
-
-
-Network hierarchy
-=================
-
-Service		org.bluez
-Interface	org.bluez.Network1
-Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
-
-Methods		string Connect(string uuid)
-
-			Connect to the network device and return the network
-			interface name. Examples of the interface name are
-			bnep0, bnep1 etc.
-
-			uuid can be either one of "gn", "panu" or "nap" (case
-			insensitive) or a traditional string representation of
-			UUID or a hexadecimal number.
-
-			The connection will be closed and network device
-			released either upon calling Disconnect() or when
-			the client disappears from the message bus.
-
-			Possible errors: org.bluez.Error.AlreadyConnected
-					 org.bluez.Error.ConnectionAttemptFailed
-
-		void Disconnect()
-
-			Disconnect from the network device.
-
-			To abort a connection attempt in case of errors or
-			timeouts in the client it is fine to call this method.
-
-			Possible errors: org.bluez.Error.Failed
-
-Properties	boolean Connected [readonly]
-
-			Indicates if the device is connected.
-
-		string Interface [readonly]
-
-			Indicates the network interface name when available.
-
-		string UUID [readonly]
-
-			Indicates the connection role when available.
-
-
-Network server hierarchy
-========================
-
-Service		org.bluez
-Interface	org.bluez.NetworkServer1
-Object path	/org/bluez/{hci0,hci1,...}
-
-Methods		void Register(string uuid, string bridge)
-
-			Register server for the provided UUID. Every new
-			connection to this server will be added the bridge
-			interface.
-
-			Valid UUIDs are "gn", "panu" or "nap".
-
-			Initially no network server SDP is provided. Only
-			after this method a SDP record will be available
-			and the BNEP server will be ready for incoming
-			connections.
-
-		void Unregister(string uuid)
-
-			Unregister the server for provided UUID.
-
-			All servers will be automatically unregistered when
-			the calling application terminates.
diff --git a/doc/org.bluez.Network.rst b/doc/org.bluez.Network.rst
new file mode 100644
index 000000000000..d81a69d3c8af
--- /dev/null
+++ b/doc/org.bluez.Network.rst
@@ -0,0 +1,83 @@
+=================
+org.bluez.Network
+=================
+
+-------------------------------------
+BlueZ D-Bus Network API documentation
+-------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.Network1
+:Object path:	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+Methods
+-------
+
+string Connect(string uuid)
+```````````````````````````
+
+	Connects to the network device and return the network interface name.
+
+	Possible uuid values:
+
+	:"panu", "00001115-0000-1000-8000-00805f9b34fb":
+
+		Personal Network User role.
+
+	:"nap", "00001116-0000-1000-8000-00805f9b34fb":
+
+		Network Access Point role.
+
+	:"gn", "00001117-0000-1000-8000-00805f9b34fb":
+
+		Group Network role.
+
+	The connection will be closed and network device released either upon
+	calling **Disconnect()** or when the client disappears from the
+	message bus.
+
+	Possible errors:
+
+	:org.bluez.Error.InvalidArguments:
+	:org.bluez.Error.NotSupported:
+	:org.bluez.Error.InProgress:
+	:org.bluez.Error.Failed:
+
+void Disconnect()
+`````````````````
+
+	Disconnects from the network device.
+
+	To abort a connection attempt in case of errors or timeouts in the
+	client it is fine to call this method.
+
+	Possible errors:
+
+	:org.bluez.Error.Failed:
+	:org.bluez.Error.NotConnected:
+
+Properties
+----------
+
+boolean Connected [readonly]
+````````````````````````````
+
+	Indicates if the device is connected.
+
+string Interface [readonly, optional]
+`````````````````````````````````````
+
+	Indicates the network interface name when available.
+
+string UUID [readonly, optional]
+````````````````````````````````
+
+	Indicates the connection role when available.
diff --git a/doc/org.bluez.NetworkServer.rst b/doc/org.bluez.NetworkServer.rst
new file mode 100644
index 000000000000..d15d223c5eca
--- /dev/null
+++ b/doc/org.bluez.NetworkServer.rst
@@ -0,0 +1,68 @@
+=======================
+org.bluez.NetworkServer
+=======================
+
+-------------------------------------------
+BlueZ D-Bus NetworkServer API documentation
+-------------------------------------------
+
+:Version: BlueZ
+:Date: October 2023
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.NetworkServer1
+:Object path:	/org/bluez/{hci0,hci1,...}
+
+
+Methods
+-------
+
+void Register(string uuid, string bridge)
+`````````````````````````````````````````
+
+	Registers server for the provided UUID.
+
+	Every new connection to this server will be added the bridge interface.
+
+	Possible uuid values:
+
+	:"panu", "00001115-0000-1000-8000-00805f9b34fb":
+
+		Personal Network User role.
+
+	:"nap", "00001116-0000-1000-8000-00805f9b34fb":
+
+		Network Access Point role.
+
+	:"gn", "00001117-0000-1000-8000-00805f9b34fb":
+
+		Group Network role.
+
+	Initially no network server SDP is provided. Only after this method a
+	SDP record will be available and the BNEP server will be ready for
+	incoming connections.
+
+	Possible errors:
+
+	:org.bluez.Error.InvalidArguments:
+	:org.bluez.Error.AlreadyExists:
+	:org.bluez.Error.Failed:
+
+void Unregister(string uuid)
+````````````````````````````
+
+	Unregisters the server for provided UUID which was previously
+	registered with **Register()** method.
+
+	All servers will be automatically unregistered when the calling
+	application terminates.
+
+	Possible errors:
+
+	:org.bluez.Error.InvalidArguments:
+	:org.bluez.Error.Failed:
-- 
2.41.0