From 9a109a9a11a827b575994ff298de57747a41bed9 Mon Sep 17 00:00:00 2001
From: lincoln auster <lincolnauster@gmail.com>
Date: Tue, 11 Jan 2022 03:47:31 -0700
Subject: [PATCH] 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.

(cherry picked from commit a1a03fa54bfb45315eefaa49ceb38a21aceafde8)
---
 man/sd_bus_message_read.xml       | 18 +++++++++++++++++-
 man/sd_bus_message_read_basic.xml |  6 +++---
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml
index 0b921258dc..aa325f39c2 100644
--- 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 bd5a149a26..55951430e6 100644
--- 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>