merge: branch 'lr/docs-deprec-props'

The documentation of property deprecation was not great in nm-settings-nmcli(5).

This aims to improve that, essentially changing:

  number
      Legacy setting that used to help establishing PPP data sessions for GSM-based modems. Deprecated: 1

Into

  number
      Legacy setting that used to help establishing PPP data sessions for GSM-based modems.

      This property is deprecated since version 1.16. User-provided values for this setting are no longer used.

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

9 files changed, 85 insertions, 55 deletions

diff --git a/man/nm-settings-dbus.xsl b/man/nm-settings-dbus.xsl
index a0c12cd879..665105eea0 100644
--- a/man/nm-settings-dbus.xsl
+++ b/man/nm-settings-dbus.xsl
@@ -162,7 +162,9 @@
       <entry align="left"><xsl:attribute name="id">nm-settings-dbus.property.<xsl:value-of select="../@name"/>.<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></entry>
       <entry align="left"><xsl:value-of select="@type"/></entry>
       <entry align="left"><xsl:value-of select="@default"/></entry>
-      <entry><xsl:apply-templates select="description"/></entry>
+      <entry><xsl:apply-templates select="description"/><xsl:if test="deprecated">
+
+This property is deprecated since version <xsl:value-of select="deprecated/@since"/>.<xsl:value-of select="deprecated"/></xsl:if></entry>
     </row>
   </xsl:template>
 
diff --git a/man/nm-settings-nmcli.xsl b/man/nm-settings-nmcli.xsl
index 5a6b8ba181..d7b770d681 100644
--- a/man/nm-settings-nmcli.xsl
+++ b/man/nm-settings-nmcli.xsl
@@ -163,6 +163,12 @@
             </para>
           </xsl:otherwise>
         </xsl:choose>
+        <xsl:if test="deprecated">
+          <para>
+            This property is deprecated since version <xsl:value-of select="deprecated/@since"/>.
+            <xsl:value-of select="deprecated"/>
+          </para>
+        </xsl:if>
         <xsl:if test="@type">
           <para>
             Format: <xsl:value-of select="@type"/>
diff --git a/src/libnm-core-impl/nm-setting-8021x.c b/src/libnm-core-impl/nm-setting-8021x.c
index aa5bfdc05e..5c36bed6bf 100644
--- a/src/libnm-core-impl/nm-setting-8021x.c
+++ b/src/libnm-core-impl/nm-setting-8021x.c
@@ -3347,9 +3347,10 @@ nm_setting_802_1x_class_init(NMSetting8021xClass *klass)
      *
      * Substring to be matched against the subject of the certificate presented
      * by the authentication server. When unset, no verification of the
