libnm: Override parts of nm-setting-docs.xml

Add "---dbus---" sections to the NMSetting property docs, in the same
style as the plugin docs, parse them out into a file
"nm-setting-docs-overrides.xml", and use them to override the GObject
property docs in nm-setting-docs.xml.

This lets us put more D-Bus-specific information in the setting docs,
without cluttering up the property docs, and it also lets us document
dbus-only properties.

12 files changed, 207 insertions, 15 deletions

diff --git a/.gitignore b/.gitignore
index 405ad78e7a..37adc4fa74 100644
--- a/.gitignore
+++ b/.gitignore
@@ -166,6 +166,7 @@ valgrind-*.log
 /libnm/nm-ifcfg-rh-docs.xml
 /libnm/nm-keyfile-docs.xml
 /libnm/nm-setting-docs.xml
+/libnm/nm-setting-docs-overrides.xml
 /libnm/tests/test-nm-client
 /libnm/tests/test-remote-settings-client
 /libnm/tests/test-secret-agent
diff --git a/libnm-core/nm-setting-bond.c b/libnm-core/nm-setting-bond.c
index 9fb7b356c6..bb05312539 100644
--- a/libnm-core/nm-setting-bond.c
+++ b/libnm-core/nm-setting-bond.c
@@ -745,6 +745,14 @@ nm_setting_bond_class_init (NMSettingBondClass *setting_class)
 	                                       _nm_utils_strdict_to_dbus,
 	                                       _nm_utils_strdict_from_dbus);
 
+	 /* ---dbus---
+	  * property: interface-name
+	  * format: string
+	  * description: Deprecated in favor of connection.interface-name, but can
+	  *   be used for backward-compatibility with older daemons, to set the
+	  *   bond's interface name.
+	  * ---end---
+	  */
 	 _nm_setting_class_add_dbus_only_property (parent_class, "interface-name",
 	                                           G_VARIANT_TYPE_STRING,
 	                                           _nm_setting_get_deprecated_virtual_interface_name,
diff --git a/libnm-core/nm-setting-bridge.c b/libnm-core/nm-setting-bridge.c
index acd3f62703..51c6ac5a03 100644
--- a/libnm-core/nm-setting-bridge.c
+++ b/libnm-core/nm-setting-bridge.c
@@ -525,6 +525,14 @@ nm_setting_bridge_class_init (NMSettingBridgeClass *setting_class)
 		                    NM_SETTING_PARAM_INFERRABLE |
 		                    G_PARAM_STATIC_STRINGS));
 
+	/* ---dbus---
+	 * property: interface-name
+	 * format: string
+	 * description: Deprecated in favor of connection.interface-name, but can
+	 *   be used for backward-compatibility with older daemons, to set the
+	 *   bridge's interface name.
+	 * ---end---
+	 */
 	_nm_setting_class_add_dbus_only_property (parent_class, "interface-name",
 	                                          G_VARIANT_TYPE_STRING,
 	                                          _nm_setting_get_deprecated_virtual_interface_name,
diff --git a/libnm-core/nm-setting-ip4-config.c b/libnm-core/nm-setting-ip4-config.c
index b71767e71c..4dbd6f0f4f 100644
--- a/libnm-core/nm-setting-ip4-config.c
+++ b/libnm-core/nm-setting-ip4-config.c
@@ -578,12 +578,35 @@ nm_setting_ip4_config_class_init (NMSettingIP4ConfigClass *ip4_class)
 		                      G_PARAM_STATIC_STRINGS));
 
 	/* IP4-specific property overrides */
+
+	/* ---dbus---
+	 * property: dns
+	 * format: array of uint32
+	 * description: Array of IP addresses of DNS servers (as network-byte-order
+	 *   integers)
+	 * ---end---
+	 */
 	_nm_setting_class_transform_property (setting_class,
 	                                      NM_SETTING_IP_CONFIG_DNS,
 	                                      G_VARIANT_TYPE ("au"),
 	                                      ip4_dns_to_dbus,
 	                                      ip4_dns_from_dbus);
 
