man: fix incorrectly placed full stop

[thirdparty/systemd.git] / man / sd_bus_message_new_method_call.xml

diff --git a/man/sd_bus_message_new_method_call.xml b/man/sd_bus_message_new_method_call.xml
index c643177ba47b73a5e87cf9d593de58731389816c..cfb13af51fafec2da1834d6f178c6d9618a462d3 100644 (file)
--- a/man/sd_bus_message_new_method_call.xml
+++ b/man/sd_bus_message_new_method_call.xml
@@ -1,6 +1,6 @@
 <?xml version='1.0'?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
 
 <refentry id="sd_bus_message_new_method_call"
@@ -28,7 +28,7 @@
       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
 
       <funcprototype>
-        <funcdef>int sd_bus_message_new_method_call</funcdef>
+        <funcdef>int <function>sd_bus_message_new_method_call</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
         <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
         <paramdef>const char *<parameter>destination</parameter></paramdef>
@@ -38,7 +38,7 @@
       </funcprototype>
 
       <funcprototype>
-        <funcdef>int sd_bus_message_new_method_return</funcdef>
+        <funcdef>int <function>sd_bus_message_new_method_return</function></funcdef>
         <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
         <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
       </funcprototype>
@@ -70,7 +70,11 @@
     has only a single member with the given name and there is no ambiguity if the interface name is
     omitted.</para>
 
-    <para>The <function>sd_bus_message_new_method_call()</function> function creates a new bus
+    <para>Note that this is a low level interface. See
+    <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    for a more convenient way of calling D-Bus methods.</para>
+
+    <para>The <function>sd_bus_message_new_method_return()</function> function creates a new bus
     message object that is a reply to the method call <parameter>call</parameter> and returns it in
     the <parameter>m</parameter> output parameter. The <parameter>call</parameter> parameter must be
     a method call message. The sender of <parameter>call</parameter> is used as the destination.
@@ -80,62 +84,62 @@
   <refsect1>
     <title>Return Value</title>
 
-    <para>This function returns 0 if the message object was successfully created, and a negative
-    errno-style error code otherwise.</para>
-  </refsect1>
+    <para>On success, these functions return a non-negative integer. On failure, they return a
+    negative errno-style error code.</para>
 
-  <refsect1 id='errors'>
-    <title>Errors</title>
+    <refsect2 id='errors'>
+      <title>Errors</title>
 
-    <para>Returned errors may indicate the following problems:</para>
+      <para>Returned errors may indicate the following problems:</para>
 
-    <variablelist>
-      <varlistentry>
-        <term><constant>-EINVAL</constant></term>
+      <variablelist>
+        <varlistentry>
+          <term><constant>-EINVAL</constant></term>
 
-        <listitem><para>The output parameter <parameter>m</parameter> is
-        <constant>NULL</constant>.</para>
+          <listitem><para>The output parameter <parameter>m</parameter> is
+          <constant>NULL</constant>.</para>
 
-        <para>The <parameter>destination</parameter> parameter is non-null and is not a valid D-Bus
-        service name (<literal>org.somewhere.Something</literal>), the <parameter>path</parameter>
-        parameter is not a valid D-Bus path (<literal>/an/object/path</literal>), the
-        <parameter>interface</parameter> parameter is non-null and is not a valid D-Bus interface
-        name (<literal>an.interface.name</literal>), or the <parameter>member</parameter> parameter
-        is not a valid D-Bus member (<literal>Name</literal>).</para>
+          <para>The <parameter>destination</parameter> parameter is non-null and is not a valid D-Bus
+          service name (<literal>org.somewhere.Something</literal>), the <parameter>path</parameter>
+          parameter is not a valid D-Bus path (<literal>/an/object/path</literal>), the
+          <parameter>interface</parameter> parameter is non-null and is not a valid D-Bus interface
+          name (<literal>an.interface.name</literal>), or the <parameter>member</parameter> parameter
+          is not a valid D-Bus member (<literal>Name</literal>).</para>
 
-        <para>The <parameter>call</parameter> parameter is not a method call object.</para>
-        </listitem>
-      </varlistentry>
+          <para>The <parameter>call</parameter> parameter is not a method call object.</para>
+          </listitem>
+        </varlistentry>
 
-      <varlistentry>
-        <term><constant>-ENOTCONN</constant></term>
+        <varlistentry>
+          <term><constant>-ENOTCONN</constant></term>
 
-        <listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or
-        the bus is not connected.</para></listitem>
-      </varlistentry>
+          <listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or
+          the bus is not connected.</para></listitem>
+        </varlistentry>
 
-      <varlistentry>
-        <term><constant>-ENOMEM</constant></term>
+        <varlistentry>
+          <term><constant>-ENOMEM</constant></term>
 
-        <listitem><para>Memory allocation failed.</para></listitem>
-      </varlistentry>
+          <listitem><para>Memory allocation failed.</para></listitem>
+        </varlistentry>
 
-      <varlistentry>
-        <term><constant>-EPERM</constant></term>
+        <varlistentry>
+          <term><constant>-EPERM</constant></term>
 
-        <listitem>
-        <para>The <parameter>call</parameter> parameter is not sealed.</para>
-        </listitem>
-      </varlistentry>
+          <listitem>
+            <para>The <parameter>call</parameter> parameter is not sealed.</para>
+          </listitem>
+        </varlistentry>
 
-      <varlistentry>
-        <term><constant>-EOPNOTSUPP</constant></term>
+        <varlistentry>
+          <term><constant>-EOPNOTSUPP</constant></term>
 
-        <listitem>
-        <para>The <parameter>call</parameter> message does not have a cookie.</para>
-        </listitem>
-      </varlistentry>
-    </variablelist>
+          <listitem>
+            <para>The <parameter>call</parameter> message does not have a cookie.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
   </refsect1>
 
   <xi:include href="libsystemd-pkgconfig.xml" />
@@ -159,6 +163,8 @@
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     </para>
   </refsect1>