merge: branch 'lr/dbus-api'

https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1154

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">

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">

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
   -->

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
@@ -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"/>

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.
   -->

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.
   -->

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">

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">

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">

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">

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">

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">

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">

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">

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">

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">

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">

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">
@@ -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" />
 

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">

introspection/org.freedesktop.NetworkManager.Device.OvsBridge.xml

@@ -2,19 +2,18 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.OvsBridge:
-      @short_description: OvsBridge Device
+      @short_description: OvsBridge Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.OvsBridge">
 
     <!--
         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"/>
 

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">

introspection/org.freedesktop.NetworkManager.Device.OvsPort.xml

@@ -2,19 +2,18 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.OvsPort:
-      @short_description: OvsPort Device
+      @short_description: OvsPort Device.
 
   -->
   <interface name="org.freedesktop.NetworkManager.Device.OvsPort">
 
     <!--
         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"/>
 

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">

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">

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">

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">

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">

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">

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">

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">

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.
     -->

introspection/org.freedesktop.NetworkManager.Device.WifiP2P.xml

@@ -2,9 +2,8 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.Device.WifiP2P:
-      @short_description: Wi-Fi P2P Device
+      @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,20 +21,24 @@
         Peers:
 
         List of object paths of peers visible to this Wi-Fi P2P device.
-
-        Since: 1.16
     -->
     <property name="Peers" type="ao" access="read"/>
 
     <!--
         StartFind:
-        @options: Options of find. Currently, 'timeout' option with value of "i"
+        @options: Options of find.
-                  in the range of 1-600 seconds is supported. The default is
-                  30 seconds.
 
         Start a find operation for Wi-Fi P2P peers.
 
-        Since: 1.16
+        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"/>
@@ -47,8 +48,6 @@
         StopFind:
 
         Stop an ongoing find operation again.
-
-        Since: 1.16
     -->
     <method name="StopFind">
     </method>
@@ -58,8 +57,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 +67,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"/>

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">

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">

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">
@@ -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"/>
 

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">

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">
@@ -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"/>
 

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.
   -->

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">
@@ -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"/>
 

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">

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">

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

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.
   -->
@@ -103,41 +103,62 @@
 
     <!--
         Update2:
-        @settings: New connection settings, properties, and (optionally) secrets.
+        @settings: New connection settings, properties, and (optionally) secrets. Provide an empty array to use the current settings.
-          Provide an empty array, to use the current settings.
+        @flags: Optional flags. Unknown flags cause the call to fail.
-        @flags: optional flags argument. Currently, supported flags are:
+        @args: Optional arguments dictionary, for extentibility. Currently, no arguments are accepted. Specifying unknown keys causes the call to fail.
-          "0x1" (to-disk),
+        @result: Currently no results are returned.
-          "0x2" (in-memory),
+        @since: 1.12
-          "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.
 
         Update the connection with new settings and properties (replacing all
-        previous settings and properties). If the flag 0x1 is present,
+        previous settings and properties).
-        the connection is persisted to disk. If the flag 0x2 is present,
+
-        the change is only made in memory (without touching an eventual
+        Update2 is an alternative to
-        profile on disk). If neither 0x1 nor 0x2 is set, the change is made
+        <link linkend="gdbus-method-org-freedesktop-NetworkManager-Settings-Connection.Update">Update</link>,
-        in memory only, if the connection is already in memory only.
+        <link linkend="gdbus-method-org-freedesktop-NetworkManager-Settings-Connection.UpdateUnsaved">UpdateUnsaved</link>
-        The flags 0x4 (in-memory-detached) and 0x8 (in-memory-only) are like
+        and <link linkend="gdbus-method-org-freedesktop-NetworkManager-Settings-Connection.Save">Save</link>
-        "in-memory", but behave slightly different when migrating the profile
+        extensible with extra %flags and %args arguments.
-        from disk to in-memory.
+
-        The flag 0x20 (block-autoconnect) blocks auto-connect on the updated
+        The %flags argument accepts the combination of following values,
-        profile, and 0x40 (no-reapply) prevents "connection.zone" and "connection.metered"
+        logically or-ed together:
-        properties to take effect on currently active devices.
+
+        <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.
-
-        Since: 1.12
     -->
     <method name="Update2">
       <arg name="settings" type="a{sa{sv}}" direction="in"/>
@@ -168,21 +189,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"/>
 

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.
@@ -66,29 +66,44 @@
     <!--
         AddConnection2:
         @settings: New connection settings, properties, and (optionally) secrets.
-        @flags: optional flags argument. Currently, the following flags are supported:
+        @flags: Flags. Unknown flags cause the call to fail.
-          "0x1" (to-disk),
+        @args: Optional arguments dictionary, for extentibility. Currently, no arguments are accepted. Specifying unknown keys causes the call to fail.
-          "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.
         @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.
+        AddConnection2 is an alternative to
-        The effect is whether to behave like AddConnection or AddConnectionUnsaved.
+        <link linkend="gdbus-method-org-freedesktop-NetworkManager-Settings.AddConnection">AddConnection</link> and
-        If 0x20 (block-autoconnect) is specified, autoconnect for the new profile
+        <link linkend="gdbus-method-org-freedesktop-NetworkManager-Settings.AddConnectionUnsaved">AddConnectionUnsaved</link>.
-        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.
         The new variant can do everything that the older variants could, and more.
+        Its behavior is extensible via extra %flags and %args arguments.
 
-        Since: 1.20
+        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"/>
@@ -102,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
@@ -110,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"/>

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.
   -->

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.

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.
   -->

introspection/org.freedesktop.NetworkManager.WifiP2PPeer.xml

@@ -2,9 +2,8 @@
 <node name="/">
   <!--
       org.freedesktop.NetworkManager.WifiP2PPeer:
-      @short_description: Wi-Fi P2P Peer
+      @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"/>
 

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,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
+        @result: A dictionary of additional output arguments for future extension. Currently, not additional output arguments are supported.
-          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,19 +286,19 @@
 
     <!--
         CheckpointAdjustRollbackTimeout:
-        @add_timeout: number of seconds from ~now~ in which the
+        @checkpoint: The checkpoint to be rolled back.
-          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.
-          Note that the added seconds start counting from now,
+        @since: 1.12
-          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.
 
         Reset the timeout for rollback for the checkpoint.
 
-        Since: 1.12
+        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"/>