From fe9ef5e1514dc7755a57769f8683dabce49f1120 Mon Sep 17 00:00:00 2001
From: Lubomir Rintel <lkundrak@v3.sk>
Date: Fri, 18 Mar 2022 15:38:05 +0100
Subject: [PATCH] introspection: unbreak o.fd.NM.Settings AddConnection2()
 docstring

There has been a lot wrong with this one. Aside from the messy
capitalization, it broke the argument documentation into multiple lines,
baffling gdbus-codegen, which, in turn, generated garbage documentation.

Overhaul it.
---
 ...rg.freedesktop.NetworkManager.Settings.xml | 48 ++++++++++++-------
 1 file changed, 32 insertions(+), 16 deletions(-)

diff --git a/introspection/org.freedesktop.NetworkManager.Settings.xml b/introspection/org.freedesktop.NetworkManager.Settings.xml
index e0d5b7d176..ace4011b53 100644
--- a/introspection/org.freedesktop.NetworkManager.Settings.xml
+++ b/introspection/org.freedesktop.NetworkManager.Settings.xml
@@ -66,28 +66,44 @@
     <!--
         AddConnection2:
         @settings: New connection settings, properties, and (optionally) secrets.
-        @flags: optional flags argument. Currently, the following flags are supported:
-          "0x1" (to-disk),
-          "0x2" (in-memory),
-          "0x20" (block-autoconnect).
-          Unknown flags cause the call to fail.
-        @args: optional arguments dictionary, for extentibility. Currently, no
-          arguments are accepted. Specifying unknown keys causes the call
-          to fail.
+        @flags: Flags. Unknown flags cause the call to fail.
+        @args: Optional arguments dictionary, for extentibility. Currently, no arguments are accepted. Specifying unknown keys causes the call to fail.
         @path: Object path of the new connection that was just added.
-        @result: output argument, currently no additional results are returned.
+        @result: Output argument, currently no additional results are returned.
         @since: 1.20
 
         Add a new connection profile.
 
-        Either the flags 0x1 (to-disk) or 0x2 (in-memory) must be specified.
-        The effect is whether to behave like AddConnection or AddConnectionUnsaved.
-        If 0x20 (block-autoconnect) is specified, autoconnect for the new profile
-        is blocked from the beginning. Otherwise, the profile might automatically
-        connect if a suitable device is around.
-
-        AddConnection2 is a extensible alternative to AddConnection, and AddConnectionUnsaved.
+        AddConnection2 is an alternative to
+        <link linkend="gdbus-method-org-freedesktop-NetworkManager-Settings.AddConnection">AddConnection</link> and
+        <link linkend="gdbus-method-org-freedesktop-NetworkManager-Settings.AddConnectionUnsaved">AddConnectionUnsaved</link>.
         The new variant can do everything that the older variants could, and more.
+        Its behavior is extensible via extra %flags and %args arguments.
+
+        The %flags argument accepts the combination of following values,
+        logically or-ed together:
+
+        <variablelist>
+        <varlistentry>
+          <term><literal>0x1 (to-disk)</literal>:</term>
+          <listitem><para>The connection is persisted to disk.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>0x2 (in-memory)</literal>:</term>
+          <listitem><para>The change is only made in memory (without touching an eventual
+          profile on disk). If neither 0x1 nor 0x2 is set, the change is made in memory
+          only, if the connection is already in memory only.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>0x20 (block-autoconnect)</literal>:</term>
+          <listitem><para>Blocks auto-connect on the new profile</para></listitem>
+        </varlistentry>
+        </variablelist>
+
+        Either the flags 0x1 (to-disk) or 0x2 (in-memory) must be specified.
+        The effect is whether to behave like
+        <link linkend="gdbus-method-org-freedesktop-NetworkManager-Settings.AddConnection">AddConnection</link> or
+        <link linkend="gdbus-method-org-freedesktop-NetworkManager-Settings.AddConnectionUnsaved">AddConnectionUnsaved</link>.
     -->
     <method name="AddConnection2">
       <arg name="settings" type="a{sa{sv}}" direction="in"/>