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

oldaccountdeadname · web-flow · commit a1a03fa54bfb · 2022-01-11T10:47:31.000Z
* 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
@@ -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
@@ -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>
