Commit 36156b70 authored by Dan Winship's avatar Dan Winship Committed by Dan Winship

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.
parent 780d8bf2
......@@ -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
......
......@@ -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,
......
......@@ -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,
......
......@@ -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}"),
......
......@@ -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 - 128), 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 - 128), 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 'next-hop' entry, containing the next hop 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}"),
......
......@@ -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,
......
......@@ -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,
......
......@@ -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,
......
......@@ -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,
......
......@@ -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)
......
......@@ -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\"/>",
......
......@@ -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")
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment