merge: branch 'lr/gtk-doc'

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

docs/libnm/Makefile.am

@@ -24,7 +24,7 @@ DOC_SOURCE_DIR= \
 	$(NULL)
 
 # Extra options to supply to gtkdoc-scan.
-SCAN_OPTIONS=--rebuild-types --rebuild-sections --ignore-decorators="NM_AVAILABLE_IN_\d_\d\d?|NM_DEPRECATED_IN_\d_\d\d?"
+SCAN_OPTIONS=--rebuild-types --rebuild-sections --ignore-decorators='NM_AVAILABLE_IN_\d+_\d+|NM_DEPRECATED_IN_\d+_\d+|NM_DEPRECATED_IN_\d+_\d+_FOR\(\)'
 
 # Extra options to supply to gtkdoc-mkdb.
 MKDB_OPTIONS=--sgml-mode --output-format=xml
@@ -38,41 +38,30 @@ CFILE_GLOB=$(top_srcdir)/src/libnm-core-impl/*.c $(top_srcdir)/src/libnm-client-
 
 # Header files to ignore when scanning.
 IGNORE_HFILES= \
-	common.h \
+	nm-core-types.h \
-	nm-core-internal.h \
+	\
-	nm-core-tests-enum-types.h \
-	nm-crypto-impl.h \
-	nm-crypto.h \
 	nm-dbus-helpers.h \
-	nm-default-libnm-core.h \
+	nm-default-libnm.h \
 	nm-device-private.h \
 	nm-dhcp4-config.h \
 	nm-dhcp6-config.h \
 	nm-dns-manager.h \
 	nm-ip4-config.h \
 	nm-ip6-config.h \
-	nm-manager.h \
+	nm-libnm-utils.h \
 	nm-object-private.h \
-	nm-property-compare.h \
 	nm-remote-connection-private.h \
+	\
+	nm-connection-private.h \
+	nm-default-libnm-core.h \
+	nm-property-compare.h \
 	nm-setting-private.h \
+	nm-team-utils.h \
 	nm-utils-private.h \
 	\
+	nm-core-tests-enum-types.h \
 	test-general-enums.h \
 	\
-	nm-keyfile-internal.h \
-	nm-keyfile-utils.h \
-	\
-	nm-auth-subject.h \
-	nm-common-macros.h \
-	nm-ethtool-base.h \
-	nm-libnm-core-utils.h \
-	\
-	nm-dispatcher-api.h \
-	nm-libnm-core-aux.h \
-	\
-	nm-libnm-aux.h \
-	\
 	$(NULL)
 
 # Images to copy into HTML directory.

docs/libnm/libnm-docs.xml

@@ -301,6 +301,7 @@ print ("NetworkManager version " + client.get_version())]]></programlisting></in
     <xi:include href="xml/nm-object.xml"/>
     <xi:include href="xml/nm-errors.xml"/>
     <xi:include href="xml/nm-dbus-interface.xml"/>
+    <xi:include href="xml/nm-vpn-dbus-interface.xml"/>
   </chapter>
 
   <chapter>
@@ -414,7 +415,10 @@ print ("NetworkManager version " + client.get_version())]]></programlisting></in
     <title>Utility API Reference</title>
     <xi:include href="xml/nm-keyfile.xml"/>
     <xi:include href="xml/nm-utils.xml"/>
+    <xi:include href="xml/nm-conn-utils.xml"/>
+    <xi:include href="xml/nm-ethtool-utils.xml"/>
     <xi:include href="xml/nm-version.xml"/>
+    <xi:include href="xml/nm-version-macros.xml"/>
   </chapter>
 
   <chapter>

docs/libnm/meson.build

@@ -1,44 +1,35 @@
 # SPDX-License-Identifier: LGPL-2.1-or-later
 
 private_headers = [
-  'common.h',
+  'nm-core-types.h',
-  'nm-core-internal.h',
+
-  'nm-core-tests-enum-types.h',
-  'nm-crypto-impl.h',
-  'nm-crypto.h',
   'nm-dbus-helpers.h',
-  'nm-default-libnm-core.h',
+  'nm-default-libnm.h',
   'nm-device-private.h',
   'nm-dhcp4-config.h',
   'nm-dhcp6-config.h',
   'nm-dns-manager.h',
   'nm-ip4-config.h',
   'nm-ip6-config.h',
-  'nm-manager.h',
+  'nm-libnm-utils.h',
   'nm-object-private.h',
-  'nm-property-compare.h',
   'nm-remote-connection-private.h',
+
+  'nm-connection-private.h',
+  'nm-default-libnm-core.h',
+  'nm-property-compare.h',
   'nm-setting-private.h',
+  'nm-team-utils.h',
   'nm-utils-private.h',
 
+  'nm-core-tests-enum-types.h',
   'test-general-enums.h',
-
-  'nm-keyfile-internal.h',
-  'nm-keyfile-utils.h',
-
-  'nm-auth-subject.h',
-  'nm-common-macros.h',
-  'nm-ethtool-base.h',
-  'nm-libnm-core-utils.h',
-
-  'nm-dispatcher-api.h',
-  'nm-libnm-core-aux.h',
 ]
 
 scan_args = [
   '--rebuild-types',
   '--rebuild-sections',
-  '--ignore-decorators=NM_AVAILABLE_IN_\d_\d\d?|NM_DEPRECATED_IN_\d_\d\d?',
+  '--ignore-decorators=NM_AVAILABLE_IN_\d+_\d+|NM_DEPRECATED_IN_\d+_\d+|NM_DEPRECATED_IN_\d+_\d+_FOR\(\)',
   '--ignore-headers=' + ' '.join(private_headers),
 ]
 

src/core/nm-default-daemon.h

@@ -18,6 +18,7 @@
 #include "nm-version.h"
 
 #include "nm-core-types.h"
+#include "nm-errors.h"
 #include "nm-types.h"
 #include "libnm-log-core/nm-logging.h"
 

src/libnm-client-impl/nm-conn-utils.c

@@ -14,6 +14,13 @@
 #include "libnm-glib-aux/nm-secret-utils.h"
 #include "nm-simple-connection.h"
 
+/**
+ * SECTION:nm-conn-utils
+ * @short_description: Connection utilities
+ *
+ * Extra connection functionality.
+ */
+
 static gboolean
 _wg_complete_peer(GPtrArray      **p_peers,
                   NMWireGuardPeer *peer_take,

src/libnm-client-impl/nm-default-libnm.h

@@ -27,6 +27,7 @@
 #include "nm-client.h"
 #include "nm-vpn-connection.h"
 #include "nm-libnm-utils.h"
+#include "nm-errors.h"
 
 /*****************************************************************************/
 

src/libnm-client-impl/nm-dhcp-config.c

@@ -146,7 +146,7 @@ nm_dhcp_config_class_init(NMDhcpConfigClass *config_class)
                                                    G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
     /**
-     * NMDhcpConfig:options: (type GHashTable(utf8,utf8)):
+     * NMDhcpConfig:options: (type GHashTable(utf8,utf8))
      *
      * The #GHashTable containing options of the configuration.
      **/

src/libnm-client-impl/nm-dns-manager.c

@@ -20,7 +20,7 @@
 
 G_DEFINE_BOXED_TYPE(NMDnsEntry, nm_dns_entry, nm_dns_entry_dup, nm_dns_entry_unref)
 
-struct NMDnsEntry {
+struct _NMDnsEntry {
     guint refcount;
 
     char    *interface;

src/libnm-client-impl/nm-secret-agent-old.c

@@ -964,7 +964,7 @@ nm_secret_agent_old_unregister_finish(NMSecretAgentOld *self, GAsyncResult *resu
 /*****************************************************************************/
 
 /**
- * nm_secret_agent_old_get_secrets: (virtual get_secrets):
+ * nm_secret_agent_old_get_secrets: (virtual get_secrets)
  * @self: a #NMSecretAgentOld
  * @connection: the #NMConnection for which we're asked secrets
  * @setting_name: the name of the secret setting
@@ -1007,7 +1007,7 @@ nm_secret_agent_old_get_secrets(NMSecretAgentOld              *self,
 }
 
 /**
- * nm_secret_agent_old_save_secrets: (virtual save_secrets):
+ * nm_secret_agent_old_save_secrets: (virtual save_secrets)
  * @self: a #NMSecretAgentOld
  * @connection: a #NMConnection
  * @callback: (scope async): a callback, to be invoked when the operation is done
@@ -1034,7 +1034,7 @@ nm_secret_agent_old_save_secrets(NMSecretAgentOld               *self,
 }
 
 /**
- * nm_secret_agent_old_delete_secrets: (virtual delete_secrets):
+ * nm_secret_agent_old_delete_secrets: (virtual delete_secrets)
  * @self: a #NMSecretAgentOld
  * @connection: a #NMConnection
  * @callback: (scope async): a callback, to be invoked when the operation is done

src/libnm-client-public/NetworkManager.h

@@ -15,6 +15,8 @@
 
 #include "nm-core-enum-types.h"
 
+#include "nm-errors.h"
+
 #include "nm-connection.h"
 #include "nm-simple-connection.h"
 #include "nm-keyfile.h"
@@ -120,6 +122,7 @@
 #include "nm-device-tun.h"
 #include "nm-device-veth.h"
 #include "nm-device-vlan.h"
+#include "nm-device-vrf.h"
 #include "nm-device-vxlan.h"
 #include "nm-device-wifi.h"
 #include "nm-device-wifi-p2p.h"

src/libnm-client-public/nm-client.h

@@ -134,7 +134,7 @@ GQuark nm_client_error_quark(void);
  *
  * Since: 1.6
  */
-typedef struct NMDnsEntry NMDnsEntry;
+typedef struct _NMDnsEntry NMDnsEntry;
 
 NM_AVAILABLE_IN_1_6
 GType nm_dns_entry_get_type(void);

src/libnm-client-public/nm-device-dummy.h

@@ -36,8 +36,8 @@ typedef struct _NMDeviceDummyClass NMDeviceDummyClass;
 
 GType nm_device_dummy_get_type(void);
 
-NM_AVAILABLE_IN_1_10
 NM_DEPRECATED_IN_1_24_FOR(nm_device_get_hw_address)
+NM_AVAILABLE_IN_1_10
 const char *nm_device_dummy_get_hw_address(NMDeviceDummy *device);
 
 G_END_DECLS

src/libnm-client-public/nm-device-macsec.h

@@ -53,8 +53,8 @@ GType nm_device_macsec_get_type(void);
 NM_AVAILABLE_IN_1_42
 NMDevice *nm_device_macsec_get_parent(NMDeviceMacsec *device);
 
-NM_AVAILABLE_IN_1_6
 NM_DEPRECATED_IN_1_24_FOR(nm_device_get_hw_address)
+NM_AVAILABLE_IN_1_6
 const char *nm_device_macsec_get_hw_address(NMDeviceMacsec *device);
 
 NM_AVAILABLE_IN_1_6

src/libnm-client-public/nm-device-macvlan.h

@@ -50,8 +50,8 @@ gboolean nm_device_macvlan_get_no_promisc(NMDeviceMacvlan *device);
 NM_AVAILABLE_IN_1_2
 gboolean nm_device_macvlan_get_tap(NMDeviceMacvlan *device);
 
-NM_AVAILABLE_IN_1_2
 NM_DEPRECATED_IN_1_24_FOR(nm_device_get_hw_address)
+NM_AVAILABLE_IN_1_2
 const char *nm_device_macvlan_get_hw_address(NMDeviceMacvlan *device);
 
 G_END_DECLS

src/libnm-client-public/nm-device-ovs-bridge.h

@@ -38,6 +38,7 @@ typedef struct _NMDeviceOvsBridgeClass NMDeviceOvsBridgeClass;
 NM_AVAILABLE_IN_1_10
 GType nm_device_ovs_bridge_get_type(void);
 
+NM_DEPRECATED_IN_1_34_FOR(nm_device_get_ports)
 NM_AVAILABLE_IN_1_14
 const GPtrArray *nm_device_ovs_bridge_get_slaves(NMDeviceOvsBridge *device);
 

src/libnm-client-public/nm-device-ovs-port.h

@@ -38,6 +38,7 @@ typedef struct _NMDeviceOvsPortClass NMDeviceOvsPortClass;
 NM_AVAILABLE_IN_1_10
 GType nm_device_ovs_port_get_type(void);
 
+NM_DEPRECATED_IN_1_34_FOR(nm_device_get_ports)
 NM_AVAILABLE_IN_1_14
 const GPtrArray *nm_device_ovs_port_get_slaves(NMDeviceOvsPort *device);
 

src/libnm-client-public/nm-device-team.h

@@ -39,8 +39,11 @@ GType nm_device_team_get_type(void);
 NM_DEPRECATED_IN_1_24_FOR(nm_device_get_hw_address)
 const char *nm_device_team_get_hw_address(NMDeviceTeam *device);
 
-gboolean         nm_device_team_get_carrier(NMDeviceTeam *device);
+gboolean nm_device_team_get_carrier(NMDeviceTeam *device);
+
+NM_DEPRECATED_IN_1_34_FOR(nm_device_get_ports)
 const GPtrArray *nm_device_team_get_slaves(NMDeviceTeam *device);
+
 NM_AVAILABLE_IN_1_4
 const char *nm_device_team_get_config(NMDeviceTeam *device);
 

src/libnm-client-public/nm-device-tun.h

@@ -42,8 +42,8 @@ typedef struct _NMDeviceTunClass NMDeviceTunClass;
 NM_AVAILABLE_IN_1_2
 GType nm_device_tun_get_type(void);
 
-NM_AVAILABLE_IN_1_2
 NM_DEPRECATED_IN_1_24_FOR(nm_device_get_hw_address)
+NM_AVAILABLE_IN_1_2
 const char *nm_device_tun_get_hw_address(NMDeviceTun *device);
 
 NM_AVAILABLE_IN_1_2

src/libnm-client-public/nm-device-vxlan.h

@@ -54,8 +54,8 @@ typedef struct _NMDeviceVxlanClass NMDeviceVxlanClass;
 NM_AVAILABLE_IN_1_2
 GType nm_device_vxlan_get_type(void);
 
-NM_AVAILABLE_IN_1_2
 NM_DEPRECATED_IN_1_24_FOR(nm_device_get_hw_address)
+NM_AVAILABLE_IN_1_2
 const char *nm_device_vxlan_get_hw_address(NMDeviceVxlan *device);
 
 NM_AVAILABLE_IN_1_42

src/libnm-client-public/nm-device-wifi-p2p.h

@@ -40,8 +40,8 @@ typedef struct _NMDeviceWifiP2PClass NMDeviceWifiP2PClass;
 NM_AVAILABLE_IN_1_16
 GType nm_device_wifi_p2p_get_type(void);
 
-NM_AVAILABLE_IN_1_16
 NM_DEPRECATED_IN_1_24_FOR(nm_device_get_hw_address)
+NM_AVAILABLE_IN_1_16
 const char *nm_device_wifi_p2p_get_hw_address(NMDeviceWifiP2P *device);
 
 NM_AVAILABLE_IN_1_42

src/libnm-core-impl/nm-default-libnm-core.h

@@ -16,6 +16,7 @@
 /*****************************************************************************/
 
 #include "nm-version.h"
+#include "nm-errors.h"
 
 /*****************************************************************************/
 

src/libnm-core-impl/nm-setting-8021x.c

@@ -1604,7 +1604,7 @@ nm_setting_802_1x_get_phase2_ca_cert_path(NMSetting8021x *setting)
  * nm_setting_802_1x_get_phase2_ca_cert_blob() and
  * nm_setting_802_1x_get_phase2_ca_cert_path().
  *
- * Currently, it's limited to PKCS#11 URIs ('pkcs11' scheme as defined by RFC
+ * Currently, it's limited to PKCS#<!-- -->11 URIs ('pkcs11' scheme as defined by RFC
  * 7512), but may be extended to other schemes in future (such as 'file' URIs
  * for local files and 'data' URIs for inline certificate data).
  *
@@ -1940,7 +1940,7 @@ nm_setting_802_1x_get_phase2_client_cert_path(NMSetting8021x *setting)
  * nm_setting_802_1x_get_phase2_ca_cert_blob() and
  * nm_setting_802_1x_get_phase2_ca_cert_path().
  *
- * Currently, it's limited to PKCS#11 URIs ('pkcs11' scheme as defined by RFC
+ * Currently, it's limited to PKCS#<!-- -->11 URIs ('pkcs11' scheme as defined by RFC
  * 7512), but may be extended to other schemes in future (such as 'file' URIs
  * for local files and 'data' URIs for inline certificate data).
  *
@@ -2176,7 +2176,7 @@ nm_setting_802_1x_get_private_key_path(NMSetting8021x *setting)
  * nm_setting_802_1x_get_private_key_blob() and
  * nm_setting_802_1x_get_private_key_path().
  *
- * Currently, it's limited to PKCS#11 URIs ('pkcs11' scheme as defined by RFC
+ * Currently, it's limited to PKCS#<!-- -->11 URIs ('pkcs11' scheme as defined by RFC
  * 7512), but may be extended to other schemes in future (such as 'file' URIs
  * for local files and 'data' URIs for inline certificate data).
  *
@@ -2379,7 +2379,7 @@ nm_setting_802_1x_get_phase2_private_key_path(NMSetting8021x *setting)
  * nm_setting_802_1x_get_phase2_private_key_blob() and
  * nm_setting_802_1x_get_phase2_private_key_path().
  *
- * Currently, it's limited to PKCS#11 URIs ('pkcs11' scheme as defined by RFC
+ * Currently, it's limited to PKCS#<!-- -->11 URIs ('pkcs11' scheme as defined by RFC
  * 7512), but may be extended to other schemes in future (such as 'file' URIs
  * for local files and 'data' URIs for inline certificate data).
  *

