From 1358831d0376fc15773e35773f8d48b8b59de717 Mon Sep 17 00:00:00 2001
From: Lubomir Rintel <lkundrak@v3.sk>
Date: Fri, 18 Mar 2022 14:41:57 +0100
Subject: [PATCH 1/6] introspection: use @since

gdbus-codegen provides a way to specify a version number on various
elements. Use it to instead of a plain text paragraph.
---
 ...sktop.NetworkManager.Connection.Active.xml |  2 +-
 ...reedesktop.NetworkManager.Device.Modem.xml |  6 ++---
 ...esktop.NetworkManager.Device.OvsBridge.xml |  3 +--
 ...edesktop.NetworkManager.Device.OvsPort.xml |  3 +--
 ...edesktop.NetworkManager.Device.WifiP2P.xml | 15 +-----------
 ...desktop.NetworkManager.Device.Wireless.xml |  3 +--
 .../org.freedesktop.NetworkManager.Device.xml | 15 ++++--------
 ...g.freedesktop.NetworkManager.IP4Config.xml |  6 ++---
 ...top.NetworkManager.Settings.Connection.xml |  9 +++-----
 ...rg.freedesktop.NetworkManager.Settings.xml |  3 +--
 ...freedesktop.NetworkManager.WifiP2PPeer.xml | 23 +------------------
 .../org.freedesktop.NetworkManager.xml        |  3 +--
 12 files changed, 21 insertions(+), 70 deletions(-)

diff --git a/introspection/org.freedesktop.NetworkManager.Connection.Active.xml b/introspection/org.freedesktop.NetworkManager.Connection.Active.xml
index 54e1fd9445..fc6ff2600a 100644
--- a/introspection/org.freedesktop.NetworkManager.Connection.Active.xml
+++ b/introspection/org.freedesktop.NetworkManager.Connection.Active.xml
@@ -93,10 +93,10 @@
         StateChanged:
         @state: (<link linkend="NMActiveConnectionState">NMActiveConnectionState</link>) The new state of the active connection.
         @reason: (<link linkend="NMActiveConnectionStateReason">NMActiveConnectionStateReason</link>) Reason code describing the change to the new state.
+        @since: 1.8
 
         Emitted when the state of the active connection has changed.
 
-        Since: 1.8
     -->
     <signal name="StateChanged">
       <arg name="state" type="u"/>
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Modem.xml b/introspection/org.freedesktop.NetworkManager.Device.Modem.xml
index b089bda2de..119a998282 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Modem.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Modem.xml
@@ -30,31 +30,31 @@
 
     <!--
         DeviceId:
+        @since: 1.20
 
         An identifier used by the modem backend (ModemManager) that aims to
         uniquely identify the a device. Can be used to match a connection to a
         particular device.
 
-        Since: 1.20
     -->
     <property name="DeviceId" type="s" access="read" />
 
     <!--
         OperatorCode:
+        @since: 1.20
 
         The MCC and MNC (concatenated) of the network the modem is connected to.
         Blank if disconnected or not a 3GPP modem.
 
-        Since: 1.20
     -->
     <property name="OperatorCode" type="s" access="read" />
 
     <!--
         Apn:
+        @since: 1.20
 
         The access point name the modem is connected to. Blank if disconnected.
 
-        Since: 1.20
     -->
     <property name="Apn" type="s" access="read" />
 
diff --git a/introspection/org.freedesktop.NetworkManager.Device.OvsBridge.xml b/introspection/org.freedesktop.NetworkManager.Device.OvsBridge.xml
index 5970a59d6a..e608cf1d0e 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.OvsBridge.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.OvsBridge.xml
@@ -9,12 +9,11 @@
 
     <!--
         Slaves:
+        @since: 1.14
 
         DEPRECATED. Use the "Ports" property in
         "org.freedesktop.NetworkManager.Device" instead which exists since
         version NetworkManager 1.34.0.
-
-        Since: 1.14
     -->
     <property name="Slaves" type="ao" access="read"/>
 
diff --git a/introspection/org.freedesktop.NetworkManager.Device.OvsPort.xml b/introspection/org.freedesktop.NetworkManager.Device.OvsPort.xml
index 3cd1fa54d6..4919fdf1bd 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.OvsPort.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.OvsPort.xml
@@ -9,12 +9,11 @@
 
     <!--
         Slaves:
+        @since: 1.14
 
         DEPRECATED. Use the "Ports" property in
         "org.freedesktop.NetworkManager.Device" instead which exists since
         version NetworkManager 1.34.0.
-
-        Since: 1.14
     -->
     <property name="Slaves" type="ao" access="read"/>
 
diff --git a/introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml b/introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml
index f5e2fdceaa..5384e3f72e 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml
@@ -3,8 +3,7 @@
   <!--
       org.freedesktop.NetworkManager.Device.WifiP2P:
       @short_description: Wi-Fi P2P Device
-
-      Since: 1.16
+      @since: 1.16
   -->
   <interface name="org.freedesktop.NetworkManager.Device.WifiP2P">
     <annotation name="org.gtk.GDBus.C.Name" value="Device_Wifi_P2P"/>
@@ -15,8 +14,6 @@
         The active hardware address of the device.
 
         DEPRECATED. Use the "HwAddress" property in "org.freedesktop.NetworkManager.Device" instead which exists since version NetworkManager 1.24.0.
-
-        Since: 1.16
     -->
     <property name="HwAddress" type="s" access="read"/>
 
@@ -24,8 +21,6 @@
         Peers:
 
         List of object paths of peers visible to this Wi-Fi P2P device.
-
-        Since: 1.16
     -->
     <property name="Peers" type="ao" access="read"/>
 
@@ -36,8 +31,6 @@
                   30 seconds.
 
         Start a find operation for Wi-Fi P2P peers.
-
-        Since: 1.16
     -->
     <method name="StartFind">
       <arg name="options" type="a{sv}" direction="in"/>
@@ -47,8 +40,6 @@
         StopFind:
 
         Stop an ongoing find operation again.
-
-        Since: 1.16
     -->
     <method name="StopFind">
     </method>
@@ -58,8 +49,6 @@
         @peer: The object path of the newly found access point.
 
         Emitted when a new Wi-Fi P2P peer is found by the device.
-
-        Since: 1.16
     -->
     <signal name="PeerAdded">
       <arg name="peer" type="o"/>
