doc: reformat the "return value" sections in all man pages

Also fix some more TODOs.

Signed-off-by: Daniel Mack <daniel@zonque.org>

7 files changed, 683 insertions, 629 deletions

diff --git a/doc/kdbus.bus.xml b/doc/kdbus.bus.xml
index 42a140a15a8..92571f62f4e 100644
--- a/doc/kdbus.bus.xml
+++ b/doc/kdbus.bus.xml
@@ -209,48 +209,48 @@ struct kdbus_cmd_make {
       On success, all mentioned ioctl commands return 0.
     </para>
 
-    <para>
-      <varname>KDBUS_CMD_BUS_MAKE</varname> may return the following errors.
-    </para>
+    <refsect2>
+      <title><varname>KDBUS_CMD_BUS_MAKE</varname> may return the following errors</title>
 
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EBADMSG</varname></term>
-        <listitem><para>
-          A mandatory item is missing.
-        </para></listitem>
-      </varlistentry>
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EBADMSG</varname></term>
+          <listitem><para>
+            A mandatory item is missing.
+          </para></listitem>
+        </varlistentry>
 
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          The flags supplied in the <varname>struct kdbus_cmd_make</varname>
-          are invalid or the supplied name does not start with the current
-          UID and a '-'.
-        </para></listitem>
-      </varlistentry>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            The flags supplied in the <varname>struct kdbus_cmd_make</varname>
+            are invalid or the supplied name does not start with the current
+            UID and a '-'.
+          </para></listitem>
+        </varlistentry>
 
-      <varlistentry>
-        <term><varname>-EEXIST</varname></term>
-        <listitem><para>
-          A bus of that name already exists.
-        </para></listitem>
-      </varlistentry>
+        <varlistentry>
+          <term><varname>-EEXIST</varname></term>
+          <listitem><para>
+            A bus of that name already exists.
+          </para></listitem>
+        </varlistentry>
 
-      <varlistentry>
-        <term><varname>-ESHUTDOWN</varname></term>
-        <listitem><para>
-          The kdbus mount instance for the bus was already shut down.
-        </para></listitem>
-      </varlistentry>
+        <varlistentry>
+          <term><varname>-ESHUTDOWN</varname></term>
+          <listitem><para>
+            The kdbus mount instance for the bus was already shut down.
+          </para></listitem>
+        </varlistentry>
 
-      <varlistentry>
-        <term><varname>-EMFILE</varname></term>
-        <listitem><para>
-          The maximum number of buses for the current user is exhausted.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
+        <varlistentry>
+          <term><varname>-EMFILE</varname></term>
+          <listitem><para>
+            The maximum number of buses for the current user is exhausted.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
   </refsect1>
 
   <refsect1>
diff --git a/doc/kdbus.connection.xml b/doc/kdbus.connection.xml
index 133022e4ce9..2b2d85e1e0b 100644
--- a/doc/kdbus.connection.xml
+++ b/doc/kdbus.connection.xml
@@ -241,7 +241,11 @@ struct kdbus_cmd_hello {
         <term><varname>attach_flags_recv</varname></term>
         <listitem><para>
           Request the attachment of metadata for each message received by this
-          connection. See XXX TODO XXX for more details.
+          connection. See
+          <citerefentry><refentrytitle>kdbus</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+          for information about metadata, and
+          <citerefentry><refentrytitle>kdbus.item</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+          regarding items in general.
         </para></listitem>
       </varlistentry>
 
@@ -317,7 +321,9 @@ struct kdbus_cmd_hello {
               <listitem>
                 <para>
                   For activators and policy holders only, combinations of
-                  these two items describe policy access entries. See XXX TODO XXX.
+                  these two items describe policy access entries. See
+                  <citerefentry><refentrytitle>kdbus.policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                  for further details.
                 </para>
               </listitem>
             </varlistentry>
@@ -807,152 +813,164 @@ struct kdbus_cmd_update {
       On success, all metioned ioctl commands return 0.
     </para>
 
-    <para>
-      <varname>KDBUS_CMD_HELLO</varname> may return the following errors.
-    </para>
-
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EFAULT</varname></term>
-        <listitem><para>
-          The supplied pool size was 0 or not a multiple of the page size.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          The flags supplied in <varname>struct kdbus_cmd_make</varname> are
-          invalid, or an illegal combination of
-          <varname>KDBUS_HELLO_MONITOR</varname>,
-          <varname>KDBUS_HELLO_ACTIVATOR</varname> and
-          <varname>KDBUS_HELLO_POLICY_HOLDER</varname> was passed in the flags,
-          or an invalid set of items was supplied.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ECONNREFUSED</varname></term>
-        <listitem><para>
-          The attach_flags_send field did not satisfy the requirements of
-          the bus.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EPERM</varname></term>
-        <listitem><para>
-          A <varname>KDBUS_ITEM_CREDS</varname> items was supplied, but the
-          current user is not privileged.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ESHUTDOWN</varname></term>
-        <listitem><para>
-          The bus you were trying to connect to has already been shut down.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EMFILE</varname></term>
-        <listitem><para>
-          The maximum number of connections on the bus has been reached.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EOPNOTSUPP</varname></term>
-        <listitem><para>
-          The endpoint does not support the connection flags supplied in
-          <varname>struct kdbus_cmd_hello</varname>.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
-
-    <para>
-      <varname>KDBUS_CMD_BYEBYE</varname> may return the following errors.
-    </para>
-
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EALREADY</varname></term>
-        <listitem><para>
-          The connection has already been shut down.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EBUSY</varname></term>
-        <listitem><para>
-          There are still messages queued up in the connection's pool.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
-
-    <para>
-      <varname>KDBUS_CMD_CONN_INFO</varname> may return the following errors.
-    </para>
-
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          Invalid flags, or neither an ID nor a name was provided, or the
-          name is invalid.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ESRCH</varname></term>
-        <listitem><para>
-          Connection lookup by name failed.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ENXIO</varname></term>
-        <listitem><para>
-          No connection with the provided connection ID found.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
-
-    <para>
-      <varname>KDBUS_CMD_CONN_UPDATE</varname> may return the following errors.
-    </para>
-
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          Illegal flags or items.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          Wildcards submitted in policy entries, or illegal sequence
-          of policy items.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EOPNOTSUPP</varname></term>
-        <listitem><para>
-          Operation not supported by connection.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-E2BIG</varname></term>
-        <listitem><para>
-          Too many policy items attached.
-        </para></listitem>
-      </varlistentry>
-
-    </variablelist>
+    <refsect2>
+      <title><varname>KDBUS_CMD_HELLO</varname> may return the following errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EFAULT</varname></term>
+          <listitem><para>
+            The supplied pool size was 0 or not a multiple of the page size.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            The flags supplied in <varname>struct kdbus_cmd_make</varname> are
+            invalid.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            An illegal combination of
+            <varname>KDBUS_HELLO_MONITOR</varname>,
+            <varname>KDBUS_HELLO_ACTIVATOR</varname> and
+            <varname>KDBUS_HELLO_POLICY_HOLDER</varname> was passed in the flags.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            An invalid set of items was supplied.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ECONNREFUSED</varname></term>
+          <listitem><para>
+            The attach_flags_send field did not satisfy the requirements of
+            the bus.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EPERM</varname></term>
+          <listitem><para>
+            A <varname>KDBUS_ITEM_CREDS</varname> items was supplied, but the
+            current user is not privileged.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ESHUTDOWN</varname></term>
+          <listitem><para>
+            The bus you were trying to connect to has already been shut down.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EMFILE</varname></term>
+          <listitem><para>
+            The maximum number of connections on the bus has been reached.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EOPNOTSUPP</varname></term>
+          <listitem><para>
+            The endpoint does not support the connection flags supplied in
+            <varname>struct kdbus_cmd_hello</varname>.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+
+    <refsect2>
+      <title><varname>KDBUS_CMD_BYEBYE</varname> may return the following errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EALREADY</varname></term>
+          <listitem><para>
+            The connection has already been shut down.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EBUSY</varname></term>
+          <listitem><para>
+            There are still messages queued up in the connection's pool.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+
+    <refsect2>
+      <title><varname>KDBUS_CMD_CONN_INFO</varname> may return the following errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            Invalid flags, or neither an ID nor a name was provided, or the
+            name is invalid.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ESRCH</varname></term>
+          <listitem><para>
+            Connection lookup by name failed.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ENXIO</varname></term>
+          <listitem><para>
+            No connection with the provided connection ID found.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+
+    <refsect2>
+      <title><varname>KDBUS_CMD_CONN_UPDATE</varname> may return the following errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            Illegal flags or items.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            Wildcards submitted in policy entries, or illegal sequence
+            of policy items.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EOPNOTSUPP</varname></term>
+          <listitem><para>
+            Operation not supported by connection.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-E2BIG</varname></term>
+          <listitem><para>
+            Too many policy items attached.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
   </refsect1>
 
   <refsect1>
diff --git a/doc/kdbus.endpoint.xml b/doc/kdbus.endpoint.xml
index 7007ae489d7..8ab7540a1f5 100644
--- a/doc/kdbus.endpoint.xml
+++ b/doc/kdbus.endpoint.xml
@@ -259,35 +259,72 @@ struct kdbus_cmd_make {
       On success, all mentioned ioctl commands return 0.
     </para>
 
-    <para>
-      <varname>KDBUS_CMD_ENDPOINT_MAKE</varname> may return the following errors.
-    </para>
+    <refsect2>
+      <title><varname>KDBUS_CMD_ENDPOINT_MAKE</varname> may return the following errors</title>
 
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          The flags supplied in the <varname>struct kdbus_cmd_make</varname>
-          are invalid.
-        </para></listitem>
-      </varlistentry>
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            The flags supplied in the <varname>struct kdbus_cmd_make</varname>
+            are invalid.
+          </para></listitem>
+        </varlistentry>
 
-      <varlistentry>
-        <term><varname>-EEXIST</varname></term>
-        <listitem><para>
-          An endpoint of that name already exists.
-        </para></listitem>
-      </varlistentry>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            Illegal combination of <varname>KDBUS_ITEM_NAME</varname> and
+            <varname>KDBUS_ITEM_POLICY_ACCESS</varname> was provided.
+          </para></listitem>
+        </varlistentry>
 
-      <varlistentry>
-        <term><varname>-EPERM</varname></term>
-        <listitem><para>
-          The calling user is not privileged. See
-          <citerefentry><refentrytitle>kdbus</refentrytitle><manvolnum>7</manvolnum></citerefentry>
-          for information about privileged users.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
+        <varlistentry>
+          <term><varname>-EEXIST</varname></term>
+          <listitem><para>
+            An endpoint of that name already exists.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EPERM</varname></term>
+          <listitem><para>
+            The calling user is not privileged. See
+            <citerefentry><refentrytitle>kdbus</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+            for information about privileged users.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+
+    <refsect2>
+      <title><varname>KDBUS_CMD_ENDPOINT_UPDATE</varname> may return the following errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            The flags supplied in the <varname>struct kdbus_cmd_update</varname>
+            are invalid.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            Illegal combination of <varname>KDBUS_ITEM_NAME</varname> and
+            <varname>KDBUS_ITEM_POLICY_ACCESS</varname> was provided.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EEXIST</varname></term>
+          <listitem><para>
+            An endpoint of that name already exists.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
   </refsect1>
 
   <refsect1>
diff --git a/doc/kdbus.match.xml b/doc/kdbus.match.xml
index 647eb2faf75..e260fdd6a2a 100644
--- a/doc/kdbus.match.xml
+++ b/doc/kdbus.match.xml
@@ -400,52 +400,52 @@ struct kdbus_cmd_match {
       On success, all mentioned ioctl commands return 0.
     </para>
 
-    <para>
-      <varname>KDBUS_CMD_MATCH_ADD</varname> may return the following errors.
-    </para>
-
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          Illegal flags or items.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EDOM</varname></term>
-        <listitem><para>
-          Illegal bloom filter size.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EMFILE</varname></term>
-        <listitem><para>
-          Too many matches for this connection.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
-
-    <para>
-      <varname>KDBUS_CMD_MATCH_REMOVE</varname> may return the following errors.
-    </para>
-
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          Illegal flags.
-        </para></listitem>
-      </varlistentry>
+    <refsect2>
+      <title><varname>KDBUS_CMD_MATCH_ADD</varname> may return the following errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            Illegal flags or items.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EDOM</varname></term>
+          <listitem><para>
+            Illegal bloom filter size.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EMFILE</varname></term>
+          <listitem><para>
+            Too many matches for this connection.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
 
-      <varlistentry>
-        <term><varname>-EBADSLT</varname></term>
-        <listitem><para>
-          A match entry with the given cookie could not be found.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
+    <refsect2>
+      <title><varname>KDBUS_CMD_MATCH_REMOVE</varname> may return the following errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            Illegal flags.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EBADSLT</varname></term>
+          <listitem><para>
+            A match entry with the given cookie could not be found.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
   </refsect1>
 
   <refsect1>
diff --git a/doc/kdbus.message.xml b/doc/kdbus.message.xml
index 4e759152eae..3482961a5da 100644
--- a/doc/kdbus.message.xml
+++ b/doc/kdbus.message.xml
@@ -756,265 +756,265 @@ struct kdbus_msg_info {
       On success, all metioned ioctl commands return 0.
     </para>
 
-    <para>
-      <varname>KDBUS_CMD_SEND</varname> may return the following errors.
-    </para>
-
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EOPNOTSUPP</varname></term>
-        <listitem><para>
-          The connection is not an ordinary connection, or the passed
-          file descriptors are either kdbus handles or unix domain
-          sockets. Both are currently unsupported.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          The submitted payload type is <varname>KDBUS_PAYLOAD_KERNEL</varname>,
-          <varname>KDBUS_MSG_EXPECT_REPLY</varname> was set without timeout or
-          cookie values, <varname>KDBUS_SEND_SYNC_REPLY</varname> was set
-          without <varname>KDBUS_MSG_EXPECT_REPLY</varname>, an invalid item
-          was supplied, <varname>src_id</varname> was non-zero and was
-          different from the current connection's ID, a supplied memfd had a
-          size of 0, or a string was not properly null-terminated.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ENOTUNIQ</varname></term>
-        <listitem><para>
-          The supplied destination is <varname>KDBUS_DST_ID_BROADCAST</varname>,
-          a file descriptor was passed, <varname>KDBUS_MSG_EXPECT_REPLY</varname>
-          was set, or a timeout was given for a broadcast message.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-E2BIG</varname></term>
-        <listitem><para>
-          Too many items
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EMSGSIZE</varname></term>
-        <listitem><para>
-          The size of the message header and items or the payload vector
-          is excessive.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EEXIST</varname></term>
-        <listitem><para>
-          Multiple <varname>KDBUS_ITEM_FDS</varname>,
-          <varname>KDBUS_ITEM_BLOOM_FILTER</varname> or
-          <varname>KDBUS_ITEM_DST_NAME</varname> items were supplied.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EBADF</varname></term>
-        <listitem><para>
-          The supplied <varname>KDBUS_ITEM_FDS</varname> or
-          <varname>KDBUS_ITEM_PAYLOAD_MEMFD</varname> items
-          contained an illegal file descriptor.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EMEDIUMTYPE</varname></term>
-        <listitem><para>
-          The supplied memfd is not a sealed kdbus memfd.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EMFILE</varname></term>
-        <listitem><para>
-          Too many file descriptors inside a <varname>KDBUS_ITEM_FDS</varname>.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EBADMSG</varname></term>
-        <listitem><para>
-          An item had illegal size, both a <varname>dst_id</varname> and a
-          <varname>KDBUS_ITEM_DST_NAME</varname> was given, or both a name
-          and a bloom filter was given.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ETXTBSY</varname></term>
-        <listitem><para>
-          The supplied kdbus memfd file cannot be sealed or the seal
-          was removed, because it is shared with other processes or
-          still mapped with
-          <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ECOMM</varname></term>
-        <listitem><para>
-          A peer does not accept the file descriptors addressed to it.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EFAULT</varname></term>
-        <listitem><para>
-          The supplied bloom filter size was not 64-bit aligned or memory
-          supplied by userspace could not be accessed by the kernel.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EDOM</varname></term>
-        <listitem><para>
-          The supplied bloom filter size did not match the bloom filter
-          size of the bus.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EDESTADDRREQ</varname></term>
-        <listitem><para>
-          <varname>dst_id</varname> was set to
-          <varname>KDBUS_DST_ID_NAME</varname>, but no
-          <varname>KDBUS_ITEM_DST_NAME</varname> was attached.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ESRCH</varname></term>
-        <listitem><para>
-          The name to look up was not found in the name registry.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EADDRNOTAVAIL</varname></term>
-        <listitem><para>
-          <varname>KDBUS_MSG_NO_AUTO_START</varname> was given but the
-          destination connection is an activator.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ENXIO</varname></term>
-        <listitem><para>
-          The passed numeric destination connection ID couldn't be found,
-          or is not connected.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ECONNRESET</varname></term>
-        <listitem><para>
-          The destination connection is no longer active.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ETIMEDOUT</varname></term>
-        <listitem><para>
-          Timeout while synchronously waiting for a reply.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EINTR</varname></term>
-        <listitem><para>
-          Interrupted system call  while synchronously waiting for a reply.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EPIPE</varname></term>
-        <listitem><para>
-          When sending a message, a synchronous reply from the receiving
-          connection was expected but the connection died before answering.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ENOBUFS</varname></term>
-        <listitem><para>
-          Too many pending messages on the receiver side.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EREMCHG</varname></term>
-        <listitem><para>
-          Both a well-known name and a unique name (ID) was given, but
-          the name is not currently owned by that connection.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EXFULL</varname></term>
-        <listitem><para>
-          The memory pool of the receiver is full.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EREMOTEIO</varname></term>
-        <listitem><para>
-          While synchronously waiting for a reply, the remote peer
-          failed with an I/O error.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
-
-    <para>
-      <varname>KDBUS_CMD_RECV</varname> may return the following errors.
-    </para>
-
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EOPNOTSUPP</varname></term>
-        <listitem><para>
-          The connection is not an ordinary connection, or the passed
-          file descriptors are either kdbus handles or unix domain
-          sockets. Both are currently unsupported.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          Invalid flags or offset.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EAGAIN</varname></term>
-        <listitem><para>
-          No message found in the queue
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ENOMSG</varname></term>
-        <listitem><para>
-          No message of the requested priority found.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EOVERFLOW</varname></term>
-        <listitem><para>
-          Some messages have been lost.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
+    <refsect2>
+      <title><varname>KDBUS_CMD_SEND</varname> may return the following errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EOPNOTSUPP</varname></term>
+          <listitem><para>
+            The connection is not an ordinary connection, or the passed
+            file descriptors are either kdbus handles or unix domain
+            sockets. Both are currently unsupported.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            The submitted payload type is <varname>KDBUS_PAYLOAD_KERNEL</varname>,
+            <varname>KDBUS_MSG_EXPECT_REPLY</varname> was set without timeout or
+            cookie values, <varname>KDBUS_SEND_SYNC_REPLY</varname> was set
+            without <varname>KDBUS_MSG_EXPECT_REPLY</varname>, an invalid item
+            was supplied, <varname>src_id</varname> was non-zero and was
+            different from the current connection's ID, a supplied memfd had a
+            size of 0, or a string was not properly null-terminated.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ENOTUNIQ</varname></term>
+          <listitem><para>
+            The supplied destination is <varname>KDBUS_DST_ID_BROADCAST</varname>,
+            a file descriptor was passed, <varname>KDBUS_MSG_EXPECT_REPLY</varname>
+            was set, or a timeout was given for a broadcast message.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-E2BIG</varname></term>
+          <listitem><para>
+            Too many items
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EMSGSIZE</varname></term>
+          <listitem><para>
+            The size of the message header and items or the payload vector
+            is excessive.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EEXIST</varname></term>
+          <listitem><para>
+            Multiple <varname>KDBUS_ITEM_FDS</varname>,
+            <varname>KDBUS_ITEM_BLOOM_FILTER</varname> or
+            <varname>KDBUS_ITEM_DST_NAME</varname> items were supplied.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EBADF</varname></term>
+          <listitem><para>
+            The supplied <varname>KDBUS_ITEM_FDS</varname> or
+            <varname>KDBUS_ITEM_PAYLOAD_MEMFD</varname> items
+            contained an illegal file descriptor.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EMEDIUMTYPE</varname></term>
+          <listitem><para>
+            The supplied memfd is not a sealed kdbus memfd.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EMFILE</varname></term>
+          <listitem><para>
+            Too many file descriptors inside a <varname>KDBUS_ITEM_FDS</varname>.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EBADMSG</varname></term>
+          <listitem><para>
+            An item had illegal size, both a <varname>dst_id</varname> and a
+            <varname>KDBUS_ITEM_DST_NAME</varname> was given, or both a name
+            and a bloom filter was given.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ETXTBSY</varname></term>
+          <listitem><para>
+            The supplied kdbus memfd file cannot be sealed or the seal
+            was removed, because it is shared with other processes or
+            still mapped with
+            <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ECOMM</varname></term>
+          <listitem><para>
+            A peer does not accept the file descriptors addressed to it.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EFAULT</varname></term>
+          <listitem><para>
+            The supplied bloom filter size was not 64-bit aligned or memory
+            supplied by userspace could not be accessed by the kernel.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EDOM</varname></term>
+          <listitem><para>
+            The supplied bloom filter size did not match the bloom filter
+            size of the bus.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EDESTADDRREQ</varname></term>
+          <listitem><para>
+            <varname>dst_id</varname> was set to
+            <varname>KDBUS_DST_ID_NAME</varname>, but no
+            <varname>KDBUS_ITEM_DST_NAME</varname> was attached.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ESRCH</varname></term>
+          <listitem><para>
+            The name to look up was not found in the name registry.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EADDRNOTAVAIL</varname></term>
+          <listitem><para>
+            <varname>KDBUS_MSG_NO_AUTO_START</varname> was given but the
+            destination connection is an activator.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ENXIO</varname></term>
+          <listitem><para>
+            The passed numeric destination connection ID couldn't be found,
+            or is not connected.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ECONNRESET</varname></term>
+          <listitem><para>
+            The destination connection is no longer active.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ETIMEDOUT</varname></term>
+          <listitem><para>
+            Timeout while synchronously waiting for a reply.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EINTR</varname></term>
+          <listitem><para>
+            Interrupted system call  while synchronously waiting for a reply.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EPIPE</varname></term>
+          <listitem><para>
+            When sending a message, a synchronous reply from the receiving
+            connection was expected but the connection died before answering.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ENOBUFS</varname></term>
+          <listitem><para>
+            Too many pending messages on the receiver side.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EREMCHG</varname></term>
+          <listitem><para>
+            Both a well-known name and a unique name (ID) was given, but
+            the name is not currently owned by that connection.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EXFULL</varname></term>
+          <listitem><para>
+            The memory pool of the receiver is full.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EREMOTEIO</varname></term>
+          <listitem><para>
+            While synchronously waiting for a reply, the remote peer
+            failed with an I/O error.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+
+    <refsect2>
+      <title><varname>KDBUS_CMD_RECV</varname> may return the following errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EOPNOTSUPP</varname></term>
+          <listitem><para>
+            The connection is not an ordinary connection, or the passed
+            file descriptors are either kdbus handles or unix domain
+            sockets. Both are currently unsupported.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            Invalid flags or offset.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EAGAIN</varname></term>
+          <listitem><para>
+            No message found in the queue
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ENOMSG</varname></term>
+          <listitem><para>
+            No message of the requested priority found.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EOVERFLOW</varname></term>
+          <listitem><para>
+            Some messages have been lost.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
   </refsect1>
 
   <refsect1>
diff --git a/doc/kdbus.names.xml b/doc/kdbus.names.xml
index f2c4c63fb88..09f0c7a683c 100644
--- a/doc/kdbus.names.xml
+++ b/doc/kdbus.names.xml
@@ -479,95 +479,94 @@ struct kdbus_name_info {
       On success, all metioned ioctl commands return 0.
     </para>
 
-    <para>
-      <varname>KDBUS_CMD_NAME_ACQUIRE</varname> may return the following errors.
-    </para>
-
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          Illegal command flags, illegal name provided, or an activator
-          tried to acquire a second name.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EPERM</varname></term>
-        <listitem><para>
-          Policy prohibited name ownership.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EALREADY</varname></term>
-        <listitem><para>
-          Connection already owns that name.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EEXIST</varname></term>
-        <listitem><para>
-          The name already exists and can not be taken over.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-E2BIG</varname></term>
-        <listitem><para>
-          The maximum number of well-known names per connection is exhausted.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
-
-    <para>
-      <varname>KDBUS_CMD_NAME_RELEASE</varname> may return the following errors.
-    </para>
-
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          Invalid command flags, or invalid name provided.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ESRCH</varname></term>
-        <listitem><para>
-          Name is not found in the registry.
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-EADDRINUSE</varname></term>
-        <listitem><para>
-          Name is owned by a different connection and can't be released.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
-
-    <para>
-      <varname>KDBUS_CMD_NAME_LIST</varname> may return the following errors.
-    </para>
-
-    <variablelist>
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          Invalid command flags
-        </para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><varname>-ENOBUFS</varname></term>
-        <listitem><para>
-          No available memory in the connection's pool.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
-
+    <refsect2>
+      <title><varname>KDBUS_CMD_NAME_ACQUIRE</varname> may return the following errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            Illegal command flags, illegal name provided, or an activator
+            tried to acquire a second name.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EPERM</varname></term>
+          <listitem><para>
+            Policy prohibited name ownership.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EALREADY</varname></term>
+          <listitem><para>
+            Connection already owns that name.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EEXIST</varname></term>
+          <listitem><para>
+            The name already exists and can not be taken over.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-E2BIG</varname></term>
+          <listitem><para>
+            The maximum number of well-known names per connection is exhausted.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+
+    <refsect2>
+      <title><varname>KDBUS_CMD_NAME_RELEASE</varname> may return the following errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            Invalid command flags, or invalid name provided.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ESRCH</varname></term>
+          <listitem><para>
+            Name is not found in the registry.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-EADDRINUSE</varname></term>
+          <listitem><para>
+            Name is owned by a different connection and can't be released.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+
+    <refsect2>
+      <title><varname>KDBUS_CMD_NAME_LIST</varname> may return the following errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            Invalid command flags
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>-ENOBUFS</varname></term>
+          <listitem><para>
+            No available memory in the connection's pool.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
   </refsect1>
 
   <refsect1>
diff --git a/doc/kdbus.pool.xml b/doc/kdbus.pool.xml
index 167727fec43..73957206823 100644
--- a/doc/kdbus.pool.xml
+++ b/doc/kdbus.pool.xml
@@ -163,34 +163,34 @@ struct kdbus_cmd_free {
       On success, all metioned ioctl commands return 0.
     </para>
 
-    <para>
-      <varname>KDBUS_CMD_FREE</varname> may return the following errors.
-    </para>
+    <refsect2>
+      <title><varname>KDBUS_CMD_FREE</varname> may return the following errors</title>
 
-    <variablelist>
-      <varlistentry>
-        <term><varname>-ENXIO</varname></term>
-        <listitem><para>
-          No pool slice found at given offset.
-        </para></listitem>
-      </varlistentry>
+      <variablelist>
+        <varlistentry>
+          <term><varname>-ENXIO</varname></term>
+          <listitem><para>
+            No pool slice found at given offset.
+          </para></listitem>
+        </varlistentry>
 
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          Invalid flags provided.
-        </para></listitem>
-      </varlistentry>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            Invalid flags provided.
+          </para></listitem>
+        </varlistentry>
 
-      <varlistentry>
-        <term><varname>-EINVAL</varname></term>
-        <listitem><para>
-          The offset is valid, but the user is not allowed to free the slice.
-          This happens, for example, if the offset was retrieved with
-          <varname>KDBUS_RECV_PEEK</varname>.
-        </para></listitem>
-      </varlistentry>
-    </variablelist>
+        <varlistentry>
+          <term><varname>-EINVAL</varname></term>
+          <listitem><para>
+            The offset is valid, but the user is not allowed to free the slice.
+            This happens, for example, if the offset was retrieved with
+            <varname>KDBUS_RECV_PEEK</varname>.
+          </para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
   </refsect1>
 
   <refsect1>