+	/* ---dbus---
+	 * property: addresses
+	 * format: array of array of uint32
+	 * description: Deprecated in favor of the 'address-data' and 'gateway'
+	 *   properties, but this can be used for backward-compatibility with older
+	 *   daemons. Note that if you send this property the daemon will ignore
+	 *   'address-data' and 'gateway'.
+	 *
+	 *   Array of IPv4 address structures.  Each IPv4 address structure is
+	 *   composed of 3 32-bit values; the first being the IPv4 address (network
+	 *   byte order), the second the prefix (1 - 32), and last the IPv4 gateway
+	 *   (network byte order). The gateway may be left as 0 if no gateway exists
+	 *   for that subnet.
+	 * ---end---
+	 */
 	_nm_setting_class_override_property (setting_class,
 	                                     NM_SETTING_IP_CONFIG_ADDRESSES,
 	                                     G_VARIANT_TYPE ("aau"),
@@ -597,12 +620,38 @@ nm_setting_ip4_config_class_init (NMSettingIP4ConfigClass *ip4_class)
 	                                          ip4_address_labels_get,
 	                                          NULL);
 
+	/* ---dbus---
+	 * property: address-data
+	 * format: array of vardict
+	 * description: Array of IPv4 addresses. Each address dictionary contains at
+	 *   least 'address' and 'prefix' entries, containing the IP address as a
+	 *   string, and the prefix length as a uint32. Additional attributes may
+	 *   also exist on some addresses.
+	 * ---end---
+	 */
 	_nm_setting_class_add_dbus_only_property (setting_class,
 	                                          "address-data",
 	                                          G_VARIANT_TYPE ("aa{sv}"),
 	                                          ip4_address_data_get,
 	                                          ip4_address_data_set);
 
+	/* ---dbus---
+	 * property: routes
+	 * format: array of array of uint32
+	 * description: Deprecated in favor of the 'route-data' property, but this
+	 *   can be used for backward-compatibility with older daemons. Note that if
+	 *   you send this property the daemon will ignore 'route-data'.
+	 *
+	 *   Array of IPv4 route structures.  Each IPv4 route structure is composed
+	 *   of 4 32-bit values; the first being the destination IPv4 network or
+	 *   address (network byte order), the second the destination network or
+	 *   address prefix (1 - 32), the third being the next-hop (network byte
+	 *   order) if any, and the fourth being the route metric. If the metric is
+	 *   0, NM will choose an appropriate default metric for the device. (There
+	 *   is no way to explicitly specify an actual metric of 0 with this
+	 *   property.)
+	 * ---end---
+	 */
 	_nm_setting_class_override_property (setting_class,
 	                                     NM_SETTING_IP_CONFIG_ROUTES,
 	                                     G_VARIANT_TYPE ("aau"),
@@ -610,6 +659,19 @@ nm_setting_ip4_config_class_init (NMSettingIP4ConfigClass *ip4_class)
 	                                     ip4_routes_set,
 	                                     NULL);
 
+	/* ---dbus---
+	 * property: route-data
+	 * format: array of vardict
+	 * description: Array of IPv4 routes. Each route dictionary contains at
+	 *   least 'dest' and 'prefix' entries, containing the destination IP
+	 *   address as a string, and the prefix length as a uint32. Most routes
+	 *   will also have a 'gateway' entry, containing the gateway IP address as
+	 *   a string. If the route has a 'metric' entry (containing a uint32), that
+	 *   will be used as the metric for the route (otherwise NM will pick a
+	 *   default value appropriate to the device). Additional attributes may
+	 *   also exist on some routes.
+	 * ---end---
+	 */
 	_nm_setting_class_add_dbus_only_property (setting_class,
 	                                          "route-data",
 	                                          G_VARIANT_TYPE ("aa{sv}"),
diff --git a/libnm-core/nm-setting-ip6-config.c b/libnm-core/nm-setting-ip6-config.c
index a737dffec3..c970a93dac 100644
--- a/libnm-core/nm-setting-ip6-config.c
+++ b/libnm-core/nm-setting-ip6-config.c
@@ -498,12 +498,33 @@ nm_setting_ip6_config_class_init (NMSettingIP6ConfigClass *ip6_class)
 		                    G_PARAM_STATIC_STRINGS));
 
 	/* IP6-specific property overrides */
+
+	/* ---dbus---
+	 * property: dns
+	 * format: array of byte array
+	 * description: Array of IP addresses of DNS servers (in network byte order)
+	 * ---end---
+	 */
 	_nm_setting_class_transform_property (setting_class,
 	                                      NM_SETTING_IP_CONFIG_DNS,
 	                                      G_VARIANT_TYPE ("aay"),
 	                                      ip6_dns_to_dbus,
 	                                      ip6_dns_from_dbus);
 