@@ -70,8 +59,6 @@
         @peer: The object path of the Wi-Fi P2P peer that has disappeared.
 
         Emitted when a Wi-Fi P2P peer disappears from view of the device.
-
-        Since: 1.16
     -->
     <signal name="PeerRemoved">
       <arg name="peer" type="o"/>
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml b/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml
index c57e568988..59d4ee9ee5 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml
@@ -100,11 +100,10 @@
 
     <!--
         LastScan:
+        @since: 1.12
 
         The timestamp (in CLOCK_BOOTTIME milliseconds) for the last finished network scan.
         A value of -1 means the device never scanned for access points.
-
-        Since: 1.12
     -->
     <property name="LastScan" type="x" access="read"/>
 
diff --git a/introspection/org.freedesktop.NetworkManager.Device.xml b/introspection/org.freedesktop.NetworkManager.Device.xml
index 82f127edde..b42b5478ee 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.xml
@@ -268,58 +268,53 @@
 
     <!--
         Ip4Connectivity:
+        @since: 1.16
 
         The result of the last IPv4 connectivity check.
 
-        Since: 1.16
-
         Returns: <link linkend="NMConnectivityState">NMConnectivityState</link>
     -->
     <property name="Ip4Connectivity" type="u" access="read"/>
 
     <!--
         Ip6Connectivity:
+        @since: 1.16
 
         The result of the last IPv6 connectivity check.
 
-        Since: 1.16
-
         Returns: <link linkend="NMConnectivityState">NMConnectivityState</link>
     -->
     <property name="Ip6Connectivity" type="u" access="read"/>
 
     <!--
         InterfaceFlags:
+        @since: 1.22
 
         The flags of the network interface. See
         <link linkend="NMDeviceInterfaceFlags">NMDeviceInterfaceFlags</link> for
         the currently defined flags.
-
-        Since: 1.22
     -->
     <property name="InterfaceFlags" type="u" access="read"/>
 
     <!--
         HwAddress:
+        @since: 1.24
 
         The hardware address of the device.
 
         This replaces the other 'HwAddress' properties on the device-specific D-Bus interfaces.
-
-        Since: 1.24
     -->
     <property name="HwAddress" type="s" access="read"/>
 
     <!--
         Ports:
+        @since: 1.34
 
         The port devices of the controller device.
 
         Array of object paths representing devices which are currently set as
         port of this device. This replaces the 'Slaves' properties on the
         device-specific D-Bus interfaces.
-
-        Since: 1.34
     -->
     <property name="Ports" type="ao" access="read"/>
 
diff --git a/introspection/org.freedesktop.NetworkManager.IP4Config.xml b/introspection/org.freedesktop.NetworkManager.IP4Config.xml
index ce659d71fd..75a59bddd8 100644
--- a/introspection/org.freedesktop.NetworkManager.IP4Config.xml
+++ b/introspection/org.freedesktop.NetworkManager.IP4Config.xml
@@ -61,11 +61,10 @@
 
     <!--
         NameserverData:
+        @since: 1.14
 
         The nameservers in use. Currently, only the value "address"
         is recognized (with an IP address string).
-
-        Since: 1.14
     -->
     <property name="NameserverData" type="aa{sv}" access="read"/>
 
@@ -108,10 +107,9 @@
 
     <!--
         WinsServerData:
+        @since: 1.14
 
         The Windows Internet Name Service servers associated with the connection.
-
-        Since: 1.14
     -->
     <property name="WinsServerData" type="as" access="read"/>
 
diff --git a/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml b/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml
index 55bdaff669..db547746ae 100644
--- a/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml
+++ b/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml
@@ -118,6 +118,7 @@
           arguments are accepted. Specifying unknown keys causes the call
           to fail.
         @result: output argument, currently no results are returned.
+        @since: 1.12
 
         Update the connection with new settings and properties (replacing all
         previous settings and properties). If the flag 0x1 is present,
@@ -136,8 +137,6 @@
         associated with each secret.
 
         Update2 is a extensible alternative to Update, UpdateUnsaved and Save.
-
-        Since: 1.12
     -->
     <method name="Update2">
       <arg name="settings" type="a{sa{sv}}" direction="in"/>
@@ -168,21 +167,19 @@
 
     <!--
         Flags:
+        @since: 1.12
 
         Additional flags of the connection profile.
 
         Returns: <link linkend="NMSettingsConnectionFlags">NMSettingsConnectionFlags</link>
-
-        Since: 1.12
     -->
     <property name="Flags" type="u" access="read"/>
 
     <!--
         Filename:
+        @since: 1.12
 
         File that stores the connection in case the connection is file-backed.
-
-        Since: 1.12
     -->
     <property name="Filename" type="s" access="read"/>
 
diff --git a/introspection/org.freedesktop.NetworkManager.Settings.xml b/introspection/org.freedesktop.NetworkManager.Settings.xml
index 28c89ff4f7..e0d5b7d176 100644
--- a/introspection/org.freedesktop.NetworkManager.Settings.xml
+++ b/introspection/org.freedesktop.NetworkManager.Settings.xml
@@ -76,6 +76,7 @@
           to fail.
         @path: Object path of the new connection that was just added.
         @result: output argument, currently no additional results are returned.
+        @since: 1.20
 
         Add a new connection profile.
 
@@ -87,8 +88,6 @@
 
         AddConnection2 is a extensible alternative to AddConnection, and AddConnectionUnsaved.
         The new variant can do everything that the older variants could, and more.
-
-        Since: 1.20
     -->
     <method name="AddConnection2">
       <arg name="settings" type="a{sa{sv}}" direction="in"/>
diff --git a/introspection/org.freedesktop.NetworkManager.WifiP2PPeer.xml b/introspection/org.freedesktop.NetworkManager.WifiP2PPeer.xml
index 760849c3f0..2c7b82df9e 100644
--- a/introspection/org.freedesktop.NetworkManager.WifiP2PPeer.xml
+++ b/introspection/org.freedesktop.NetworkManager.WifiP2PPeer.xml
@@ -3,8 +3,7 @@
   <!--
       org.freedesktop.NetworkManager.WifiP2PPeer:
       @short_description: Wi-Fi P2P Peer
-
-      Since: 1.16
+      @since: 1.16
   -->
   <interface name="org.freedesktop.NetworkManager.WifiP2PPeer">
     <annotation name="org.gtk.GDBus.C.Name" value="Wifi_P2P_Peer"/>
