sd-bus/man: document EBUSY error in bus_message_read (#21954)

* sd-bus/man: document EBUSY error in bus_message_read

The EBUSY error can be returned from sd_bus_exit_container(), and, if
that happens, it will be propogated upwards towards bus_message_read. In
terms of documentation, this means that bus_message_read's man page
can't just include the error text for sd_bus_message_read_basic, as
reading basic types exclusively doesn't have the potential for this
error.

sd_bus_message_read_basic's error documentation isn't incorrect when
applied to sd_bus_message_read, it's just incomplete.  While EBUSY is
documented in sd_bus_message_open_container.xml,
it's explanation is unique to the sd_bus_message_exit_container function
and makes for poor documentation of the general read API.

diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml
index 0b921258dc555fe2a0f4f2a666dd1139b8ba557e..aa325f39c29ec2412c81ec2d87dbde8b582ef4e7 100644 (file)
--- a/man/sd_bus_message_read.xml
+++ b/man/sd_bus_message_read.xml
@@ -172,7 +172,23 @@
     <para>On success, these functions return a non-negative integer. On failure, they return a negative
     errno-style error code.</para>
 
-    <xi:include href="sd_bus_message_read_basic.xml" xpointer="errors" />
+    <refsect2 id='errors'>
+      <title>Errors</title>
+
+      <para>Returned errors may indicate the following problems:</para>
+
+      <variablelist>
+        <xi:include href="sd_bus_message_read_basic.xml" xpointer="errors-einval"/>
+        <xi:include href="sd_bus_message_read_basic.xml" xpointer="errors-enxio"/>
+        <xi:include href="sd_bus_message_read_basic.xml" xpointer="errors-ebadmsg"/>
+        <varlistentry>
+          <term><constant>-EBUSY</constant></term>
+
+          <listitem><para>When reading from a container, this error will be returned if unread elements
+          are left in the container.</para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
   </refsect1>
 
   <xi:include href="libsystemd-pkgconfig.xml" />

diff --git a/man/sd_bus_message_read_basic.xml b/man/sd_bus_message_read_basic.xml
index bd5a149a2639111ce3936d4c48b82346b87af008..55951430e6e86d2e97d1a1fa21139e80a9cc8a77 100644 (file)
--- a/man/sd_bus_message_read_basic.xml
+++ b/man/sd_bus_message_read_basic.xml
@@ -199,21 +199,21 @@
       <para>Returned errors may indicate the following problems:</para>
 
       <variablelist>
-        <varlistentry>
+        <varlistentry id="errors-einval">
           <term><constant>-EINVAL</constant></term>
 
           <listitem><para>Specified type string is invalid or the message parameter is
           <constant>NULL</constant>.</para></listitem>
         </varlistentry>
 
-        <varlistentry>
+        <varlistentry id="errors-enxio">
           <term><constant>-ENXIO</constant></term>
 
           <listitem><para>The message does not contain the specified type at current position.
           </para></listitem>
         </varlistentry>
 
-        <varlistentry>
+        <varlistentry id="errors-ebadmsg">
           <term><constant>-EBADMSG</constant></term>
 
           <listitem><para>The message cannot be parsed.</para></listitem>