man: document *_with_description functions

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 6cb2e7ffb11d0bd4f0b6f4833872799feb40e690..8a69d046bf6d67f7da975ef6473d0e078e082b9d 100644 (file)
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -166,7 +166,10 @@ manpages = [
    'sd_bus_open_system',
    'sd_bus_open_system_machine',
    'sd_bus_open_system_remote',
-   'sd_bus_open_user'],
+   'sd_bus_open_system_with_description',
+   'sd_bus_open_user',
+   'sd_bus_open_user_with_description',
+   'sd_bus_open_with_description'],
   ''],
  ['sd_bus_error',
   '3',

diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml
index 0d3532f3c778948696656fbf739ea2b25a48ad04..73ad568b916642082ac23a1689977792e75f93da 100644 (file)
--- a/man/sd_bus_default.xml
+++ b/man/sd_bus_default.xml
@@ -24,8 +24,11 @@
     <refname>sd_bus_default_system</refname>
 
     <refname>sd_bus_open</refname>
+    <refname>sd_bus_open_with_description</refname>
     <refname>sd_bus_open_user</refname>
+    <refname>sd_bus_open_user_with_description</refname>
     <refname>sd_bus_open_system</refname>
+    <refname>sd_bus_open_system_with_description</refname>
     <refname>sd_bus_open_system_remote</refname>
     <refname>sd_bus_open_system_machine</refname>
 
@@ -56,16 +59,34 @@
         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_bus_open_with_description</function></funcdef>
+        <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
+        <paramdef>const char *<parameter>description</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_bus_open_user</function></funcdef>
         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_bus_open_user_with_description</function></funcdef>
+        <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
+        <paramdef>const char *<parameter>description</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_bus_open_system</function></funcdef>
         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_bus_open_system_with_description</function></funcdef>
+        <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
+        <paramdef>const char *<parameter>description</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_bus_open_system_remote</function></funcdef>
         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
@@ -126,6 +147,20 @@
     <function>sd_bus_default_system()</function> to connect to the
     user or system buses.</para>
 
+    <para><function>sd_bus_open_with_description()</function>,
+    <function>sd_bus_open_user_with_description()</function>, and
+    <function>sd_bus_open_system_with_description()</function> are similar to
+    <function>sd_bus_open()</function>, <function>sd_bus_open_user()</function>, and
+    <function>sd_bus_open_system()</function>, but allow a description string to be set, see
+    <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    <parameter>description</parameter> may be <constant>NULL</constant>, in which case this function
+    is equivalent to <function>sd_bus_open()</function>. This description string is used in log
+    messages about the bus object, and including a "name" for the bus makes them easier to
+    understand. Some messages are emitted during bus initialization, hence using this function is
+    prefereable to setting the description later with
+    <function>sd_bus_open_with_description()</function>. The argument is copied internally and will
+    not be referenced after the function returns.</para>
+
     <para>If the <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment
     variable is set
     (cf. <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>),