@@ -18,8 +17,6 @@
         Name:
 
         Device name.
-
-        Since: 1.16
     -->
     <property name="Name" type="s" access="read"/>
 
@@ -29,8 +26,6 @@
         Flags describing the capabilities of the access point.
 
         Returns: <link linkend="NM80211ApFlags">NM80211ApFlags</link>
-
-        Since: 1.16
     -->
     <property name="Flags" type="u" access="read"/>
 
@@ -38,8 +33,6 @@
         Manufacturer:
 
         The manufacturer of the Wi-Fi P2P peer.
-
-        Since: 1.16
     -->
     <property name="Manufacturer" type="s" access="read"/>
 
@@ -47,8 +40,6 @@
         Model:
 
         The model of the Wi-Fi P2P peer.
-
-        Since: 1.16
     -->
     <property name="Model" type="s" access="read"/>
 
@@ -56,8 +47,6 @@
         ModelNumber:
 
         The model number of the Wi-Fi P2P peer.
-
-        Since: 1.16
     -->
     <property name="ModelNumber" type="s" access="read"/>
 
@@ -65,8 +54,6 @@
         Serial:
 
         The serial number of the Wi-Fi P2P peer.
-
-        Since: 1.16
     -->
     <property name="Serial" type="s" access="read"/>
 
@@ -74,8 +61,6 @@
         WfdIEs:
 
         The Wi-Fi Display Information Elements of the Wi-Fi P2P peer.
-
-        Since: 1.16
     -->
     <property name="WfdIEs" type="ay" access="read"/>
 
@@ -83,8 +68,6 @@
         HwAddress:
 
         The hardware address (BSSID) of the access point.
-
-        Since: 1.16
     -->
     <property name="HwAddress" type="s" access="read"/>
 
@@ -92,8 +75,6 @@
         Strength:
 
         The current signal quality of the access point, in percent.
-
-        Since: 1.16
     -->
     <property name="Strength" type="y" access="read"/>
 
@@ -103,8 +84,6 @@
         The timestamp (in CLOCK_BOOTTIME seconds) for the last time the access
         point was found in scan results. A value of -1 means the access point has
         never been found in scan results.
-
-        Since: 1.16
     -->
     <property name="LastSeen" type="i" access="read"/>
 
diff --git a/introspection/org.freedesktop.NetworkManager.xml b/introspection/org.freedesktop.NetworkManager.xml
index ff74c5122d..475f329f2c 100644
--- a/introspection/org.freedesktop.NetworkManager.xml
+++ b/introspection/org.freedesktop.NetworkManager.xml
@@ -296,10 +296,9 @@
           will be recalculated to give the approximate new expiration time.
           The new "RollbackTimeout" property will be approximate up to
           one second precision, which is the accuracy of the property.
+        @since: 1.12
 
         Reset the timeout for rollback for the checkpoint.
-
-        Since: 1.12
     -->
     <method name="CheckpointAdjustRollbackTimeout">
       <arg name="checkpoint" type="o" direction="in"/>

From b5715b82b60bb96647e62e7297b20af64ed239c0 Mon Sep 17 00:00:00 2001
From: Lubomir Rintel <lkundrak@v3.sk>
Date: Fri, 18 Mar 2022 15:17:12 +0100
Subject: [PATCH 2/6] introspection: unbreak o.fd.NM.Settings.Connection
 Update2() 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.
---
 ...top.NetworkManager.Settings.Connection.xml | 78 ++++++++++++-------
 1 file changed, 50 insertions(+), 28 deletions(-)

diff --git a/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml b/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml
index db547746ae..4fd94e17b2 100644
--- a/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml
+++ b/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml
@@ -103,40 +103,62 @@
 
     <!--
         Update2:
-        @settings: New connection settings, properties, and (optionally) secrets.
-          Provide an empty array, to use the current settings.
-        @flags: optional flags argument. Currently, supported flags are:
-          "0x1" (to-disk),
-          "0x2" (in-memory),
-          "0x4" (in-memory-detached),
-          "0x8" (in-memory-only),
-          "0x10" (volatile),
-          "0x20" (block-autoconnect),
-          "0x40" (no-reapply).
-          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.
-        @result: output argument, currently no results are returned.
+        @settings: New connection settings, properties, and (optionally) secrets. Provide an empty array to use the current settings.
+        @flags: Optional 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.
+        @result: Currently no results are returned.
         @since: 1.12
 
         Update the connection with new settings and properties (replacing all
-        previous settings and properties). If the flag 0x1 is present,
-        the connection is persisted to disk. If the flag 0x2 is present,
-        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.
-        The flags 0x4 (in-memory-detached) and 0x8 (in-memory-only) are like
-        "in-memory", but behave slightly different when migrating the profile
-        from disk to in-memory.
-        The flag 0x20 (block-autoconnect) blocks auto-connect on the updated
-        profile, and 0x40 (no-reapply) prevents "connection.zone" and "connection.metered"
-        properties to take effect on currently active devices.
+        previous settings and properties).
+
+        Update2 is an alternative to
+        <link linkend="gdbus-method-org-freedesktop-NetworkManager-Settings-Connection.Update">Update</link>,
+        <link linkend="gdbus-method-org-freedesktop-NetworkManager-Settings-Connection.UpdateUnsaved">UpdateUnsaved</link>
+        and <link linkend="gdbus-method-org-freedesktop-NetworkManager-Settings-Connection.Save">Save</link>
+        extensible with 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>0x4 (in-memory-detached)</literal>:</term>
+          <listitem><para>Like "in-memory", but behaves slightly different when migrating
+          the profile from disk to in-memory.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>0x8 (in-memory-only)</literal>:</term>
+          <listitem><para>Like "in-memory", but behaves slightly different when migrating
+          the profile from disk to in-memory.</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>0x10 (volatile)</literal>:</term>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>0x20 (block-autoconnect)</literal>:</term>
+          <listitem><para>Blocks auto-connect on the updated profile</para></listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><literal>0x40 (no-reapply)</literal>:</term>
+          <listitem><para>Prevents "connection.zone" and "connection.metered" properties
+          to take effect on currently active devices.</para></listitem>
+        </varlistentry>
+        </variablelist>
+
         Secrets may be part of the update request, and will be either stored in persistent
         storage or sent to a Secret Agent for storage, depending on the flags
         associated with each secret.