+	/* ---dbus---
+	 * property: addresses
+	 * format: array of legacy IPv6 address struct (a(ayuay))
+	 * description: Deprecated in favor of the 'address-data' and 'gateway'
+	 *   properties, but this can be used for backward-compatibility with older
+	 *   daemons. Note that if you send this property the daemon will ignore
+	 *   'address-data' and 'gateway'.
+	 *
+	 *   Array of IPv6 address structures.  Each IPv6 address structure is
+	 *   composed of an IPv6 address, a prefix length (1 -32), and an IPv6
+	 *   gateway address. The gateway may be zeroed out if no gateway exists for
+	 *   that subnet.
+	 * ---end---
+	 */
 	_nm_setting_class_override_property (setting_class,
 	                                     NM_SETTING_IP_CONFIG_ADDRESSES,
 	                                     G_VARIANT_TYPE ("a(ayuay)"),
@@ -511,12 +532,35 @@ nm_setting_ip6_config_class_init (NMSettingIP6ConfigClass *ip6_class)
 	                                     ip6_addresses_set,
 	                                     NULL);
 
+	/* ---dbus---
+	 * property: address-data
+	 * format: array of vardict
+	 * description: Array of IPv6 addresses. Each address dictionary contains at
+	 *   least 'address' and 'prefix' entries, containing the IP address as a
+	 *   string, and the prefix length as a uint32. Additional attributes may
+	 *   also exist on some addresses.
+	 * ---end---
+	 */
 	_nm_setting_class_add_dbus_only_property (setting_class,
 	                                          "address-data",
 	                                          G_VARIANT_TYPE ("aa{sv}"),
 	                                          ip6_address_data_get,
 	                                          ip6_address_data_set);
 
+	/* ---dbus---
+	 * property: routes
+	 * format: array of legacy IPv6 route struct (a(ayuayu))
+	 * description: Deprecated in favor of the 'route-data' property, but this
+	 *   can be used for backward-compatibility with older daemons. Note that if
+	 *   you send this property the daemon will ignore 'route-data'.
+	 *
+	 *   Array of IPv6 route structures.  Each IPv6 route structure is
+	 *   composed of an IPv6 address, a prefix length (1 -32), an IPv6
+	 *   next hop address (which may be zeroed out if there is no next hop),
+	 *   and a metric. If the metric is 0, NM will choose an appropriate
+	 *   default metric for the device.
+	 * ---end---
+	 */
 	_nm_setting_class_override_property (setting_class,
 	                                     NM_SETTING_IP_CONFIG_ROUTES,
 	                                     G_VARIANT_TYPE ("a(ayuayu)"),
@@ -524,6 +568,19 @@ nm_setting_ip6_config_class_init (NMSettingIP6ConfigClass *ip6_class)
 	                                     ip6_routes_set,
 	                                     NULL);
 
+	/* ---dbus---
+	 * property: route-data
+	 * format: array of vardict
+	 * description: Array of IPv6 routes. Each route dictionary contains at
+	 *   least 'dest' and 'prefix' entries, containing the destination IP
+	 *   address as a string, and the prefix length as a uint32. Most routes
+	 *   will also have a 'gateway' entry, containing the gateway IP address as
+	 *   a string. If the route has a 'metric' entry (containing a uint32), that
+	 *   will be used as the metric for the route (otherwise NM will pick a
+	 *   default value appropriate to the device). Additional attributes may
+	 *   also exist on some routes.
+	 * ---end---
+	 */
 	_nm_setting_class_add_dbus_only_property (setting_class,
 	                                          "route-data",
 	                                          G_VARIANT_TYPE ("aa{sv}"),
diff --git a/libnm-core/nm-setting-serial.c b/libnm-core/nm-setting-serial.c
index 9a7b7f26c3..3fd780c838 100644
--- a/libnm-core/nm-setting-serial.c
+++ b/libnm-core/nm-setting-serial.c
@@ -301,6 +301,12 @@ nm_setting_serial_class_init (NMSettingSerialClass *setting_class)
 	 *   111 ('o') for odd, or 110 ('n') for none.
 	 * example: parity=n
 	 * ---end---
+	 * ---dbus---
+	 * property: parity
+	 * format: byte
+	 * description: The connection parity: 69 (ASCII 'E') for even parity,
+	 *   111 (ASCII 'o') for odd, 110 (ASCII 'n') for none.
+	 * ---end---
 	 */
 	g_object_class_install_property
 		(object_class, PROP_PARITY,
diff --git a/libnm-core/nm-setting-team.c b/libnm-core/nm-setting-team.c
index 3027810486..04b98243f1 100644
--- a/libnm-core/nm-setting-team.c
+++ b/libnm-core/nm-setting-team.c
@@ -171,6 +171,14 @@ nm_setting_team_class_init (NMSettingTeamClass *setting_class)
 		                      NM_SETTING_PARAM_INFERRABLE |
 		                      G_PARAM_STATIC_STRINGS));
 
