From 3f6af3360b7e2b059e14e6d86ad2b147780bd61d Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 10 Mar 2017 20:08:29 +0100 Subject: [PATCH 01/13] libnm-core/8021x: add a missing colon in gtk-doc The universe is now perfect. --- libnm-core/nm-setting-8021x.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libnm-core/nm-setting-8021x.h b/libnm-core/nm-setting-8021x.h index ac38d94e9..073d6e885 100644 --- a/libnm-core/nm-setting-8021x.h +++ b/libnm-core/nm-setting-8021x.h @@ -76,7 +76,7 @@ typedef enum { /*< underscore_name=nm_setting_802_1x_ck_scheme >*/ } NMSetting8021xCKScheme; /** - * NMSetting8021xAuthFlags + * NMSetting8021xAuthFlags: * @NM_SETTING_802_1X_AUTH_FLAGS_NONE: No flags * @NM_SETTING_802_1X_AUTH_FLAGS_TLS_1_0_DISABLE: Disable TLSv1.0 * @NM_SETTING_802_1X_AUTH_FLAGS_TLS_1_1_DISABLE: Disable TLSv1.1 From b0da972f5fa51608cca5837af9fe7094818204f8 Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 10 Mar 2017 20:19:30 +0100 Subject: [PATCH 02/13] doc: sort "connection" settings first in nm-settings manual --- libnm/generate-setting-docs.py | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/libnm/generate-setting-docs.py b/libnm/generate-setting-docs.py index e1ea9723d..0a4adae3a 100755 --- a/libnm/generate-setting-docs.py +++ b/libnm/generate-setting-docs.py @@ -162,6 +162,14 @@ def get_default_value(setting, pspec, propxml): return default_value +def cmp_settings(x,y): + x_prefix = x.attrib['{%s}symbol-prefix' % ns_map['c']] + y_prefix = y.attrib['{%s}symbol-prefix' % ns_map['c']] + if x_prefix == "setting_connection": + # Always sort NMSettingConnection first + return -1; + return cmp(x_prefix, y_prefix) + def escape(val): return str(val).replace('"', '"') @@ -186,7 +194,7 @@ settings = girxml.findall('./gi:namespace/gi:class[@parent="Setting"]', ns_map) # Hack. Need a better way to do this ipxml = girxml.find('./gi:namespace/gi:class[@name="SettingIPConfig"]', ns_map) settings.extend(girxml.findall('./gi:namespace/gi:class[@parent="SettingIPConfig"]', ns_map)) -settings = sorted(settings, key=lambda setting: setting.attrib['{%s}symbol-prefix' % ns_map['c']]) +settings = sorted(settings, cmp=cmp_settings) init_constants(girxml, settings) From f6e9b1d328283d9328e1b0a3e78fafb4bedc6c37 Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 10 Mar 2017 18:58:34 +0100 Subject: [PATCH 03/13] introspection: include short description everywhere --- introspection/org.freedesktop.NetworkManager.AccessPoint.xml | 5 +++++ .../org.freedesktop.NetworkManager.AgentManager.xml | 5 +++++ introspection/org.freedesktop.NetworkManager.Checkpoint.xml | 1 + .../org.freedesktop.NetworkManager.Connection.Active.xml | 1 + introspection/org.freedesktop.NetworkManager.DHCP4Config.xml | 1 + introspection/org.freedesktop.NetworkManager.DHCP6Config.xml | 1 + introspection/org.freedesktop.NetworkManager.Device.Adsl.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.Bluetooth.xml | 5 +++++ introspection/org.freedesktop.NetworkManager.Device.Bond.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.Bridge.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.Dummy.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.Generic.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.IPTunnel.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.Infiniband.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.Macsec.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.Macvlan.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.Modem.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.OlpcMesh.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.Statistics.xml | 5 +++++ introspection/org.freedesktop.NetworkManager.Device.Team.xml | 5 +++++ introspection/org.freedesktop.NetworkManager.Device.Tun.xml | 5 +++++ introspection/org.freedesktop.NetworkManager.Device.Veth.xml | 5 +++++ introspection/org.freedesktop.NetworkManager.Device.Vlan.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.Vxlan.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.WiMax.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.Wired.xml | 5 +++++ .../org.freedesktop.NetworkManager.Device.Wireless.xml | 5 +++++ introspection/org.freedesktop.NetworkManager.Device.xml | 5 +++++ introspection/org.freedesktop.NetworkManager.DnsManager.xml | 1 + introspection/org.freedesktop.NetworkManager.IP4Config.xml | 5 +++++ introspection/org.freedesktop.NetworkManager.IP6Config.xml | 5 +++++ introspection/org.freedesktop.NetworkManager.PPP.xml | 5 +++++ introspection/org.freedesktop.NetworkManager.SecretAgent.xml | 1 + .../org.freedesktop.NetworkManager.Settings.Connection.xml | 1 + introspection/org.freedesktop.NetworkManager.Settings.xml | 1 + .../org.freedesktop.NetworkManager.VPN.Connection.xml | 1 + introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml | 1 + introspection/org.freedesktop.NetworkManager.WiMax.Nsp.xml | 5 +++++ introspection/org.freedesktop.NetworkManager.xml | 5 +++++ 39 files changed, 155 insertions(+) diff --git a/introspection/org.freedesktop.NetworkManager.AccessPoint.xml b/introspection/org.freedesktop.NetworkManager.AccessPoint.xml index 617c8671b..769ab7a93 100644 --- a/introspection/org.freedesktop.NetworkManager.AccessPoint.xml +++ b/introspection/org.freedesktop.NetworkManager.AccessPoint.xml @@ -1,5 +1,10 @@ + diff --git a/introspection/org.freedesktop.NetworkManager.Connection.Active.xml b/introspection/org.freedesktop.NetworkManager.Connection.Active.xml index 383ede34a..3ffa4cd67 100644 --- a/introspection/org.freedesktop.NetworkManager.Connection.Active.xml +++ b/introspection/org.freedesktop.NetworkManager.Connection.Active.xml @@ -3,6 +3,7 @@ diff --git a/introspection/org.freedesktop.NetworkManager.DHCP6Config.xml b/introspection/org.freedesktop.NetworkManager.DHCP6Config.xml index 09e2ca867..0f064c4c8 100644 --- a/introspection/org.freedesktop.NetworkManager.DHCP6Config.xml +++ b/introspection/org.freedesktop.NetworkManager.DHCP6Config.xml @@ -3,6 +3,7 @@ diff --git a/introspection/org.freedesktop.NetworkManager.Device.Adsl.xml b/introspection/org.freedesktop.NetworkManager.Device.Adsl.xml index 0986f0699..ef1f580f0 100644 --- a/introspection/org.freedesktop.NetworkManager.Device.Adsl.xml +++ b/introspection/org.freedesktop.NetworkManager.Device.Adsl.xml @@ -1,5 +1,10 @@ + diff --git a/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml b/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml index 1973b417d..bff89120a 100644 --- a/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml +++ b/introspection/org.freedesktop.NetworkManager.Device.Wireless.xml @@ -1,5 +1,10 @@ + diff --git a/introspection/org.freedesktop.NetworkManager.Device.xml b/introspection/org.freedesktop.NetworkManager.Device.xml index d4535a84d..ee424101e 100644 --- a/introspection/org.freedesktop.NetworkManager.Device.xml +++ b/introspection/org.freedesktop.NetworkManager.Device.xml @@ -1,5 +1,10 @@ + diff --git a/introspection/org.freedesktop.NetworkManager.IP4Config.xml b/introspection/org.freedesktop.NetworkManager.IP4Config.xml index 17f57bc68..0b04af94e 100644 --- a/introspection/org.freedesktop.NetworkManager.IP4Config.xml +++ b/introspection/org.freedesktop.NetworkManager.IP4Config.xml @@ -1,5 +1,10 @@ + diff --git a/introspection/org.freedesktop.NetworkManager.SecretAgent.xml b/introspection/org.freedesktop.NetworkManager.SecretAgent.xml index 33296fb06..654b3f2f0 100644 --- a/introspection/org.freedesktop.NetworkManager.SecretAgent.xml +++ b/introspection/org.freedesktop.NetworkManager.SecretAgent.xml @@ -3,6 +3,7 @@ diff --git a/introspection/org.freedesktop.NetworkManager.Settings.xml b/introspection/org.freedesktop.NetworkManager.Settings.xml index 32675e02d..61940f912 100644 --- a/introspection/org.freedesktop.NetworkManager.Settings.xml +++ b/introspection/org.freedesktop.NetworkManager.Settings.xml @@ -3,6 +3,7 @@ diff --git a/introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml b/introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml index 7eed97210..0c68f76e2 100644 --- a/introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml +++ b/introspection/org.freedesktop.NetworkManager.VPN.Plugin.xml @@ -3,6 +3,7 @@ From 7bd69aa08d99583c9824ab4145fcba1ff089b497 Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 10 Mar 2017 20:04:34 +0100 Subject: [PATCH 04/13] libnm-core: sensible docstrings for NMSettings* --- libnm-core/nm-setting-8021x.h | 2 ++ libnm-core/nm-setting-adsl.h | 2 ++ libnm-core/nm-setting-bluetooth.h | 2 ++ libnm-core/nm-setting-bond.h | 2 ++ libnm-core/nm-setting-bridge-port.h | 2 ++ libnm-core/nm-setting-bridge.h | 2 ++ libnm-core/nm-setting-cdma.h | 2 ++ libnm-core/nm-setting-connection.h | 3 +-- libnm-core/nm-setting-dcb.h | 2 ++ libnm-core/nm-setting-dummy.h | 2 ++ libnm-core/nm-setting-generic.h | 2 ++ libnm-core/nm-setting-gsm.h | 2 ++ libnm-core/nm-setting-infiniband.h | 2 ++ libnm-core/nm-setting-ip-tunnel.h | 2 ++ libnm-core/nm-setting-ip4-config.h | 2 ++ libnm-core/nm-setting-ip6-config.h | 2 ++ libnm-core/nm-setting-macsec.h | 2 ++ libnm-core/nm-setting-macvlan.h | 2 ++ libnm-core/nm-setting-olpc-mesh.h | 2 ++ libnm-core/nm-setting-ppp.h | 2 ++ libnm-core/nm-setting-pppoe.h | 2 ++ libnm-core/nm-setting-proxy.h | 5 +++++ libnm-core/nm-setting-serial.h | 2 ++ libnm-core/nm-setting-team-port.h | 2 ++ libnm-core/nm-setting-team.h | 2 ++ libnm-core/nm-setting-tun.h | 2 ++ libnm-core/nm-setting-vlan.h | 2 ++ libnm-core/nm-setting-vpn.h | 2 ++ libnm-core/nm-setting-vxlan.h | 2 ++ libnm-core/nm-setting-wimax.h | 2 ++ libnm-core/nm-setting-wired.h | 2 ++ libnm-core/nm-setting-wireless-security.h | 2 ++ libnm-core/nm-setting-wireless.h | 2 ++ 33 files changed, 68 insertions(+), 2 deletions(-) diff --git a/libnm-core/nm-setting-8021x.h b/libnm-core/nm-setting-8021x.h index 073d6e885..0f5f7ddd9 100644 --- a/libnm-core/nm-setting-8021x.h +++ b/libnm-core/nm-setting-8021x.h @@ -174,6 +174,8 @@ typedef enum { /*< underscore_name=nm_setting_802_1x_auth_flags >*/ /** * NMSetting8021x: + * + * AIEEE 802.1x Authentication Settings */ struct _NMSetting8021x { NMSetting parent; diff --git a/libnm-core/nm-setting-adsl.h b/libnm-core/nm-setting-adsl.h index d1f975e96..4f04355ec 100644 --- a/libnm-core/nm-setting-adsl.h +++ b/libnm-core/nm-setting-adsl.h @@ -56,6 +56,8 @@ G_BEGIN_DECLS /** * NMSettingAdsl: + * + * ADSL Settings */ struct _NMSettingAdsl { NMSetting parent; diff --git a/libnm-core/nm-setting-bluetooth.h b/libnm-core/nm-setting-bluetooth.h index 6746782e7..312aab144 100644 --- a/libnm-core/nm-setting-bluetooth.h +++ b/libnm-core/nm-setting-bluetooth.h @@ -61,6 +61,8 @@ G_BEGIN_DECLS /** * NMSettingBluetooth: + * + * Bluetooth Settings */ struct _NMSettingBluetooth { NMSetting parent; diff --git a/libnm-core/nm-setting-bond.h b/libnm-core/nm-setting-bond.h index ee2da9777..e2d8f9b56 100644 --- a/libnm-core/nm-setting-bond.h +++ b/libnm-core/nm-setting-bond.h @@ -72,6 +72,8 @@ G_BEGIN_DECLS /** * NMSettingBond: + * + * Bonding Settings */ struct _NMSettingBond { NMSetting parent; diff --git a/libnm-core/nm-setting-bridge-port.h b/libnm-core/nm-setting-bridge-port.h index 690f9d0df..0ff6d9f13 100644 --- a/libnm-core/nm-setting-bridge-port.h +++ b/libnm-core/nm-setting-bridge-port.h @@ -45,6 +45,8 @@ G_BEGIN_DECLS /** * NMSettingBridgePort: + * + * Bridge Port Settings */ struct _NMSettingBridgePort { NMSetting parent; diff --git a/libnm-core/nm-setting-bridge.h b/libnm-core/nm-setting-bridge.h index 918b9c16c..81e4c6442 100644 --- a/libnm-core/nm-setting-bridge.h +++ b/libnm-core/nm-setting-bridge.h @@ -50,6 +50,8 @@ G_BEGIN_DECLS /** * NMSettingBridge: + * + * Bridging Settings */ struct _NMSettingBridge { NMSetting parent; diff --git a/libnm-core/nm-setting-cdma.h b/libnm-core/nm-setting-cdma.h index 85ad3e4c8..6e429bd12 100644 --- a/libnm-core/nm-setting-cdma.h +++ b/libnm-core/nm-setting-cdma.h @@ -48,6 +48,8 @@ G_BEGIN_DECLS /** * NMSettingCdma: + * + * CDMA-based Mobile Broadband Settings */ struct _NMSettingCdma { NMSetting parent; diff --git a/libnm-core/nm-setting-connection.h b/libnm-core/nm-setting-connection.h index 89fa64ce6..bd5b98ff4 100644 --- a/libnm-core/nm-setting-connection.h +++ b/libnm-core/nm-setting-connection.h @@ -99,8 +99,7 @@ typedef enum { /** * NMSettingConnection: * - * The NMSettingConnection struct contains only private data. - * It should only be accessed through the functions described below. + * General Connection Profile Settings */ struct _NMSettingConnection { NMSetting parent; diff --git a/libnm-core/nm-setting-dcb.h b/libnm-core/nm-setting-dcb.h index 4a3c7329d..d2a364a22 100644 --- a/libnm-core/nm-setting-dcb.h +++ b/libnm-core/nm-setting-dcb.h @@ -94,6 +94,8 @@ typedef enum { /*< flags >*/ /** * NMSettingDcb: + * + * Data Center Bridging Settings */ struct _NMSettingDcb { NMSetting parent; diff --git a/libnm-core/nm-setting-dummy.h b/libnm-core/nm-setting-dummy.h index fdeb76059..62fe3fa67 100644 --- a/libnm-core/nm-setting-dummy.h +++ b/libnm-core/nm-setting-dummy.h @@ -41,6 +41,8 @@ G_BEGIN_DECLS /** * NMSettingDummy: + * + * Dummy Link Settings */ struct _NMSettingDummy { NMSetting parent; diff --git a/libnm-core/nm-setting-generic.h b/libnm-core/nm-setting-generic.h index a5e94f625..864b90049 100644 --- a/libnm-core/nm-setting-generic.h +++ b/libnm-core/nm-setting-generic.h @@ -41,6 +41,8 @@ G_BEGIN_DECLS /** * NMSettingGeneric: + * + * Generic Link Settings */ struct _NMSettingGeneric { NMSetting parent; diff --git a/libnm-core/nm-setting-gsm.h b/libnm-core/nm-setting-gsm.h index 8dd4793ef..8516698db 100644 --- a/libnm-core/nm-setting-gsm.h +++ b/libnm-core/nm-setting-gsm.h @@ -56,6 +56,8 @@ G_BEGIN_DECLS /** * NMSettingGsm: + * + * GSM-based Mobile Broadband Settings */ struct _NMSettingGsm { NMSetting parent; diff --git a/libnm-core/nm-setting-infiniband.h b/libnm-core/nm-setting-infiniband.h index 30e1158fe..ff78b3dce 100644 --- a/libnm-core/nm-setting-infiniband.h +++ b/libnm-core/nm-setting-infiniband.h @@ -47,6 +47,8 @@ G_BEGIN_DECLS /** * NMSettingInfiniband: + * + * Infiniband Settings */ struct _NMSettingInfiniband { NMSetting parent; diff --git a/libnm-core/nm-setting-ip-tunnel.h b/libnm-core/nm-setting-ip-tunnel.h index 081b171b0..dfa621168 100644 --- a/libnm-core/nm-setting-ip-tunnel.h +++ b/libnm-core/nm-setting-ip-tunnel.h @@ -53,6 +53,8 @@ G_BEGIN_DECLS /** * NMSettingIPTunnel: + * + * IP Tunneling Settings */ struct _NMSettingIPTunnel { NMSetting parent; diff --git a/libnm-core/nm-setting-ip4-config.h b/libnm-core/nm-setting-ip4-config.h index adef37546..ca8945093 100644 --- a/libnm-core/nm-setting-ip4-config.h +++ b/libnm-core/nm-setting-ip4-config.h @@ -89,6 +89,8 @@ G_BEGIN_DECLS /** * NMSettingIP4Config: + * + * IPv4 Settings */ struct _NMSettingIP4Config { NMSettingIPConfig parent; diff --git a/libnm-core/nm-setting-ip6-config.h b/libnm-core/nm-setting-ip6-config.h index 8e2c7771d..e01a36b75 100644 --- a/libnm-core/nm-setting-ip6-config.h +++ b/libnm-core/nm-setting-ip6-config.h @@ -139,6 +139,8 @@ typedef enum { /** * NMSettingIP6Config: + * + * IPv6 Settings */ struct _NMSettingIP6Config { NMSettingIPConfig parent; diff --git a/libnm-core/nm-setting-macsec.h b/libnm-core/nm-setting-macsec.h index f9431dfe5..6a524faab 100644 --- a/libnm-core/nm-setting-macsec.h +++ b/libnm-core/nm-setting-macsec.h @@ -50,6 +50,8 @@ G_BEGIN_DECLS /** * NMSettingMacsec: + * + * MACSec Settings */ struct _NMSettingMacsec { NMSetting parent; diff --git a/libnm-core/nm-setting-macvlan.h b/libnm-core/nm-setting-macvlan.h index 33860aacc..605efd0f9 100644 --- a/libnm-core/nm-setting-macvlan.h +++ b/libnm-core/nm-setting-macvlan.h @@ -46,6 +46,8 @@ G_BEGIN_DECLS /** * NMSettingMacvlan: + * + * MAC VLAN Settings */ struct _NMSettingMacvlan { NMSetting parent; diff --git a/libnm-core/nm-setting-olpc-mesh.h b/libnm-core/nm-setting-olpc-mesh.h index 162373b3e..69b3c6e96 100644 --- a/libnm-core/nm-setting-olpc-mesh.h +++ b/libnm-core/nm-setting-olpc-mesh.h @@ -46,6 +46,8 @@ G_BEGIN_DECLS /** * NMSettingOlpcMesh: + * + * OLPC Wireless Mesh Settings */ struct _NMSettingOlpcMesh { NMSetting parent; diff --git a/libnm-core/nm-setting-ppp.h b/libnm-core/nm-setting-ppp.h index 39b578b35..01536d84c 100644 --- a/libnm-core/nm-setting-ppp.h +++ b/libnm-core/nm-setting-ppp.h @@ -61,6 +61,8 @@ G_BEGIN_DECLS /** * NMSettingPpp: + * + * Point-to-Point Protocol Settings */ struct _NMSettingPpp { NMSetting parent; diff --git a/libnm-core/nm-setting-pppoe.h b/libnm-core/nm-setting-pppoe.h index 56d42efd3..b6717cde8 100644 --- a/libnm-core/nm-setting-pppoe.h +++ b/libnm-core/nm-setting-pppoe.h @@ -47,6 +47,8 @@ G_BEGIN_DECLS /** * NMSettingPppoe: + * + * PPP-over-Ethernet Settings */ struct _NMSettingPppoe { NMSetting parent; diff --git a/libnm-core/nm-setting-proxy.h b/libnm-core/nm-setting-proxy.h index e80789b4a..0c72799f8 100644 --- a/libnm-core/nm-setting-proxy.h +++ b/libnm-core/nm-setting-proxy.h @@ -58,6 +58,11 @@ typedef enum { #define NM_SETTING_PROXY_PAC_URL "pac-url" #define NM_SETTING_PROXY_PAC_SCRIPT "pac-script" +/** + * NMSettingProxy: + * + * WWW Proxy Settings + */ struct _NMSettingProxy { NMSetting parent; }; diff --git a/libnm-core/nm-setting-serial.h b/libnm-core/nm-setting-serial.h index 16cad3fae..2362b2463 100644 --- a/libnm-core/nm-setting-serial.h +++ b/libnm-core/nm-setting-serial.h @@ -62,6 +62,8 @@ typedef enum { /** * NMSettingSerial: + * + * Serial Link Settings */ struct _NMSettingSerial { NMSetting parent; diff --git a/libnm-core/nm-setting-team-port.h b/libnm-core/nm-setting-team-port.h index 3b9dc09e2..4fcc51083 100644 --- a/libnm-core/nm-setting-team-port.h +++ b/libnm-core/nm-setting-team-port.h @@ -42,6 +42,8 @@ G_BEGIN_DECLS /** * NMSettingTeamPort: + * + * Team Port Settings */ struct _NMSettingTeamPort { NMSetting parent; diff --git a/libnm-core/nm-setting-team.h b/libnm-core/nm-setting-team.h index baaa073d4..532963aac 100644 --- a/libnm-core/nm-setting-team.h +++ b/libnm-core/nm-setting-team.h @@ -42,6 +42,8 @@ G_BEGIN_DECLS /** * NMSettingTeam: + * + * Teaming Settings */ struct _NMSettingTeam { NMSetting parent; diff --git a/libnm-core/nm-setting-tun.h b/libnm-core/nm-setting-tun.h index 63c0cbd8c..d977e381f 100644 --- a/libnm-core/nm-setting-tun.h +++ b/libnm-core/nm-setting-tun.h @@ -62,6 +62,8 @@ typedef enum { /** * NMSettingTun: + * + * Tunnel Settings */ struct _NMSettingTun { NMSetting parent; diff --git a/libnm-core/nm-setting-vlan.h b/libnm-core/nm-setting-vlan.h index b147a1857..ec41b5950 100644 --- a/libnm-core/nm-setting-vlan.h +++ b/libnm-core/nm-setting-vlan.h @@ -48,6 +48,8 @@ G_BEGIN_DECLS /** * NMSettingVlan: + * + * VLAN Settings */ struct _NMSettingVlan { NMSetting parent; diff --git a/libnm-core/nm-setting-vpn.h b/libnm-core/nm-setting-vpn.h index 79f3d642b..115aa8676 100644 --- a/libnm-core/nm-setting-vpn.h +++ b/libnm-core/nm-setting-vpn.h @@ -49,6 +49,8 @@ G_BEGIN_DECLS /** * NMSettingVpn: + * + * VPN Settings */ struct _NMSettingVpn { NMSetting parent; diff --git a/libnm-core/nm-setting-vxlan.h b/libnm-core/nm-setting-vxlan.h index fab2d8201..ce2669411 100644 --- a/libnm-core/nm-setting-vxlan.h +++ b/libnm-core/nm-setting-vxlan.h @@ -58,6 +58,8 @@ G_BEGIN_DECLS /** * NMSettingVxlan: + * + * VXLAN Settings */ struct _NMSettingVxlan { NMSetting parent; diff --git a/libnm-core/nm-setting-wimax.h b/libnm-core/nm-setting-wimax.h index b9c86f3ac..fb0abbac9 100644 --- a/libnm-core/nm-setting-wimax.h +++ b/libnm-core/nm-setting-wimax.h @@ -44,6 +44,8 @@ G_BEGIN_DECLS /** * NMSettingWimax: + * + * WiMax Settings */ struct _NMSettingWimax { NMSetting parent; diff --git a/libnm-core/nm-setting-wired.h b/libnm-core/nm-setting-wired.h index 0978ae90f..015f09da3 100644 --- a/libnm-core/nm-setting-wired.h +++ b/libnm-core/nm-setting-wired.h @@ -96,6 +96,8 @@ typedef enum { /*< flags >*/ /** * NMSettingWired: + * + * Wired Ethernet Settings */ struct _NMSettingWired { NMSetting parent; diff --git a/libnm-core/nm-setting-wireless-security.h b/libnm-core/nm-setting-wireless-security.h index 290d4f265..ae252f112 100644 --- a/libnm-core/nm-setting-wireless-security.h +++ b/libnm-core/nm-setting-wireless-security.h @@ -91,6 +91,8 @@ typedef enum { /** * NMSettingWirelessSecurity: + * + * Wi-Fi Security Settings */ struct _NMSettingWirelessSecurity { NMSetting parent; diff --git a/libnm-core/nm-setting-wireless.h b/libnm-core/nm-setting-wireless.h index 1d58903fc..b0ef47568 100644 --- a/libnm-core/nm-setting-wireless.h +++ b/libnm-core/nm-setting-wireless.h @@ -101,6 +101,8 @@ typedef enum { /** * NMSettingWireless: + * + * Wi-Fi Settings */ struct _NMSettingWireless { NMSetting parent; From a1c5f43501958a2546c4da8fbab9224215d44973 Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 10 Mar 2017 20:08:11 +0100 Subject: [PATCH 05/13] libnm/generate-setting-docs.py: include description attribute --- libnm/generate-setting-docs.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/libnm/generate-setting-docs.py b/libnm/generate-setting-docs.py index 0a4adae3a..86fe08cde 100755 --- a/libnm/generate-setting-docs.py +++ b/libnm/generate-setting-docs.py @@ -112,7 +112,7 @@ def get_prop_type(setting, pspec, propxml): return prop_type -def get_docs(setting, pspec, propxml): +def get_docs(propxml): doc_xml = propxml.find('gi:doc', ns_map) if doc_xml is None: return None @@ -215,7 +215,10 @@ for settingxml in settings: new_func = NM.__getattr__(settingxml.attrib['name']) setting = new_func() - outfile.write(" \n" % setting.props.name) + class_desc = get_docs(settingxml) + if class_desc is None: + raise Exception("%s needs a gtk-doc block with one-line description" % setting.props.name) + outfile.write(" \n" % (setting.props.name, class_desc)) setting_properties = { prop.name: prop for prop in GObject.list_properties(setting) } if args.overrides is None: @@ -239,7 +242,7 @@ for settingxml in settings: propxml = ipxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map) value_type = get_prop_type(setting, pspec, propxml) - value_desc = get_docs(setting, pspec, propxml) + value_desc = get_docs(propxml) default_value = get_default_value(setting, pspec, propxml) if prop in setting_overrides: From 96042c41f89778be16f71b3baee8f3421ddb8725 Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 10 Mar 2017 21:02:09 +0100 Subject: [PATCH 06/13] man: include the description for settings --- man/nm-settings.xsl | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/man/nm-settings.xsl b/man/nm-settings.xsl index 733d08aa6..36fb82885 100644 --- a/man/nm-settings.xsl +++ b/man/nm-settings.xsl @@ -126,22 +126,25 @@ - + <xsl:value-of select="@name"/> setting - - - - Key Name - Value Type - Default Value - Value Description - - - - - - -
+ . + + + + + Key Name + Value Type + Default Value + Value Description + + + + + + + + From 74b6a015f7e1d1f72e56d5ffd85ada38687a399b Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 10 Mar 2017 17:25:32 +0100 Subject: [PATCH 07/13] docs/api: reorder the manual pages I guess the daemon and its configuration first makes most sense. --- docs/api/network-manager-docs.xml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index b2fe87e99..660e88a17 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -43,15 +43,15 @@ Manual Pages - - - + + + + - - + From 6926eaeb05f7538eaebd40d4dc8c53ec6bca4e4c Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 10 Mar 2017 17:43:06 +0100 Subject: [PATCH 08/13] docs/api: add standard release information --- docs/api/network-manager-docs.xml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index 660e88a17..7040a92cc 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -6,7 +6,11 @@ NetworkManager Reference Manual - Version &version; + + for NetworkManager &version; + The latest version of this documentation can be found on-line at + https://developer.gnome.org/NetworkManager/stable/. + 2012 From 265269855bae4f878f560e1242bf189643a33ead Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 10 Mar 2017 17:43:12 +0100 Subject: [PATCH 09/13] docs/api: add abstract --- docs/api/network-manager-docs.xml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index 7040a92cc..c8f8bc5c8 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -43,6 +43,26 @@ + + + + This manual is the reference documentation for NetworkManager, the standard + Linux network management service. It is intended for system administrators and + integrators who need to understand the capabilities of NetworkManager, its + configuration options, command line tools and the D-Bus API for programmatic + control of the service. + + + The end users NetworkManager should instead refer to respective documentation + of their desktop environment of choice. + + + The application developers who prefer not to use the D-Bus API directly can use the + libnm library + shipped with NetworkManager or its bindings to a higher level language such as + Python, Ruby or Vala via GObject introspection. + + From c673c5210143316234cb415ce0380aea9f63551e Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 10 Mar 2017 18:40:03 +0100 Subject: [PATCH 10/13] docs/api: make the connection settings look better Turn the it into a chapter with refentries to better fit the structure of the table of contects. Also, include the properties in the index. --- docs/api/Makefile.am | 3 +- docs/api/settings-spec.xsl | 63 +++++++++++++++++++++++++------------- 2 files changed, 44 insertions(+), 22 deletions(-) diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am index 12a6d52f6..f5def7b8b 100644 --- a/docs/api/Makefile.am +++ b/docs/api/Makefile.am @@ -38,8 +38,9 @@ MKTMPL_OPTIONS= # Extra options to supply to gtkdoc-mkhtml MKHTML_OPTIONS=--path="$(abs_srcdir)" -# Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE) +# Files to be included in $(DOC_MAIN_SGML_FILE) content_files = \ + $(GENERATED_FILES) \ dbus-org.freedesktop.NetworkManager.AccessPoint.xml \ dbus-org.freedesktop.NetworkManager.Connection.Active.xml \ dbus-org.freedesktop.NetworkManager.Device.Team.xml \ diff --git a/docs/api/settings-spec.xsl b/docs/api/settings-spec.xsl index 04feb3987..80f27309d 100644 --- a/docs/api/settings-spec.xsl +++ b/docs/api/settings-spec.xsl @@ -9,37 +9,58 @@ /> -
+ Configuration Settings -
+ - - - <xsl:value-of select="@name"/> setting - - - - Key Name - Value Type - Default Value - Value Description - - - - - - -
- + + settings- + + + + + + + <xsl:attribute name="id">settings-<xsl:value-of select="@name"/>.properties</xsl:attribute> + Properties + + + + + + + Key Name + Value Type + Default Value + Value Description + + + + + + +
+ + + - + + + + settings- + + + + + + (see for flag values) From 967207f5bc2c7a73ba87345a52ef9333388a74c0 Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 10 Mar 2017 18:24:07 +0100 Subject: [PATCH 11/13] docs/api: move D-Bus reference after nm-settings --- docs/api/network-manager-docs.xml | 114 +++++++++++++++--------------- 1 file changed, 57 insertions(+), 57 deletions(-) diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index c8f8bc5c8..0ca12d5f4 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -78,63 +78,6 @@ - - D-Bus API Reference - - - This part documents the D-Bus interface used to access the - NetworkManager daemon. - - -
- Interfaces - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-
- Types - - -
- - Network Configuration Setting Specification @@ -192,6 +135,63 @@ + + D-Bus API Reference + + + This part documents the D-Bus interface used to access the + NetworkManager daemon. + + +
+ Interfaces + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ Types + + +
+ + Index From 374abc3f5046e9bb56ff131be15c669578f368e8 Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Fri, 10 Mar 2017 21:14:44 +0100 Subject: [PATCH 12/13] docs/api: restructure This splits the manual into parts and groups the D-Bus interfaces into chapters by the object class. It looks considerably better. --- docs/api/network-manager-docs.xml | 134 +++++++++++++++++++++++------- 1 file changed, 105 insertions(+), 29 deletions(-) diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index 0ca12d5f4..dd5f0e47f 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -65,7 +65,7 @@ - + Manual Pages @@ -76,9 +76,9 @@ - + - + Network Configuration Setting Specification This part documents the properties and value types of each "Setting" @@ -89,16 +89,16 @@ -
+ Configuration Settings (NetworkManager was built without full introspection support. Setting documentation is not available.) -
+ -
+ Secret flag types Each secret property in a setting has an associated "flags" property @@ -132,30 +132,52 @@ -
- + + - - D-Bus API Reference + + D-Bus API Reference This part documents the D-Bus interface used to access the NetworkManager daemon. -
- Interfaces - + + The <literal>/org/freedesktop/NetworkManager</literal> object + - + + + + The <literal>/org/freedesktop/NetworkManager/AgentManager</literal> object + - - + + + + The <literal>/org/freedesktop/NetworkManager/DnsManager</literal> object + + + + + + The <literal>/org/freedesktop/NetworkManager/Settings</literal> object + + + + + + The <literal>/org/freedesktop/NetworkManager/Settings/*</literal> objects + - - + + + + The <literal>/org/freedesktop/NetworkManager/Devices/*</literal> objects + + @@ -176,21 +198,75 @@ - - + + + + + The <literal>/org/freedesktop/NetworkManager/ActiveConnection/*</literal> objects + + + + + + + The <literal>/org/freedesktop/NetworkManager/IP4Config/*</literal> objects + + + + + The <literal>/org/freedesktop/NetworkManager/IP6Config/*</literal> objects + - - - - -
-
+ + + + The <literal>/org/freedesktop/NetworkManager/DHCP4Config/*</literal> objects + + + + + + The <literal>/org/freedesktop/NetworkManager/DHCP4Config/*</literal> objects + + + + + + The <literal>/org/freedesktop/NetworkManager/AccessPoint/*</literal> objects + + + + + Types + + + + + Secret Agent D-Bus API Reference + + + Secret agents + + + + + + + VPN Plugin D-Bus API Reference + + + VPN services + + + + + Types -
- + + Index From a1cf9f4339bf5ba1cdb2ef9c3680d266961acbb5 Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Wed, 15 Mar 2017 14:28:23 +0100 Subject: [PATCH 13/13] docs/libnm: add some more documentation --- docs/libnm/libnm-docs.xml | 142 +++++++++++++++++++++++++++++++++----- 1 file changed, 124 insertions(+), 18 deletions(-) diff --git a/docs/libnm/libnm-docs.xml b/docs/libnm/libnm-docs.xml index 705bcfc18..b03efc33f 100644 --- a/docs/libnm/libnm-docs.xml +++ b/docs/libnm/libnm-docs.xml @@ -48,24 +48,130 @@ Overview - - libnm maps fairly closely to the actual D-Bus API that NetworkManager - provides, wrapping the remote D-Bus objects as native GObjects, - mapping D-Bus signals and properties to GObject signals and properties, - and providing helpful accessor and utility functions. However, unlike - the old libnm-util/libnm-glib API, the mapping to the D-Bus API is not - exact, and various inconveniences and historical anomolies of the D-Bus - API are papered over. - - - The following is a rough overview of the libnm object structure and - how to use the various parts of it: - - - - - - +
+ Introduction to libnm + + libnm is a client library for NetworkManager, the standard Linux network + management service. NetworkManager supports a wide variety of network + configuration scenarios, hardware devices and protocol families. Most of + the functionality is exposed on a + D-Bus API, + allowing other tools to use the functionality provided by NetworkManager. + + + libnm provides C language bindings for functionality provided by + NetworkManager, optionally useful from other language runtimes as well. + + + libnm maps fairly closely to the actual D-Bus API that NetworkManager + provides, wrapping the remote D-Bus objects as native GObjects, + mapping D-Bus signals and properties to GObject signals and properties, + and providing helpful accessor and utility functions. However, unlike + the old libnm-util/libnm-glib API, the mapping to the D-Bus API is not + exact, and various inconveniences and historical anomolies of the D-Bus + API are papered over. + + + The following is a rough overview of the libnm object structure and + how to use the various parts of it: + + + + + + +
+ +
+ Using libnm + + When to use libnm + + libnm is fairly simple to use from C. It's based on glib and GObject. + If your project uses these already you'll find integration libnm with your + project rather convenient. In fact, the nmcli tool shipped + with NetworkManager is based on libnm. + + + libnm should be also the way to go if your project does something non-trivial + with NetworkManager, such as manipulating the connection profiles. + That is, if you're writing a specialized networking control tool or a desktop + environment, libnm is probably the right choice. The popular desktop + environments in fact all use libnm directly or with nm-applet and + nm-connection-editor that are all based on libnm. + + + An alternative to use of libnm is the use of the + D-Bus API + directly. This gives you larger flexibility and reduces the overhead of linking + with the libnm library. This makes sense if your task is simple and you have a good + D-Bus library at your disposal. Activating a particular connection profile + from a Python script is a good example of a task that is perfectly simple + without using libnm. + + + + + How to use libnm + + You can use the libnm's C API directly. To do so, all libnm programs need to + include NetworkManager.h that provides necessary definitions. + The rest of the API is documented in the reference manual. + + +#include + +int +main (int argc, char *argv[]) +{ + NMClient *client; + + client = nm_client_new (NULL, NULL); + if (client) + g_print ("NetworkManager version: %s\n", nm_client_get_version (client)); +}]]> + + Use pkg-config for libnm to discover the necessary + compiler flags. + + $ cc $(pkg-config --libs --cflags libnm) -o hello-nm hello-nm.c + $ ./hello-nm + NetworkManager version: &version; + $ + + Utilize the PKG_CHECK_MODULES macro to integrate with an + autoconf-based build system. It's also recommended to use + NM_VERSION_MIN_REQUIRED and NM_VERSION_MAX_ALLOWED + macros to tell libnm headers which API version does your application need to work with. + If you use them, the compiler will warn you when you use functionality that is not + available in the versions you specified. + + = 1.8) +LIBNM_CFLAGS="$LIBNM_CFLAGS -DNM_VERSION_MIN_REQUIRED=NM_VERSION_1_8" +LIBNM_CFLAGS="$LIBNM_CFLAGS -DNM_VERSION_MAX_ALLOWED=NM_VERSION_1_8"]]> + + You can use libnm from other languages than C with the use of GObject introspection. + This includes Perl, Python, Javascript, Lua, Ruby and more. The example below shows what the + typical libnm use in Python would look like. + + + + There's NM-1.0 Python API Reference + maintained a third party that is generated from the introspection metadata. + + + In general, the C API documentation applies to the use GObject introspection + from other languages, with the calling convention respecting the language's + customs. Consult the source tree for + some examples. + + +