src/libnm-core-impl/nm-setting-bond.c

@@ -601,7 +601,7 @@ handle_error:
 /**
  * nm_setting_bond_validate_option:
  * @name: the name of the option to validate
- * @value (allow-none): the value of the option to validate.
+ * @value: (allow-none): the value of the option to validate.
  *
  * Checks whether @name is a valid bond option and @value is a valid value for
  * the @name. If @value is %NULL, the function only validates the option name.
@@ -1273,7 +1273,7 @@ nm_setting_bond_class_init(NMSettingBondClass *klass)
     setting_class->verify = verify;
 
     /**
-     * NMSettingBond:options: (type GHashTable(utf8,utf8)):
+     * NMSettingBond:options: (type GHashTable(utf8,utf8))
      *
      * Dictionary of key/value pairs of bonding options.  Both keys and values
      * must be strings. Option names must contain only alphanumeric characters

src/libnm-core-impl/nm-setting-ethtool.c

@@ -29,7 +29,7 @@
  *
  * Checks whether @optname is a valid option name for an offload feature.
  *
- * %Returns: %TRUE, if @optname is valid
+ * Returns: %TRUE, if @optname is valid
  *
  * Note that nm_ethtool_optname_is_feature() was first added to the libnm header files
  * in 1.14.0 but forgot to actually add to the library. This happened belatedly in 1.20.0 and
@@ -49,7 +49,7 @@ nm_ethtool_optname_is_feature(const char *optname)
  *
  * Checks whether @optname is a valid option name for a coalesce setting.
  *
- * %Returns: %TRUE, if @optname is valid
+ * Returns: %TRUE, if @optname is valid
  *
  * Since: 1.26
  */