-
-        Update2 is a extensible alternative to Update, UpdateUnsaved and Save.
     -->
     <method name="Update2">
       <arg name="settings" type="a{sa{sv}}" direction="in"/>

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 3/6] 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"/>

From 87d16e7020a0add6996f77887bd233e995520a4b Mon Sep 17 00:00:00 2001
From: Lubomir Rintel <lkundrak@v3.sk>
Date: Fri, 18 Mar 2022 15:39:09 +0100
Subject: [PATCH 4/6] introspection: unbreak o.fd.NM.Device.WifiP2p StartFind()
 docstring

This one attempts to document an option dictionary in a manner that has
been deemed criminal by the high court of gdbus-codegen.

Beat it back into shape.
---
 ...g.freedesktop.NetworkManager.Device.WifiP2P.xml | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml b/introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml
index 5384e3f72e..61e3236e4e 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml
@@ -26,11 +26,19 @@
 
     <!--
         StartFind:
-        @options: Options of find. Currently, 'timeout' option with value of "i"
-                  in the range of 1-600 seconds is supported. The default is
-                  30 seconds.
+        @options: Options of find.
 
         Start a find operation for Wi-Fi P2P peers.
+
+        The %options argument accepts the following keys:
+
+        <variablelist>
+        <varlistentry>
+          <term><literal>i timeout</literal>:</term>
+          <listitem><para>Timeout value in the range of 1-600 seconds.</para>
+          <para>The default is 30 seconds.</para></listitem>
+        </varlistentry>
+        </variablelist>
     -->
     <method name="StartFind">
       <arg name="options" type="a{sv}" direction="in"/>

From d1e73f0ece03529a51ab5d12a85ae6239111d0c8 Mon Sep 17 00:00:00 2001
From: Lubomir Rintel <lkundrak@v3.sk>
Date: Fri, 18 Mar 2022 14:57:08 +0100
Subject: [PATCH 5/6] introspection: unbreak a couple of docstrings

A couple of argument documentation strings were long enough to be broken
up to span over multiple lines. gdbus-codegen, on the other hand, was
of differing opinion and promptly punished the offense by garbling the
resulting docbook.

Merge the string into single lines.
---
 ...rg.freedesktop.NetworkManager.Settings.xml |  5 ++++-
 .../org.freedesktop.NetworkManager.xml        | 22 +++++++++----------
 2 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/introspection/org.freedesktop.NetworkManager.Settings.xml b/introspection/org.freedesktop.NetworkManager.Settings.xml
index ace4011b53..7e6ff802da 100644
--- a/introspection/org.freedesktop.NetworkManager.Settings.xml
+++ b/introspection/org.freedesktop.NetworkManager.Settings.xml
@@ -117,7 +117,6 @@
         LoadConnections:
         @filenames: Array of paths to on-disk connection profiles in directories monitored by NetworkManager.
         @status: Success or failure of the operation as a whole. True if NetworkManager at least tried to load the indicated connections, even if it did not succeed. False if an error occurred before trying to load the connections (eg, permission denied).
-          Note that before 1.20, NetworkManager had a bug and this @status value was wrong. It is better to assume success if the method does not return with a D-Bus error. On top of that, you can look at @failures to know whether any of the requested files failed.
         @failures: Paths of connection files that could not be loaded.
 
         Loads or reloads the indicated connections from disk. You should call this
@@ -125,6 +124,10 @@
         that NetworkManager sees the changes.
         As with AddConnection(), this operation does not necessarily
         start the network connection.
+
+        Note that before 1.20, NetworkManager had a bug and this @status value was wrong.
+        It is better to assume success if the method does not return with a D-Bus error.
+        On top of that, you can look at @failures to know whether any of the requested files failed.
     -->
     <method name="LoadConnections">
       <arg name="filenames" type="as" direction="in"/>
diff --git a/introspection/org.freedesktop.NetworkManager.xml b/introspection/org.freedesktop.NetworkManager.xml
index 475f329f2c..9b5ceb04d7 100644
--- a/introspection/org.freedesktop.NetworkManager.xml
+++ b/introspection/org.freedesktop.NetworkManager.xml
@@ -119,8 +119,7 @@
         @options: Further options for the method call.
         @path: Object path of the new connection that was just added.
         @active_connection: The path of the active connection object representing this active connection.