+	/* ---dbus---
+	 * property: interface-name
+	 * format: string
+	 * description: Deprecated in favor of connection.interface-name, but can
+	 *   be used for backward-compatibility with older daemons, to set the
+	 *   team's interface name.
+	 * ---end---
+	 */
 	_nm_setting_class_add_dbus_only_property (parent_class, "interface-name",
 	                                          G_VARIANT_TYPE_STRING,
 	                                          _nm_setting_get_deprecated_virtual_interface_name,
diff --git a/libnm-core/nm-setting-vlan.c b/libnm-core/nm-setting-vlan.c
index 5a348211e9..7b7ad91cf6 100644
--- a/libnm-core/nm-setting-vlan.c
+++ b/libnm-core/nm-setting-vlan.c
@@ -806,6 +806,13 @@ nm_setting_vlan_class_init (NMSettingVlanClass *setting_class)
 	 *   but VLAN id from DEVICE takes precedence over VLAN_ID.
 	 * example: PHYSDEV=eth0, VLAN_ID=12; or DEVICE=eth0.12
 	 * ---end---
+	 * ---dbus---
+	 * property: interface-name
+	 * format: string
+	 * description: Deprecated in favor of connection.interface-name, but can
+	 *   be used for backward-compatibility with older daemons, to set the
+	 *   vlan's interface name.
+	 * ---end---
 	 */
 	_nm_setting_class_add_dbus_only_property (parent_class, "interface-name",
 	                                          G_VARIANT_TYPE_STRING,
diff --git a/libnm-core/nm-setting-wireless.c b/libnm-core/nm-setting-wireless.c
index 696ade3082..64640f2697 100644
--- a/libnm-core/nm-setting-wireless.c
+++ b/libnm-core/nm-setting-wireless.c
@@ -1317,6 +1317,13 @@ nm_setting_wireless_class_init (NMSettingWirelessClass *setting_class)
 	 * variable: (none)
 	 * description: This property is deprecated and not handled by ifcfg-rh-plugin.
 	 * ---end---
+	 * ---dbus---
+	 * property: security
+	 * description: This property is deprecated, but can be set to the value
+	 *   '802-11-wireless-security' when a wireless security setting is also
+	 *   present in the connection dictionary, for compatibility with very old
+	 *   NetworkManager daemons.
+	 * ---end---
 	 */
 	_nm_setting_class_add_dbus_only_property (parent_class, "security",
 	                                          G_VARIANT_TYPE_STRING,
diff --git a/libnm/Makefile.am b/libnm/Makefile.am
index e00aa87392..75c3f18acd 100644
--- a/libnm/Makefile.am
+++ b/libnm/Makefile.am
@@ -184,15 +184,23 @@ check-local:
 
 if BUILD_SETTING_DOCS
 
-noinst_DATA = nm-setting-docs.xml nm-keyfile-docs.xml nm-ifcfg-rh-docs.xml
+noinst_DATA = \
+	nm-setting-docs-overrides.xml \
+	nm-setting-docs.xml \
+	nm-keyfile-docs.xml \
+	nm-ifcfg-rh-docs.xml
 
 docs_sources = $(filter-out nm-core-enum-types.c,$(libnm_core_sources))
 
-nm-setting-docs.xml: generate-setting-docs.py $(docs_sources) | NM-1.0.gir NM-1.0.typelib libnm.la
+nm-setting-docs-overrides.xml: generate-plugin-docs.pl $(docs_sources)
+	$(srcdir)/generate-plugin-docs.pl dbus $(top_srcdir)/libnm-core $@
+
+nm-setting-docs.xml: generate-setting-docs.py $(docs_sources) nm-setting-docs-overrides.xml | NM-1.0.gir NM-1.0.typelib libnm.la
 	export GI_TYPELIB_PATH=$(abs_builddir)$${GI_TYPELIB_PATH:+:$$GI_TYPELIB_PATH}; \
 	export LD_LIBRARY_PATH=$(abs_builddir)/.libs$${LD_LIBRARY_PATH:+:$$LD_LIBRARY_PATH}; \
 	$(srcdir)/generate-setting-docs.py \
 		--gir $(builddir)/NM-1.0.gir \
+		--overrides $(builddir)/nm-setting-docs-overrides.xml \
 		--output $@
 
 nm-keyfile-docs.xml: generate-plugin-docs.pl $(docs_sources)
diff --git a/libnm/generate-plugin-docs.pl b/libnm/generate-plugin-docs.pl
index 53edb48cd2..ea97a2224f 100755
--- a/libnm/generate-plugin-docs.pl
+++ b/libnm/generate-plugin-docs.pl
@@ -55,7 +55,6 @@ my @data;
 my $fo;
 
 (scalar @ARGV == 3) or die "Usage: $0 <plugin> <srcdir> <output-xml-file>\n";
-($ARGV[0] eq "keyfile" || $ARGV[0] eq "ifcfg-rh") or die "Allowed <plugin> values: keyfile, ifcfg-rh\n";
 my ($plugin, $srcdir, $output) = @ARGV;
 my $start_tag = "---$plugin---\\s*\$";
 my $end_tag   = '---end---';
@@ -155,6 +154,7 @@ sub process_data {
   my $exam   = $yaml_data->{example}     // "";
   my $desc   = $yaml_data->{description} // "";
 
+  chomp($name, $var, $format, $values, $def, $exam, $desc);
   escape_xml_chars($name, $var, $format, $values, $def, $exam, $desc);
   my $foo = sprintf("<property name=\"%s\" variable=\"%s\" format=\"%s\" values=\"%s\" ".
                     "default=\"%s\" example=\"%s\" description=\"%s\"/>",
diff --git a/libnm/generate-setting-docs.py b/libnm/generate-setting-docs.py
index 1d7aaea665..a47794715a 100755
--- a/libnm/generate-setting-docs.py
+++ b/libnm/generate-setting-docs.py
@@ -152,6 +152,7 @@ def usage():
 
 parser = argparse.ArgumentParser()
 parser.add_argument('-g', '--gir', metavar='FILE', help='NM-1.0.gir file')
+parser.add_argument('-x', '--overrides', metavar='FILE', help='documentation overrides file')
 parser.add_argument('-o', '--output', metavar='FILE', help='output file')
 
 args = parser.parse_args()
@@ -172,6 +173,8 @@ settings = sorted(settings, key=lambda setting: setting.attrib['{%s}symbol-prefi
 
 init_constants(girxml, settings)
 
+overrides = ET.parse(args.overrides).getroot()
+
 outfile.write("""<?xml version=\"1.0\"?>
 <!DOCTYPE nm-setting-docs [
 <!ENTITY quot "&#34;">
@@ -188,24 +191,41 @@ for settingxml in settings:
 
     outfile.write("  <setting name=\"%s\">\n" % setting.props.name)
 
-    properties = sorted(GObject.list_properties(setting), key=lambda prop: prop.name)
-    for pspec in properties:
-        propxml = settingxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
-        if propxml is None:
-            propxml = basexml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
-        if propxml is None:
-            propxml = ipxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
+    setting_properties = { prop.name: prop for prop in GObject.list_properties(setting) }
+    setting_overrides = { override.attrib['name']: override for override in overrides.findall('./setting[@name="%s"]/property' % setting.props.name) }
+
+    properties = sorted(set.union(set(setting_properties.keys()), set(setting_overrides.keys())))
+
+    for prop in properties:
+        value_type = None
+        value_desc = None
+        default_value = None
 
-        value_type = get_prop_type(setting, pspec, propxml)
-        value_desc = get_docs(setting, pspec, propxml)
-        default_value = get_default_value(setting, pspec, propxml)
+        if prop in setting_properties:
+            pspec = setting_properties[prop]
+            propxml = settingxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
+            if propxml is None:
+                propxml = basexml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
+            if propxml is None:
+                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)
+            default_value = get_default_value(setting, pspec, propxml)
+
+        if prop in setting_overrides:
+            override = setting_overrides[prop]
+            if override.attrib['format'] != '':
+                value_type = override.attrib['format']
+            if override.attrib['description'] != '':
+                value_desc = override.attrib['description']
 
         if default_value is not None:
             outfile.write("    <property name=\"%s\" type=\"%s\" default=\"%s\" description=\"%s\" />\n" %
-                          (pspec.name, value_type, escape(default_value), escape(value_desc)))
+                          (prop, value_type, escape(default_value), escape(value_desc)))
         else:
             outfile.write("    <property name=\"%s\" type=\"%s\" description=\"%s\" />\n" %
-                          (pspec.name, value_type, escape(value_desc)))
+                          (prop, value_type, escape(value_desc)))
 
     outfile.write("  </setting>\n")