@@ -65,7 +65,7 @@ nm_ethtool_optname_is_coalesce(const char *optname)
  *
  * Checks whether @optname is a valid option name for a ring setting.
  *
- * %Returns: %TRUE, if @optname is valid
+ * Returns: %TRUE, if @optname is valid
  *
  * Since: 1.26
  */
@@ -81,7 +81,7 @@ nm_ethtool_optname_is_ring(const char *optname)
  *
  * Checks whether @optname is a valid option name for a pause setting.
  *
- * %Returns: %TRUE, if @optname is valid
+ * Returns: %TRUE, if @optname is valid
  *
  * Since: 1.32
  */

src/libnm-core-impl/nm-setting-vpn.c

@@ -1132,7 +1132,7 @@ nm_setting_vpn_class_init(NMSettingVpnClass *klass)
                                                persistent);
 
     /**
-     * NMSettingVpn:data: (type GHashTable(utf8,utf8)):
+     * NMSettingVpn:data: (type GHashTable(utf8,utf8))
      *
      * Dictionary of key/value pairs of VPN plugin specific data.  Both keys and
      * values must be strings.
@@ -1155,7 +1155,7 @@ nm_setting_vpn_class_init(NMSettingVpnClass *klass)
                                  &nm_sett_info_propert_type_strdict);
 
     /**
-     * NMSettingVpn:secrets: (type GHashTable(utf8,utf8)):
+     * NMSettingVpn:secrets: (type GHashTable(utf8,utf8))
      *
      * Dictionary of key/value pairs of VPN plugin specific secrets like
      * passwords or private keys.  Both keys and values must be strings.

src/libnm-core-impl/nm-setting-wired.c

@@ -1557,7 +1557,7 @@ nm_setting_wired_class_init(NMSettingWiredClass *klass)
                                               s390_nettype);
 
     /**
-     * NMSettingWired:s390-options: (type GHashTable(utf8,utf8)):
+     * NMSettingWired:s390-options: (type GHashTable(utf8,utf8))
      *
      * Dictionary of key/value pairs of s390-specific device options.  Both keys
      * and values must be strings.  Allowed keys include "portno", "layer2",

src/libnm-core-public/nm-connection.h

@@ -13,7 +13,6 @@
 
 #include "nm-core-types.h"
 #include "nm-setting.h"
-#include "nm-errors.h"
 
 G_BEGIN_DECLS
 

src/libnm-core-public/nm-utils.h

@@ -172,6 +172,7 @@ gboolean nm_utils_iface_valid_name(const char *name);
 NM_AVAILABLE_IN_1_6
 gboolean nm_utils_is_valid_iface_name(const char *name, GError **error);
 
+NM_DEPRECATED_IN_1_32
 gboolean nm_utils_is_uuid(const char *str);
 
 /**

tools/check-docs.sh

@@ -69,12 +69,35 @@ F2="$(grep -l "$(sed -n 's/^[\t ]*\(.*_get_type\);/\1/p' "$SOURCEDIR/src/libnm-c
 F2_EXTRA="
 annotation-glossary
 api-index-full
+nm-conn-utils
 nm-dbus-interface
 nm-errors
+nm-ethtool-utils
 nm-keyfile
 nm-utils
 nm-version
+nm-version-macros
+nm-vpn-dbus-interface
 "
 if ! same_lines "$F1"$'\n'"$F1_EXTRA" "$F2"$'\n'"$F2_EXTRA"; then
     die "*** Error: libnm classes not included in docs/libnm/libnm-docs.xml ***"
 fi
+
+F1="$(sed -n 's/^#include "\(nm-.*\).h"$/xml\/\1.xml/p' "$SOURCEDIR/src/libnm-client-public/NetworkManager.h")"
+F1_EXTRA="
+xml/annotation-glossary.xml
+xml/api-index-full.xml
+xml/nm-setting-ovs-external-ids.xml
+xml/nm-version-macros.xml
+xml/nm-secret-agent-old.xml
+xml/nm-vpn-plugin-old.xml
+"
+F2="$(sed -n 's/.*<xi:include href="\(xml\/.*.xml\)".*/\1/p' "$SOURCEDIR/docs/libnm/libnm-docs.xml")"
+F2_EXTRA="
+xml/nm-autoptr.xml
+xml/nm-core-enum-types.xml
+xml/nm-enum-types.xml
+"
+if ! same_lines "$F1"$'\n'"$F1_EXTRA" "$F2"$'\n'"$F2_EXTRA"; then
+    die "*** Error: documentation from public headers not included in docs/libnm/libnm-docs.xml ***"
+fi