-     * authentication server certificate's subject is performed.  This property
-     * provides little security, if any, and its use is deprecated in favor of
-     * NMSetting8021x:domain-suffix-match.
+     * authentication server certificate's subject is performed. This property
+     * provides little security, if any, and should not be used.
+     *
+     * Deprecated: 1.2: Use #NMSetting8021x:phase2-domain-suffix-match instead.
      **/
     /* ---ifcfg-rh---
      * property: subject-match
@@ -3758,9 +3759,10 @@ nm_setting_802_1x_class_init(NMSetting8021xClass *klass)
      * Substring to be matched against the subject of the certificate presented
      * by the authentication server during the inner "phase 2"
      * authentication. When unset, no verification of the authentication server
-     * certificate's subject is performed.  This property provides little security,
-     * if any, and its use is deprecated in favor of
-     * NMSetting8021x:phase2-domain-suffix-match.
+     * certificate's subject is performed. This property provides little security,
+     * if any, and should not be used.
+     *
+     * Deprecated: 1.2: Use #NMSetting8021x:phase2-domain-suffix-match instead.
      **/
     /* ---ifcfg-rh---
      * property: phase2-subject-match
diff --git a/src/libnm-core-impl/nm-setting-bridge.c b/src/libnm-core-impl/nm-setting-bridge.c
index 017b8e860e..19048287b7 100644
--- a/src/libnm-core-impl/nm-setting-bridge.c
+++ b/src/libnm-core-impl/nm-setting-bridge.c
@@ -1426,10 +1426,9 @@ nm_setting_bridge_class_init(NMSettingBridgeClass *klass)
      * If this field is left unspecified, the "ethernet.cloned-mac-address" is
      * referred instead to generate the initial MAC address. Note that setting
      * "ethernet.cloned-mac-address" anyway overwrites the MAC address of
-     * the bridge later while activating the bridge. Hence, this property
-     * is deprecated.
+     * the bridge later while activating the bridge.
      *
-     * Deprecated: 1.12: Use the ethernet.cloned-mac-address property instead.
+     * Deprecated: 1.12: Use the #NMSettingWired:cloned-mac-address property instead.
      **/
     /* ---keyfile---
      * property: mac-address
diff --git a/src/libnm-core-impl/nm-setting-wireless.c b/src/libnm-core-impl/nm-setting-wireless.c
index 6bfcd2ce91..30de4cef44 100644
--- a/src/libnm-core-impl/nm-setting-wireless.c
+++ b/src/libnm-core-impl/nm-setting-wireless.c
@@ -1787,11 +1787,10 @@ nm_setting_wireless_class_init(NMSettingWirelessClass *klass)
      * the user has set a global default to randomize and the supplicant
      * supports randomization),  %NM_SETTING_MAC_RANDOMIZATION_NEVER (never
      * randomize the MAC address), or %NM_SETTING_MAC_RANDOMIZATION_ALWAYS
-     * (always randomize the MAC address). This property is deprecated for
-     * 'cloned-mac-address'.
+     * (always randomize the MAC address).
      *
      * Since: 1.2
-     * Deprecated: 1.4: Deprecated by NMSettingWireless:cloned-mac-address property.
+     * Deprecated: 1.4: Use the #NMSettingWireless:cloned-mac-address property instead.
      **/
     /* ---ifcfg-rh---
      * property: mac-address-randomization
diff --git a/src/libnmc-setting/settings-docs.h.in b/src/libnmc-setting/settings-docs.h.in
index 56a15e476e..4fdafed5db 100644
--- a/src/libnmc-setting/settings-docs.h.in
+++ b/src/libnmc-setting/settings-docs.h.in
@@ -68,13 +68,13 @@
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_PRIVATE_KEY N_("Contains the \"phase 2\" inner private key when the \"phase2-auth\" or \"phase2-autheap\" property is set to \"tls\". Key data is specified using a \"scheme\"; two are currently supported: blob and path. When using the blob scheme and private keys, this property should be set to the key's encrypted PEM encoded data. When using private keys with the path scheme, this property should be set to the full UTF-8 encoded path of the key, prefixed with the string \"file://\" and ending with a terminating NUL byte. When using PKCS#12 format private keys and the blob scheme, this property should be set to the PKCS#12 data and the \"phase2-private-key-password\" property must be set to password used to decrypt the PKCS#12 certificate and key. When using PKCS#12 files and the path scheme, this property should be set to the full UTF-8 encoded path of the key, prefixed with the string \"file://\" and ending with a terminating NUL byte, and as with the blob scheme the \"phase2-private-key-password\" property must be set to the password used to decode the PKCS#12 private key and certificate.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_PRIVATE_KEY_PASSWORD N_("The password used to decrypt the \"phase 2\" private key specified in the \"phase2-private-key\" property when the private key either uses the path scheme, or is a PKCS#12 format key.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_PRIVATE_KEY_PASSWORD_FLAGS N_("Flags indicating how to handle the \"phase2-private-key-password\" property.")
-#define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_SUBJECT_MATCH N_("Substring to be matched against the subject of the certificate presented by the authentication server during the inner \"phase 2\" authentication. When unset, no verification of the authentication server certificate's subject is performed.  This property provides little security, if any, and its use is deprecated in favor of NMSetting8021x:phase2-domain-suffix-match.")
+#define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_SUBJECT_MATCH N_("Substring to be matched against the subject of the certificate presented by the authentication server during the inner \"phase 2\" authentication. When unset, no verification of the authentication server certificate's subject is performed. This property provides little security, if any, and should not be used.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PIN N_("PIN used for EAP authentication methods.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PIN_FLAGS N_("Flags indicating how to handle the \"pin\" property.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PRIVATE_KEY N_("Contains the private key when the \"eap\" property is set to \"tls\". Key data is specified using a \"scheme\"; two are currently supported: blob and path. When using the blob scheme and private keys, this property should be set to the key's encrypted PEM encoded data. When using private keys with the path scheme, this property should be set to the full UTF-8 encoded path of the key, prefixed with the string \"file://\" and ending with a terminating NUL byte. When using PKCS#12 format private keys and the blob scheme, this property should be set to the PKCS#12 data and the \"private-key-password\" property must be set to password used to decrypt the PKCS#12 certificate and key. When using PKCS#12 files and the path scheme, this property should be set to the full UTF-8 encoded path of the key, prefixed with the string \"file://\" and ending with a terminating NUL byte, and as with the blob scheme the \"private-key-password\" property must be set to the password used to decode the PKCS#12 private key and certificate. WARNING: \"private-key\" is not a \"secret\" property, and thus unencrypted private key data using the BLOB scheme may be readable by unprivileged users.  Private keys should always be encrypted with a private key password to prevent unauthorized access to unencrypted private key data.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PRIVATE_KEY_PASSWORD N_("The password used to decrypt the private key specified in the \"private-key\" property when the private key either uses the path scheme, or if the private key is a PKCS#12 format key.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PRIVATE_KEY_PASSWORD_FLAGS N_("Flags indicating how to handle the \"private-key-password\" property.")
-#define DESCRIBE_DOC_NM_SETTING_802_1X_SUBJECT_MATCH N_("Substring to be matched against the subject of the certificate presented by the authentication server. When unset, no verification of the authentication server certificate's subject is performed.  This property provides little security, if any, and its use is deprecated in favor of NMSetting8021x:domain-suffix-match.")
+#define DESCRIBE_DOC_NM_SETTING_802_1X_SUBJECT_MATCH N_("Substring to be matched against the subject of the certificate presented by the authentication server. When unset, no verification of the authentication server certificate's subject is performed. This property provides little security, if any, and should not be used.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_SYSTEM_CA_CERTS N_("When TRUE, overrides the \"ca-path\" and \"phase2-ca-path\" properties using the system CA directory specified at configure time with the --system-ca-path switch.  The certificates in this directory are added to the verification chain in addition to any certificates specified by the \"ca-cert\" and \"phase2-ca-cert\" properties. If the path provided with --system-ca-path is rather a file name (bundle of trusted CA certificates), it overrides \"ca-cert\" and \"phase2-ca-cert\" properties instead (sets ca_cert/ca_cert2 options for wpa_supplicant).")
 #define DESCRIBE_DOC_NM_SETTING_ADSL_ENCAPSULATION N_("Encapsulation of ADSL connection.  Can be \"vcmux\" or \"llc\".")
 #define DESCRIBE_DOC_NM_SETTING_ADSL_PASSWORD N_("Password used to authenticate with the ADSL service.")
@@ -91,7 +91,7 @@
 #define DESCRIBE_DOC_NM_SETTING_BRIDGE_GROUP_ADDRESS N_("If specified, The MAC address of the multicast group this bridge uses for STP. The address must be a link-local address in standard Ethernet MAC address format, ie an address of the form 01:80:C2:00:00:0X, with X in [0, 4..F]. If not specified the default value is 01:80:C2:00:00:00.")
 #define DESCRIBE_DOC_NM_SETTING_BRIDGE_GROUP_FORWARD_MASK N_("A mask of group addresses to forward. Usually, group addresses in the range from 01:80:C2:00:00:00 to 01:80:C2:00:00:0F are not forwarded according to standards. This property is a mask of 16 bits, each corresponding to a group address in that range that must be forwarded. The mask can't have bits 0, 1 or 2 set because they are used for STP, MAC pause frames and LACP.")
 #define DESCRIBE_DOC_NM_SETTING_BRIDGE_HELLO_TIME N_("The Spanning Tree Protocol (STP) hello time, in seconds.")
-#define DESCRIBE_DOC_NM_SETTING_BRIDGE_MAC_ADDRESS N_("If specified, the MAC address of bridge. When creating a new bridge, this MAC address will be set. If this field is left unspecified, the \"ethernet.cloned-mac-address\" is referred instead to generate the initial MAC address. Note that setting \"ethernet.cloned-mac-address\" anyway overwrites the MAC address of the bridge later while activating the bridge. Hence, this property is deprecated. Deprecated: 1")
+#define DESCRIBE_DOC_NM_SETTING_BRIDGE_MAC_ADDRESS N_("If specified, the MAC address of bridge. When creating a new bridge, this MAC address will be set. If this field is left unspecified, the \"ethernet.cloned-mac-address\" is referred instead to generate the initial MAC address. Note that setting \"ethernet.cloned-mac-address\" anyway overwrites the MAC address of the bridge later while activating the bridge.")
 #define DESCRIBE_DOC_NM_SETTING_BRIDGE_MAX_AGE N_("The Spanning Tree Protocol (STP) maximum message age, in seconds.")
 #define DESCRIBE_DOC_NM_SETTING_BRIDGE_MULTICAST_HASH_MAX N_("Set maximum size of multicast hash table (value must be a power of 2).")
 #define DESCRIBE_DOC_NM_SETTING_BRIDGE_MULTICAST_LAST_MEMBER_COUNT N_("Set the number of queries the bridge will send before stopping forwarding a multicast group after a \"leave\" message has been received.")
@@ -143,7 +143,7 @@
 #define DESCRIBE_DOC_NM_SETTING_GSM_HOME_ONLY N_("When TRUE, only connections to the home network will be allowed. Connections to roaming networks will not be made.")
 #define DESCRIBE_DOC_NM_SETTING_GSM_MTU N_("If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple frames.")
 #define DESCRIBE_DOC_NM_SETTING_GSM_NETWORK_ID N_("The Network ID (GSM LAI format, ie MCC-MNC) to force specific network registration.  If the Network ID is specified, NetworkManager will attempt to force the device to register only on the specified network. This can be used to ensure that the device does not roam when direct roaming control of the device is not otherwise possible.")
-#define DESCRIBE_DOC_NM_SETTING_GSM_NUMBER N_("Legacy setting that used to help establishing PPP data sessions for GSM-based modems. Deprecated: 1")
+#define DESCRIBE_DOC_NM_SETTING_GSM_NUMBER N_("Legacy setting that used to help establishing PPP data sessions for GSM-based modems.")
 #define DESCRIBE_DOC_NM_SETTING_GSM_PASSWORD N_("The password used to authenticate with the network, if required.  Many providers do not require a password, or accept any password.  But if a password is required, it is specified here.")
 #define DESCRIBE_DOC_NM_SETTING_GSM_PASSWORD_FLAGS N_("Flags indicating how to handle the \"password\" property.")
 #define DESCRIBE_DOC_NM_SETTING_GSM_PIN N_("If the SIM is locked with a PIN it must be unlocked before any other operations are requested.  Specify the PIN here to allow operation of the device.")
@@ -359,8 +359,8 @@
 #define DESCRIBE_DOC_NM_SETTING_WIFI_P2P_PEER N_("The P2P device that should be connected to. Currently, this is the only way to create or join a group.")
 #define DESCRIBE_DOC_NM_SETTING_WIFI_P2P_WFD_IES N_("The Wi-Fi Display (WFD) Information Elements (IEs) to set. Wi-Fi Display requires a protocol specific information element to be set in certain Wi-Fi frames. These can be specified here for the purpose of establishing a connection. This setting is only useful when implementing a Wi-Fi Display client.")
 #define DESCRIBE_DOC_NM_SETTING_WIFI_P2P_WPS_METHOD N_("Flags indicating which mode of WPS is to be used. There's little point in changing the default setting as NetworkManager will automatically determine the best method to use.")
-#define DESCRIBE_DOC_NM_SETTING_WIMAX_MAC_ADDRESS N_("If specified, this connection will only apply to the WiMAX device whose MAC address matches. This property does not change the MAC address of the device (known as MAC spoofing). Deprecated: 1")
-#define DESCRIBE_DOC_NM_SETTING_WIMAX_NETWORK_NAME N_("Network Service Provider (NSP) name of the WiMAX network this connection should use. Deprecated: 1")
+#define DESCRIBE_DOC_NM_SETTING_WIMAX_MAC_ADDRESS N_("If specified, this connection will only apply to the WiMAX device whose MAC address matches. This property does not change the MAC address of the device (known as MAC spoofing).")
+#define DESCRIBE_DOC_NM_SETTING_WIMAX_NETWORK_NAME N_("Network Service Provider (NSP) name of the WiMAX network this connection should use.")
 #define DESCRIBE_DOC_NM_SETTING_WIRED_ACCEPT_ALL_MAC_ADDRESSES N_("When TRUE, setup the interface to accept packets for all MAC addresses. This is enabling the kernel interface flag IFF_PROMISC. When FALSE, the interface will only accept the packets with the interface destination mac address or broadcast.")
 #define DESCRIBE_DOC_NM_SETTING_WIRED_AUTO_NEGOTIATE N_("When TRUE, enforce auto-negotiation of speed and duplex mode. If \"speed\" and \"duplex\" properties are both specified, only that single mode will be advertised and accepted during the link auto-negotiation process: this works only for BASE-T 802.3 specifications and is useful for enforcing gigabits modes, as in these cases link negotiation is mandatory. When FALSE, \"speed\" and \"duplex\" properties should be both set or link configuration will be skipped.")
 #define DESCRIBE_DOC_NM_SETTING_WIRED_CLONED_MAC_ADDRESS N_("If specified, request that the device use this MAC address instead. This is known as MAC cloning or spoofing. Beside explicitly specifying a MAC address, the special values \"preserve\", \"permanent\", \"random\" and \"stable\" are supported. \"preserve\" means not to touch the MAC address on activation. \"permanent\" means to use the permanent hardware address if the device has one (otherwise this is treated as \"preserve\"). \"random\" creates a random MAC address on each connect. \"stable\" creates a hashed MAC address based on connection.stable-id and a machine dependent key. If unspecified, the value can be overwritten via global defaults, see manual of NetworkManager.conf. If still unspecified, it defaults to \"preserve\" (older versions of NetworkManager may use a different default value). On D-Bus, this field is expressed as \"assigned-mac-address\" or the deprecated \"cloned-mac-address\".")
@@ -393,7 +393,7 @@
 #define DESCRIBE_DOC_NM_SETTING_WIRELESS_HIDDEN N_("If TRUE, indicates that the network is a non-broadcasting network that hides its SSID. This works both in infrastructure and AP mode. In infrastructure mode, various workarounds are used for a more reliable discovery of hidden networks, such as probe-scanning the SSID.  However, these workarounds expose inherent insecurities with hidden SSID networks, and thus hidden SSID networks should be used with caution. In AP mode, the created network does not broadcast its SSID. Note that marking the network as hidden may be a privacy issue for you (in infrastructure mode) or client stations (in AP mode), as the explicit probe-scans are distinctly recognizable on the air.")
 #define DESCRIBE_DOC_NM_SETTING_WIRELESS_MAC_ADDRESS N_("If specified, this connection will only apply to the Wi-Fi device whose permanent MAC address matches. This property does not change the MAC address of the device (i.e. MAC spoofing).")
 #define DESCRIBE_DOC_NM_SETTING_WIRELESS_MAC_ADDRESS_BLACKLIST N_("A list of permanent MAC addresses of Wi-Fi devices to which this connection should never apply.  Each MAC address should be given in the standard hex-digits-and-colons notation (eg \"00:11:22:33:44:55\").")
-#define DESCRIBE_DOC_NM_SETTING_WIRELESS_MAC_ADDRESS_RANDOMIZATION N_("One of NM_SETTING_MAC_RANDOMIZATION_DEFAULT (0) (never randomize unless the user has set a global default to randomize and the supplicant supports randomization),  NM_SETTING_MAC_RANDOMIZATION_NEVER (1) (never randomize the MAC address), or NM_SETTING_MAC_RANDOMIZATION_ALWAYS (2) (always randomize the MAC address). This property is deprecated for 'cloned-mac-address'. Deprecated: 1")
+#define DESCRIBE_DOC_NM_SETTING_WIRELESS_MAC_ADDRESS_RANDOMIZATION N_("One of NM_SETTING_MAC_RANDOMIZATION_DEFAULT (0) (never randomize unless the user has set a global default to randomize and the supplicant supports randomization),  NM_SETTING_MAC_RANDOMIZATION_NEVER (1) (never randomize the MAC address), or NM_SETTING_MAC_RANDOMIZATION_ALWAYS (2) (always randomize the MAC address).")
 #define DESCRIBE_DOC_NM_SETTING_WIRELESS_MODE N_("Wi-Fi network mode; one of \"infrastructure\", \"mesh\", \"adhoc\" or \"ap\".  If blank, infrastructure is assumed.")
 #define DESCRIBE_DOC_NM_SETTING_WIRELESS_MTU N_("If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple Ethernet frames.")
 #define DESCRIBE_DOC_NM_SETTING_WIRELESS_POWERSAVE N_("One of NM_SETTING_WIRELESS_POWERSAVE_DISABLE (2) (disable Wi-Fi power saving), NM_SETTING_WIRELESS_POWERSAVE_ENABLE (3) (enable Wi-Fi power saving), NM_SETTING_WIRELESS_POWERSAVE_IGNORE (1) (don't touch currently configure setting) or NM_SETTING_WIRELESS_POWERSAVE_DEFAULT (0) (use the globally configured value). All other values are reserved.")
diff --git a/src/nmcli/generate-docs-nm-settings-nmcli.xml.in b/src/nmcli/generate-docs-nm-settings-nmcli.xml.in
index ab6d926b55..a9bde03d9b 100644
--- a/src/nmcli/generate-docs-nm-settings-nmcli.xml.in
+++ b/src/nmcli/generate-docs-nm-settings-nmcli.xml.in
@@ -45,7 +45,7 @@
         <property name="mac-address-blacklist"
                   description="A list of permanent MAC addresses of Wi-Fi devices to which this connection should never apply.  Each MAC address should be given in the standard hex-digits-and-colons notation (eg &quot;00:11:22:33:44:55&quot;)." />
         <property name="mac-address-randomization"
-                  description="One of NM_SETTING_MAC_RANDOMIZATION_DEFAULT (0) (never randomize unless the user has set a global default to randomize and the supplicant supports randomization),  NM_SETTING_MAC_RANDOMIZATION_NEVER (1) (never randomize the MAC address), or NM_SETTING_MAC_RANDOMIZATION_ALWAYS (2) (always randomize the MAC address). This property is deprecated for &apos;cloned-mac-address&apos;. Deprecated: 1" />
+                  description="One of NM_SETTING_MAC_RANDOMIZATION_DEFAULT (0) (never randomize unless the user has set a global default to randomize and the supplicant supports randomization),  NM_SETTING_MAC_RANDOMIZATION_NEVER (1) (never randomize the MAC address), or NM_SETTING_MAC_RANDOMIZATION_ALWAYS (2) (always randomize the MAC address)." />
         <property name="mtu"
                   alias="mtu"
                   description="If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple Ethernet frames." />
@@ -123,7 +123,7 @@
         <property name="ca-path"
                   description="UTF-8 encoded path to a directory containing PEM or DER formatted certificates to be added to the verification chain in addition to the certificate specified in the &quot;ca-cert&quot; property. If NMSetting8021x:system-ca-certs is enabled and the built-in CA path is an existing directory, then this setting is ignored." />
         <property name="subject-match"
-                  description="Substring to be matched against the subject of the certificate presented by the authentication server. When unset, no verification of the authentication server certificate&apos;s subject is performed.  This property provides little security, if any, and its use is deprecated in favor of NMSetting8021x:domain-suffix-match." />
+                  description="Substring to be matched against the subject of the certificate presented by the authentication server. When unset, no verification of the authentication server certificate&apos;s subject is performed. This property provides little security, if any, and should not be used." />
         <property name="altsubject-matches"
                   description="List of strings to be matched against the altSubjectName of the certificate presented by the authentication server. If the list is empty, no verification of the server certificate&apos;s altSubjectName is performed." />
         <property name="domain-suffix-match"
@@ -157,7 +157,7 @@
         <property name="phase2-ca-path"
                   description="UTF-8 encoded path to a directory containing PEM or DER formatted certificates to be added to the verification chain in addition to the certificate specified in the &quot;phase2-ca-cert&quot; property. If NMSetting8021x:system-ca-certs is enabled and the built-in CA path is an existing directory, then this setting is ignored." />
         <property name="phase2-subject-match"
-                  description="Substring to be matched against the subject of the certificate presented by the authentication server during the inner &quot;phase 2&quot; authentication. When unset, no verification of the authentication server certificate&apos;s subject is performed.  This property provides little security, if any, and its use is deprecated in favor of NMSetting8021x:phase2-domain-suffix-match." />
+                  description="Substring to be matched against the subject of the certificate presented by the authentication server during the inner &quot;phase 2&quot; authentication. When unset, no verification of the authentication server certificate&apos;s subject is performed. This property provides little security, if any, and should not be used." />
         <property name="phase2-altsubject-matches"
                   description="List of strings to be matched against the altSubjectName of the certificate presented by the authentication server during the inner &quot;phase 2&quot; authentication. If the list is empty, no verification of the server certificate&apos;s altSubjectName is performed." />
         <property name="phase2-domain-suffix-match"
@@ -275,7 +275,7 @@
     <setting name="bridge" >
         <property name="mac-address"
                   alias="mac"
-                  description="If specified, the MAC address of bridge. When creating a new bridge, this MAC address will be set. If this field is left unspecified, the &quot;ethernet.cloned-mac-address&quot; is referred instead to generate the initial MAC address. Note that setting &quot;ethernet.cloned-mac-address&quot; anyway overwrites the MAC address of the bridge later while activating the bridge. Hence, this property is deprecated. Deprecated: 1" />
+                  description="If specified, the MAC address of bridge. When creating a new bridge, this MAC address will be set. If this field is left unspecified, the &quot;ethernet.cloned-mac-address&quot; is referred instead to generate the initial MAC address. Note that setting &quot;ethernet.cloned-mac-address&quot; anyway overwrites the MAC address of the bridge later while activating the bridge." />
         <property name="stp"
                   alias="stp"
                   description="Controls whether Spanning Tree Protocol (STP) is enabled for this bridge." />
@@ -560,7 +560,7 @@
         <property name="auto-config"
                   description="When TRUE, the settings such as APN, username, or password will default to values that match the network the modem will register to in the Mobile Broadband Provider database." />
         <property name="number"
-                  description="Legacy setting that used to help establishing PPP data sessions for GSM-based modems. Deprecated: 1" />
+                  description="Legacy setting that used to help establishing PPP data sessions for GSM-based modems." />
         <property name="username"
                   alias="user"
                   description="The username used to authenticate with the network, if required.  Many providers do not require a username, or accept any username.  But if a username is required, it is specified here." />
@@ -1119,10 +1119,10 @@
     <setting name="wimax" >
         <property name="mac-address"
                   alias="mac"
-                  description="If specified, this connection will only apply to the WiMAX device whose MAC address matches. This property does not change the MAC address of the device (known as MAC spoofing). Deprecated: 1" />
+                  description="If specified, this connection will only apply to the WiMAX device whose MAC address matches. This property does not change the MAC address of the device (known as MAC spoofing)." />
         <property name="network-name"
                   alias="nsp"
-                  description="Network Service Provider (NSP) name of the WiMAX network this connection should use. Deprecated: 1" />
+                  description="Network Service Provider (NSP) name of the WiMAX network this connection should use." />
     </setting>
     <setting name="wireguard" >
         <property name="private-key"
diff --git a/tools/generate-docs-nm-settings-docs-gir.py b/tools/generate-docs-nm-settings-docs-gir.py
index f7a20e2bb0..88b87a7233 100755
--- a/tools/generate-docs-nm-settings-docs-gir.py
+++ b/tools/generate-docs-nm-settings-docs-gir.py
@@ -120,14 +120,8 @@ def remove_prefix(line, prefix):
     return line[len(prefix) :] if line.startswith(prefix) else line
 
 
-def get_docs(propxml):
-    doc_xml = propxml.find("gi:doc", ns_map)
-    if doc_xml is None:
-        return None
-
+def format_docs(doc_xml):
     doc = doc_xml.text
-    if "deprecated" in propxml.attrib:
-        doc = doc + " Deprecated: " + propxml.attrib["deprecated"]
 
     # split docs into lines
     lines = re.split("\n", doc)
@@ -136,11 +130,11 @@ def get_docs(propxml):
     doc = ""
     for l in lines:
         if l:
-            doc += " " + l
+            doc += l + " "
         else:
-            doc += "\n\n"
+            doc = doc.strip(" ") + "\n\n"
 
-    doc = doc.strip("\n")
+    doc = doc.strip("\n ")
 
     # Expand constants
     doc = re.sub(r"%([^%]\w*)", lambda match: constants[match.group(1)], doc)
@@ -173,6 +167,14 @@ def get_docs(propxml):
     return doc
 
 
+def get_docs(propxml):
+    doc_xml = propxml.find("gi:doc", ns_map)
+    if doc_xml is None:
+        return None
+    else:
+        return format_docs(doc_xml)
+
+
 def get_default_value(setting, pspec, propxml):
     default_value = setting.get_property(pspec.name.replace("-", "_"))
     if default_value is None:
@@ -274,6 +276,13 @@ def main(gir_path_str, output_path_str):
             value_desc = get_docs(propxml)
             default_value = get_default_value(setting, pspec, propxml)
 
+            if "deprecated" in propxml.attrib:
+                deprecated = True
+                deprecated_since = propxml.attrib["deprecated-version"]
+                deprecated_desc = format_docs(propxml.find("gi:doc-deprecated", ns_map))
+            else:
+                deprecated = False
+
             prop_upper = prop.upper().replace("-", "_")
 
             if value_desc is None:
@@ -310,6 +319,22 @@ def main(gir_path_str, output_path_str):
 
                 create_desc_docbook(description_docbook, value_desc)
 
+            if deprecated:
+                ET.SubElement(
+                    property_element,
+                    "deprecated",
+                    attrib={
+                        "since": deprecated_since,
+                    },
+                ).text = deprecated_desc
+
+                deprecated_docbook = ET.SubElement(
+                    property_element,
+                    "deprecated-docbook",
+                )
+
+                create_desc_docbook(deprecated_docbook, deprecated_desc)
+
     docs_gir.write(
         output_path_str,
         xml_declaration=True,
diff --git a/tools/generate-docs-nm-settings-docs-merge.py b/tools/generate-docs-nm-settings-docs-merge.py
index 17c78a24d3..5df4907349 100755
--- a/tools/generate-docs-nm-settings-docs-merge.py
+++ b/tools/generate-docs-nm-settings-docs-merge.py
@@ -110,13 +110,12 @@ def node_set_attr(dst_node, name, nodes):
     if x:
         dst_node.set(name, x)
 
-
-def find_first_not_none(itr):
-    for i in itr:
-        if i is not None:
-            return i
-    return None
-
+def find_attr(properties_attrs, name):
+    for p_attr in properties_attrs:
+        if p_attr is not None:
+            p_attr = p_attr.find(name)
+        if p_attr is not None:
+            return p_attr
 
 ###############################################################################
 
@@ -180,17 +179,10 @@ for setting_name in iter_keys_of_dicts(settings_roots, key_fcn_setting_name):
         dbg("> > > > property_name: %s" % (property_name))
 
         properties_attrs = list([p.get(property_name) for p in properties])
-        description_docbook = find_first_not_none(
-            p_attr.find("description-docbook")
-            for p_attr in properties_attrs
-            if p_attr is not None
-        )
-
-        description = find_first_not_none(
-            p_attr.find("description")
-            for p_attr in properties_attrs
-            if p_attr is not None
-        )
+        description_docbook = find_attr(properties_attrs, "description-docbook")
+        description = find_attr(properties_attrs, "description")
+        deprecated_docbook = find_attr(properties_attrs, "deprecated-docbook")
+        deprecated = find_attr(properties_attrs, "deprecated")
 
         if gl_only_from_first and properties_attrs[0] is None:
             dbg("> > > > skip (only-from-first")
@@ -221,4 +213,9 @@ for setting_name in iter_keys_of_dicts(settings_roots, key_fcn_setting_name):
         elif description is not None:
             property_node.append(description)
 
+        if deprecated_docbook is not None:
+            property_node.insert(0, deprecated_docbook)
+        if deprecated is not None:
+            property_node.insert(0, deprecated)
+
 ET.ElementTree(root_node).write(gl_output_xml_file)