-        @result: a dictionary of additional output arguments for future extension. Currently, not additional
-          output arguments are supported.
+        @result: a dictionary of additional output arguments for future extension. Currently, not additional output arguments are supported.
 
         Adds a new connection using the given details (if any) as a template
         (automatically filling in missing settings with the capabilities of the
@@ -287,18 +286,19 @@
 
     <!--
         CheckpointAdjustRollbackTimeout:
-        @add_timeout: number of seconds from ~now~ in which the
-          timeout will expire. Set to 0 to disable the timeout.
-          Note that the added seconds start counting from now,
-          not "Created" timestamp or the previous expiration
-          time. Note that the "Created" property of the checkpoint
-          will stay unchanged by this call. However, the "RollbackTimeout"
-          will be recalculated to give the approximate new expiration time.
-          The new "RollbackTimeout" property will be approximate up to
-          one second precision, which is the accuracy of the property.
+        @checkpoint: The checkpoint to be rolled back.
+        @add_timeout: number of seconds from <emphasis>now</emphasis> in which the timeout will expire. Set to 0 to disable the timeout.
         @since: 1.12
 
         Reset the timeout for rollback for the checkpoint.
+
+        Note that the added seconds start counting from now,
+        not "Created" timestamp or the previous expiration
+        time. Note that the "Created" property of the checkpoint
+        will stay unchanged by this call. However, the "RollbackTimeout"
+        will be recalculated to give the approximate new expiration time.
+        The new "RollbackTimeout" property will be approximate up to
+        one second precision, which is the accuracy of the property.
     -->
     <method name="CheckpointAdjustRollbackTimeout">
       <arg name="checkpoint" type="o" direction="in"/>

From 2df493c00d22c2a782985d66376b6592dbfb5be9 Mon Sep 17 00:00:00 2001
From: Lubomir Rintel <lkundrak@v3.sk>
Date: Fri, 18 Mar 2022 15:52:48 +0100
Subject: [PATCH 6/6] introspection: fix punctuation and capitalization

Sentences start with a capital letter and end with a period, even if
they are really really short.
---
 .../org.freedesktop.NetworkManager.AccessPoint.xml        | 2 +-
 .../org.freedesktop.NetworkManager.AgentManager.xml       | 2 +-
 .../org.freedesktop.NetworkManager.Checkpoint.xml         | 2 +-
 .../org.freedesktop.NetworkManager.Connection.Active.xml  | 2 +-
 .../org.freedesktop.NetworkManager.DHCP4Config.xml        | 2 +-
 .../org.freedesktop.NetworkManager.DHCP6Config.xml        | 2 +-
 .../org.freedesktop.NetworkManager.Device.Adsl.xml        | 2 +-
 .../org.freedesktop.NetworkManager.Device.Bluetooth.xml   | 2 +-
 .../org.freedesktop.NetworkManager.Device.Bond.xml        | 2 +-
 .../org.freedesktop.NetworkManager.Device.Bridge.xml      | 2 +-
 .../org.freedesktop.NetworkManager.Device.Dummy.xml       | 2 +-
 .../org.freedesktop.NetworkManager.Device.Generic.xml     | 2 +-
 .../org.freedesktop.NetworkManager.Device.IPTunnel.xml    | 2 +-
 .../org.freedesktop.NetworkManager.Device.Infiniband.xml  | 2 +-
 .../org.freedesktop.NetworkManager.Device.Lowpan.xml      | 2 +-
 .../org.freedesktop.NetworkManager.Device.Macsec.xml      | 2 +-
 .../org.freedesktop.NetworkManager.Device.Macvlan.xml     | 2 +-
 .../org.freedesktop.NetworkManager.Device.Modem.xml       | 2 +-
 .../org.freedesktop.NetworkManager.Device.OlpcMesh.xml    | 2 +-
 .../org.freedesktop.NetworkManager.Device.OvsBridge.xml   | 2 +-
 ...org.freedesktop.NetworkManager.Device.OvsInterface.xml | 2 +-
 .../org.freedesktop.NetworkManager.Device.OvsPort.xml     | 2 +-
 .../org.freedesktop.NetworkManager.Device.Ppp.xml         | 2 +-
 .../org.freedesktop.NetworkManager.Device.Statistics.xml  | 2 +-
 .../org.freedesktop.NetworkManager.Device.Team.xml        | 2 +-
 .../org.freedesktop.NetworkManager.Device.Tun.xml         | 2 +-
 .../org.freedesktop.NetworkManager.Device.Veth.xml        | 2 +-
 .../org.freedesktop.NetworkManager.Device.Vlan.xml        | 2 +-
 .../org.freedesktop.NetworkManager.Device.Vrf.xml         | 2 +-
 .../org.freedesktop.NetworkManager.Device.Vxlan.xml       | 2 +-
 .../org.freedesktop.NetworkManager.Device.WiMax.xml       | 4 ++--
 .../org.freedesktop.NetworkManager.Device.WifiP2P.xml     | 2 +-
 .../org.freedesktop.NetworkManager.Device.WireGuard.xml   | 2 +-
 .../org.freedesktop.NetworkManager.Device.Wired.xml       | 2 +-
 .../org.freedesktop.NetworkManager.Device.Wireless.xml    | 2 +-
 .../org.freedesktop.NetworkManager.Device.Wpan.xml        | 2 +-
 introspection/org.freedesktop.NetworkManager.Device.xml   | 2 +-
 .../org.freedesktop.NetworkManager.DnsManager.xml         | 2 +-
 .../org.freedesktop.NetworkManager.IP4Config.xml          | 2 +-
 .../org.freedesktop.NetworkManager.IP6Config.xml          | 2 +-
 introspection/org.freedesktop.NetworkManager.PPP.xml      | 2 +-
 .../org.freedesktop.NetworkManager.SecretAgent.xml        | 2 +-
 ...org.freedesktop.NetworkManager.Settings.Connection.xml | 2 +-
 introspection/org.freedesktop.NetworkManager.Settings.xml | 2 +-
 .../org.freedesktop.NetworkManager.VPN.Connection.xml     | 2 +-
 .../org.freedesktop.NetworkManager.VPN.Plugin.xml         | 2 +-
 .../org.freedesktop.NetworkManager.WiMax.Nsp.xml          | 2 +-
 .../org.freedesktop.NetworkManager.WifiP2PPeer.xml        | 2 +-
 introspection/org.freedesktop.NetworkManager.xml          | 8 ++++----
 49 files changed, 53 insertions(+), 53 deletions(-)

diff --git a/introspection/org.freedesktop.NetworkManager.AccessPoint.xml b/introspection/org.freedesktop.NetworkManager.AccessPoint.xml
index 6edb25ead2..7340bda308 100644
--- a/introspection/org.freedesktop.NetworkManager.AccessPoint.xml
+++ b/introspection/org.freedesktop.NetworkManager.AccessPoint.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.AccessPoint:
-      @short_description: Wi-Fi Access Point
+      @short_description: Wi-Fi Access Point.
 
   -->
   <interface name="org.freedesktop.NetworkManager.AccessPoint">
diff --git a/introspection/org.freedesktop.NetworkManager.AgentManager.xml b/introspection/org.freedesktop.NetworkManager.AgentManager.xml
index e5fbd100ec..66dfea2ab7 100644
--- a/introspection/org.freedesktop.NetworkManager.AgentManager.xml
+++ b/introspection/org.freedesktop.NetworkManager.AgentManager.xml
@@ -2,7 +2,7 @@
 <node name="/org/freedesktop/NetworkManager/AgentManager">
   <!--
       org.freedesktop.NetworkManager.AgentManager:
-      @short_description: Secret Agent Manager
+      @short_description: Secret Agent Manager.
 
   -->
   <interface name="org.freedesktop.NetworkManager.AgentManager">
diff --git a/introspection/org.freedesktop.NetworkManager.Checkpoint.xml b/introspection/org.freedesktop.NetworkManager.Checkpoint.xml
index 1496ed4ea4..d47407bfda 100644
--- a/introspection/org.freedesktop.NetworkManager.Checkpoint.xml
+++ b/introspection/org.freedesktop.NetworkManager.Checkpoint.xml
@@ -3,7 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.Checkpoint:
-      @short_description: Configuration and State Snapshot
+      @short_description: Configuration and State Snapshot.
 
       A snapshot of NetworkManager state for a given device list
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.Connection.Active.xml b/introspection/org.freedesktop.NetworkManager.Connection.Active.xml
index fc6ff2600a..ebcdf95203 100644
--- a/introspection/org.freedesktop.NetworkManager.Connection.Active.xml
+++ b/introspection/org.freedesktop.NetworkManager.Connection.Active.xml
@@ -3,7 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.Connection.Active:
-      @short_description: Active Connection
+      @short_description: Active Connection.
 
       Objects that implement the Connection.Active interface represent an
       attempt to connect to a network using the details provided by a Connection
diff --git a/introspection/org.freedesktop.NetworkManager.DHCP4Config.xml b/introspection/org.freedesktop.NetworkManager.DHCP4Config.xml
index 0da12d62d0..ae5c3741a8 100644
--- a/introspection/org.freedesktop.NetworkManager.DHCP4Config.xml
+++ b/introspection/org.freedesktop.NetworkManager.DHCP4Config.xml
@@ -3,7 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.DHCP4Config:
-      @short_description: IPv4 DHCP Client State
+      @short_description: IPv4 DHCP Client State.
 
       Options and configuration returned by the IPv4 DHCP server.
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.DHCP6Config.xml b/introspection/org.freedesktop.NetworkManager.DHCP6Config.xml
index 940cf4e463..7da61b231d 100644
--- a/introspection/org.freedesktop.NetworkManager.DHCP6Config.xml
+++ b/introspection/org.freedesktop.NetworkManager.DHCP6Config.xml
@@ -3,7 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.DHCP6Config:
-      @short_description: IPv6 DHCP Client State
+      @short_description: IPv6 DHCP Client State.
 
       Options and configuration returned by the IPv6 DHCP server.
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Adsl.xml b/introspection/org.freedesktop.NetworkManager.Device.Adsl.xml
index 29701d7874..eeb92e9c49 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Adsl.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Adsl.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Adsl:
-      @short_description: ADSL Device
+      @short_description: ADSL Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Adsl">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Bluetooth.xml b/introspection/org.freedesktop.NetworkManager.Device.Bluetooth.xml
index 5cd0eaaee1..ce3d785c7d 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Bluetooth.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Bluetooth.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Bluetooth:
-      @short_description: Bluetooth Device
+      @short_description: Bluetooth Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Bluetooth">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Bond.xml b/introspection/org.freedesktop.NetworkManager.Device.Bond.xml
index e29dee45c8..34803d17b4 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Bond.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Bond.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Bond:
-      @short_description: Bonding Device
+      @short_description: Bonding Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Bond">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Bridge.xml b/introspection/org.freedesktop.NetworkManager.Device.Bridge.xml
index ee0a9c5058..b3a8167d9f 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Bridge.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Bridge.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Bridge:
-      @short_description: Bridging Device
+      @short_description: Bridging Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Bridge">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Dummy.xml b/introspection/org.freedesktop.NetworkManager.Device.Dummy.xml
index 22c917e831..ccef0b5336 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Dummy.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Dummy.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Dummy:
-      @short_description: Dummy Device
+      @short_description: Dummy Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Dummy">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Generic.xml b/introspection/org.freedesktop.NetworkManager.Device.Generic.xml
index 792c460bab..231b22da88 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Generic.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Generic.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Generic:
-      @short_description: Unrecognized Device
+      @short_description: Unrecognized Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Generic">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.IPTunnel.xml b/introspection/org.freedesktop.NetworkManager.Device.IPTunnel.xml
index 4d8a85bbc6..475da37525 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.IPTunnel.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.IPTunnel.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.IPTunnel:
-      @short_description: IP Tunneling Device
+      @short_description: IP Tunneling Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.IPTunnel">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Infiniband.xml b/introspection/org.freedesktop.NetworkManager.Device.Infiniband.xml
index e931a95820..01d328b25a 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Infiniband.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Infiniband.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Infiniband:
-      @short_description: Infiniband Device
+      @short_description: Infiniband Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Infiniband">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Lowpan.xml b/introspection/org.freedesktop.NetworkManager.Device.Lowpan.xml
index 3866946d32..4b99a884d8 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Lowpan.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Lowpan.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Lowpan:
-      @short_description: 6LoWPAN Device
+      @short_description: 6LoWPAN Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Lowpan">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Macsec.xml b/introspection/org.freedesktop.NetworkManager.Device.Macsec.xml
index 6fd2cee54d..2b7cabce72 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Macsec.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Macsec.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Macsec:
-      @short_description: MACSec Device
+      @short_description: MACSec Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Macsec">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Macvlan.xml b/introspection/org.freedesktop.NetworkManager.Device.Macvlan.xml
index cd810a53ca..121dec6214 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Macvlan.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Macvlan.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Macvlan:
-      @short_description: MAC VLAN Device
+      @short_description: MAC VLAN Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Macvlan">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Modem.xml b/introspection/org.freedesktop.NetworkManager.Device.Modem.xml
index 119a998282..1aa0c834f9 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Modem.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Modem.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Modem:
-      @short_description: Modem Device
+      @short_description: Modem Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Modem">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.OlpcMesh.xml b/introspection/org.freedesktop.NetworkManager.Device.OlpcMesh.xml
index 040a6a5d86..00743bf07c 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.OlpcMesh.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.OlpcMesh.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.OlpcMesh:
-      @short_description: OLPC Wireless Mesh Device
+      @short_description: OLPC Wireless Mesh Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.OlpcMesh">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.OvsBridge.xml b/introspection/org.freedesktop.NetworkManager.Device.OvsBridge.xml
index e608cf1d0e..01c09bdf1c 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.OvsBridge.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.OvsBridge.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.OvsBridge:
-      @short_description: OvsBridge Device
+      @short_description: OvsBridge Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.OvsBridge">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.OvsInterface.xml b/introspection/org.freedesktop.NetworkManager.Device.OvsInterface.xml
index be64eb471c..3c4c50c3db 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.OvsInterface.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.OvsInterface.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.OvsInterface:
-      @short_description: OvsInterface Device
+      @short_description: OvsInterface Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.OvsInterface">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.OvsPort.xml b/introspection/org.freedesktop.NetworkManager.Device.OvsPort.xml
index 4919fdf1bd..2a48e9b222 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.OvsPort.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.OvsPort.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.OvsPort:
-      @short_description: OvsPort Device
+      @short_description: OvsPort Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.OvsPort">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Ppp.xml b/introspection/org.freedesktop.NetworkManager.Device.Ppp.xml
index 0032692e68..74ae7bc3df 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Ppp.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Ppp.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Ppp:
-      @short_description: PPP Device
+      @short_description: PPP Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Ppp">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Statistics.xml b/introspection/org.freedesktop.NetworkManager.Device.Statistics.xml
index 06781692b4..ab9076cebb 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Statistics.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Statistics.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Statistics:
-      @short_description: Device Statistic Counters
+      @short_description: Device Statistic Counters.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Statistics">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Team.xml b/introspection/org.freedesktop.NetworkManager.Device.Team.xml
index 0634d87990..ee0f5900d1 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Team.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Team.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Team:
-      @short_description: Teaming Device
+      @short_description: Teaming Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Team">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Tun.xml b/introspection/org.freedesktop.NetworkManager.Device.Tun.xml
index 55a9bacb8d..9e3425568a 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Tun.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Tun.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Tun:
-      @short_description: Userspace Tunneling Device
+      @short_description: Userspace Tunneling Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Tun">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Veth.xml b/introspection/org.freedesktop.NetworkManager.Device.Veth.xml
index 900554c428..95bfeaef30 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Veth.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Veth.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Veth:
-      @short_description: Virtual Ethernet Device
+      @short_description: Virtual Ethernet Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Veth">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Vlan.xml b/introspection/org.freedesktop.NetworkManager.Device.Vlan.xml
index 1ab762b2b7..0dacbc948e 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Vlan.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Vlan.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Vlan:
-      @short_description: Virtual LAN Device
+      @short_description: Virtual LAN Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Vlan">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Vrf.xml b/introspection/org.freedesktop.NetworkManager.Device.Vrf.xml
index 9dfb6c8740..66dc779360 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Vrf.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Vrf.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Vrf:
-      @short_description: VRF Device
+      @short_description: VRF Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Vrf">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Vxlan.xml b/introspection/org.freedesktop.NetworkManager.Device.Vxlan.xml
index 4c04f9dfb6..a8b68ca256 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Vxlan.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Vxlan.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Vxlan:
-      @short_description: VXLAN Device
+      @short_description: VXLAN Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Vxlan">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.WiMax.xml b/introspection/org.freedesktop.NetworkManager.Device.WiMax.xml
index e510a142db..573d170e46 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.WiMax.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.WiMax.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.WiMax:
-      @short_description: WiMax Device
+      @short_description: WiMax Device.
 
       DEPRECATED: NetworkManager no longer supports WiMAX since version 1.2. This interface is no longer used.
   -->
@@ -10,7 +10,7 @@
 
     <!--
         GetNspList:
-        @nsps: List of NSP object paths
+        @nsps: List of NSP object paths.
 
         Get the list of NSPs visible to this device.
     -->
diff --git a/introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml b/introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml
index 61e3236e4e..73b8cc0c21 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.WifiP2P:
-      @short_description: Wi-Fi P2P Device
+      @short_description: Wi-Fi P2P Device.
       @since: 1.16
   -->
   <interface name="org.freedesktop.NetworkManager.Device.WifiP2P">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.WireGuard.xml b/introspection/org.freedesktop.NetworkManager.Device.WireGuard.xml
index b4d4698751..b81cae80e1 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.WireGuard.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.WireGuard.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.WireGuard:
-      @short_description: WireGuard Device
+      @short_description: WireGuard Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.WireGuard">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Wired.xml b/introspection/org.freedesktop.NetworkManager.Device.Wired.xml
index ec3aeae37e..41ea1c6797 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Wired.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Wired.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Wired:
-      @short_description: Wired Ethernet Device
+      @short_description: Wired Ethernet Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Wired">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml b/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml
index 59d4ee9ee5..c428e99855 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Wireless:
-      @short_description: Wi-Fi Device
+      @short_description: Wi-Fi Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Wireless">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.Wpan.xml b/introspection/org.freedesktop.NetworkManager.Device.Wpan.xml
index 1591ce81f6..f8acde5731 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.Wpan.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.Wpan.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.Wpan:
-      @short_description: IEEE 802.15.4 (WPAN) MAC Layer Device
+      @short_description: IEEE 802.15.4 (WPAN) MAC Layer Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.Wpan">
diff --git a/introspection/org.freedesktop.NetworkManager.Device.xml b/introspection/org.freedesktop.NetworkManager.Device.xml
index b42b5478ee..e694fcda3c 100644
--- a/introspection/org.freedesktop.NetworkManager.Device.xml
+++ b/introspection/org.freedesktop.NetworkManager.Device.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device:
-      @short_description: Device
+      @short_description: Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device">
diff --git a/introspection/org.freedesktop.NetworkManager.DnsManager.xml b/introspection/org.freedesktop.NetworkManager.DnsManager.xml
index dd96e0f660..702efb87bd 100644
--- a/introspection/org.freedesktop.NetworkManager.DnsManager.xml
+++ b/introspection/org.freedesktop.NetworkManager.DnsManager.xml
@@ -3,7 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.DnsManager:
-      @short_description: DNS Configuration State
+      @short_description: DNS Configuration State.
 
       The interface contains DNS-related information.
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.IP4Config.xml b/introspection/org.freedesktop.NetworkManager.IP4Config.xml
index 75a59bddd8..f6e18b76b5 100644
--- a/introspection/org.freedesktop.NetworkManager.IP4Config.xml
+++ b/introspection/org.freedesktop.NetworkManager.IP4Config.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.IP4Config:
-      @short_description: IPv4 Configuration Set
+      @short_description: IPv4 Configuration Set.
 
   -->
   <interface name="org.freedesktop.NetworkManager.IP4Config">
diff --git a/introspection/org.freedesktop.NetworkManager.IP6Config.xml b/introspection/org.freedesktop.NetworkManager.IP6Config.xml
index 3fe4a46836..e47b35f28e 100644
--- a/introspection/org.freedesktop.NetworkManager.IP6Config.xml
+++ b/introspection/org.freedesktop.NetworkManager.IP6Config.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.IP6Config:
-      @short_description: IPv6 Configuration Set
+      @short_description: IPv6 Configuration Set.
 
   -->
   <interface name="org.freedesktop.NetworkManager.IP6Config">
diff --git a/introspection/org.freedesktop.NetworkManager.PPP.xml b/introspection/org.freedesktop.NetworkManager.PPP.xml
index d840c786bf..b64414f999 100644
--- a/introspection/org.freedesktop.NetworkManager.PPP.xml
+++ b/introspection/org.freedesktop.NetworkManager.PPP.xml
@@ -3,7 +3,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.PPP:
-      @short_description: Helper interface for a PPP plugin
+      @short_description: Helper interface for a PPP plugin.
 
   -->
   <interface name="org.freedesktop.NetworkManager.PPP">
diff --git a/introspection/org.freedesktop.NetworkManager.SecretAgent.xml b/introspection/org.freedesktop.NetworkManager.SecretAgent.xml
index 7c96064bc6..928e39afe2 100644
--- a/introspection/org.freedesktop.NetworkManager.SecretAgent.xml
+++ b/introspection/org.freedesktop.NetworkManager.SecretAgent.xml
@@ -3,7 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.SecretAgent:
-      @short_description: User Secret Agent
+      @short_description: User Secret Agent.
 
       Private D-Bus interface used by secret agents that store and provide
       secrets to NetworkManager. If an agent provides secrets to NetworkManager
diff --git a/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml b/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml
index 4fd94e17b2..8bc6ebbd08 100644
--- a/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml
+++ b/introspection/org.freedesktop.NetworkManager.Settings.Connection.xml
@@ -3,7 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.Settings.Connection:
-      @short_description: Connection Settings Profile
+      @short_description: Connection Settings Profile.
 
       Represents a single network connection configuration.
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.Settings.xml b/introspection/org.freedesktop.NetworkManager.Settings.xml
index 7e6ff802da..efdd8294c6 100644
--- a/introspection/org.freedesktop.NetworkManager.Settings.xml
+++ b/introspection/org.freedesktop.NetworkManager.Settings.xml
@@ -3,7 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.Settings:
-      @short_description: Connection Settings Profile Manager
+      @short_description: Connection Settings Profile Manager.
 
       The Settings interface allows clients to view and administrate the
       connections stored and used by NetworkManager.
diff --git a/introspection/org.freedesktop.NetworkManager.VPN.Connection.xml b/introspection/org.freedesktop.NetworkManager.VPN.Connection.xml
index 92de149664..2167064133 100644
--- a/introspection/org.freedesktop.NetworkManager.VPN.Connection.xml
+++ b/introspection/org.freedesktop.NetworkManager.VPN.Connection.xml
@@ -3,7 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.VPN.Connection:
-      @short_description: Active VPN Connection
+      @short_description: Active VPN Connection.
 
       Represents an active connection to a Virtual Private Network.
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml b/introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml
index 4c8a8af8c2..b01f7a8195 100644
--- a/introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml
+++ b/introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml
@@ -3,7 +3,7 @@
 
   <!--
       org.freedesktop.NetworkManager.VPN.Plugin:
-      @short_description: VPN Service
+      @short_description: VPN Service.
 
       This interface is provided by plugins providing VPN services to the
       NetworkManager daemon.
diff --git a/introspection/org.freedesktop.NetworkManager.WiMax.Nsp.xml b/introspection/org.freedesktop.NetworkManager.WiMax.Nsp.xml
index 6ebf9cb70c..249df7e7d7 100644
--- a/introspection/org.freedesktop.NetworkManager.WiMax.Nsp.xml
+++ b/introspection/org.freedesktop.NetworkManager.WiMax.Nsp.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.WiMax.Nsp:
-      @short_description: WiMax Network Service Provider
+      @short_description: WiMax Network Service Provider.
 
       DEPRECATED: NetworkManager no longer supports WiMAX since version 1.2. This interface is no longer used.
   -->
diff --git a/introspection/org.freedesktop.NetworkManager.WifiP2PPeer.xml b/introspection/org.freedesktop.NetworkManager.WifiP2PPeer.xml
index 2c7b82df9e..349dc87f6c 100644
--- a/introspection/org.freedesktop.NetworkManager.WifiP2PPeer.xml
+++ b/introspection/org.freedesktop.NetworkManager.WifiP2PPeer.xml
@@ -2,7 +2,7 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.WifiP2PPeer:
-      @short_description: Wi-Fi P2P Peer
+      @short_description: Wi-Fi P2P Peer.
       @since: 1.16
   -->
   <interface name="org.freedesktop.NetworkManager.WifiP2PPeer">
diff --git a/introspection/org.freedesktop.NetworkManager.xml b/introspection/org.freedesktop.NetworkManager.xml
index 9b5ceb04d7..b0ac658b2d 100644
--- a/introspection/org.freedesktop.NetworkManager.xml
+++ b/introspection/org.freedesktop.NetworkManager.xml
@@ -2,7 +2,7 @@
 <node name="/org/freedesktop/NetworkManager">
   <!--
       org.freedesktop.NetworkManager:
-      @short_description: Connection Manager
+      @short_description: Connection Manager.
 
   -->
   <interface name="org.freedesktop.NetworkManager">
@@ -10,7 +10,7 @@
 
     <!--
         Reload:
-        @flags: optional flags to specify which parts shall be reloaded.
+        @flags: Optional flags to specify which parts shall be reloaded.
 
         Reload NetworkManager's configuration and perform certain updates, like flushing a cache or
         rewriting external state to disk. This is similar to sending SIGHUP to NetworkManager but it
@@ -119,7 +119,7 @@
         @options: Further options for the method call.
         @path: Object path of the new connection that was just added.
         @active_connection: The path of the active connection object representing this active connection.
-        @result: a dictionary of additional output arguments for future extension. Currently, not additional output arguments are supported.
+        @result: A dictionary of additional output arguments for future extension. Currently, not additional output arguments are supported.
 
         Adds a new connection using the given details (if any) as a template
         (automatically filling in missing settings with the capabilities of the
@@ -287,7 +287,7 @@
     <!--
         CheckpointAdjustRollbackTimeout:
         @checkpoint: The checkpoint to be rolled back.
-        @add_timeout: number of seconds from <emphasis>now</emphasis> in which the timeout will expire. Set to 0 to disable the timeout.
+        @add_timeout: Number of seconds from <emphasis>now</emphasis> in which the timeout will expire. Set to 0 to disable the timeout.
         @since: 1.12
 
         Reset the timeout for rollback for the checkpoint.