docs: merge branch 'th/generate-docs'

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

5 files changed, 418 insertions, 123 deletions

diff --git a/src/libnm-core-impl/nm-setting-ip4-config.c b/src/libnm-core-impl/nm-setting-ip4-config.c
index 46ad495092..d1aa72ae25 100644
--- a/src/libnm-core-impl/nm-setting-ip4-config.c
+++ b/src/libnm-core-impl/nm-setting-ip4-config.c
@@ -624,9 +624,9 @@ nm_setting_ip4_config_class_init(NMSettingIP4ConfigClass *klass)
     /* ---ifcfg-rh---
      * property: method
      * variable: BOOTPROTO
-     * format:   string
-     * values:   none, dhcp (bootp), static, ibft, autoip, shared
-     * default:  none
+     * format: string
+     * values: none, dhcp (bootp), static, ibft, autoip, shared
+     * default: none
      * description: Method used for IPv4 protocol configuration.
      * ---end---
      */
@@ -641,7 +641,7 @@ nm_setting_ip4_config_class_init(NMSettingIP4ConfigClass *klass)
     /* ---ifcfg-rh---
      * property: dns
      * variable: DNS1, DNS2, ...
-     * format:   string
+     * format: string
      * description: List of DNS servers. Even if NetworkManager supports many DNS
      *   servers, initscripts and resolver only care about the first three, usually.
      * example: DNS1=1.2.3.4 DNS2=10.0.0.254 DNS3=8.8.8.8
@@ -651,7 +651,7 @@ nm_setting_ip4_config_class_init(NMSettingIP4ConfigClass *klass)
     /* ---ifcfg-rh---
      * property: dns-search
      * variable: DOMAIN
-     * format:   string (space-separated domains)
+     * format: string (space-separated domains)
      * description: List of DNS search domains.
      * ---end---
      */
diff --git a/src/libnm-core-impl/nm-setting-ip6-config.c b/src/libnm-core-impl/nm-setting-ip6-config.c
index c6288b2694..01b6855ef2 100644
--- a/src/libnm-core-impl/nm-setting-ip6-config.c
+++ b/src/libnm-core-impl/nm-setting-ip6-config.c
@@ -563,7 +563,7 @@ nm_setting_ip6_config_class_init(NMSettingIP6ConfigClass *klass)
     /* ---ifcfg-rh---
      * property: method
      * variable: IPV6INIT, IPV6FORWARDING, IPV6_AUTOCONF, DHCPV6C, IPV6_DISABLED
-     * default:  IPV6INIT=yes; IPV6FORWARDING=no; IPV6_AUTOCONF=!IPV6FORWARDING, DHCPV6=no
+     * default: IPV6INIT=yes; IPV6FORWARDING=no; IPV6_AUTOCONF=!IPV6FORWARDING, DHCPV6=no
      * description: Method used for IPv6 protocol configuration.
      *   ignore ~ IPV6INIT=no; auto ~ IPV6_AUTOCONF=yes; dhcp ~ IPV6_AUTOCONF=no and DHCPV6C=yes;
      *   disabled ~ IPV6_DISABLED=yes
@@ -580,7 +580,7 @@ nm_setting_ip6_config_class_init(NMSettingIP6ConfigClass *klass)
     /* ---ifcfg-rh---
      * property: dns
      * variable: DNS1, DNS2, ...
-     * format:   string
+     * format: string
      * description: List of DNS servers. NetworkManager uses the variables both
      *   for IPv4 and IPv6.
      * ---end---
@@ -589,7 +589,7 @@ nm_setting_ip6_config_class_init(NMSettingIP6ConfigClass *klass)
     /* ---ifcfg-rh---
      * property: dns-search
      * variable: IPV6_DOMAIN(+)
-     * format:   string (space-separated domains)
+     * format: string (space-separated domains)
      * description: List of DNS search domains.
      * ---end---
      */
diff --git a/src/libnmc-setting/settings-docs.h.in b/src/libnmc-setting/settings-docs.h.in
index 4df96c7d31..cf87f38c15 100644
--- a/src/libnmc-setting/settings-docs.h.in
+++ b/src/libnmc-setting/settings-docs.h.in
@@ -24,7 +24,7 @@
 #define DESCRIBE_DOC_NM_SETTING_CONNECTION_STABLE_ID N_("This represents the identity of the connection used for various purposes. It allows to configure multiple profiles to share the identity. Also, the stable-id can contain placeholders that are substituted dynamically and deterministically depending on the context. The stable-id is used for generating IPv6 stable private addresses with ipv6.addr-gen-mode=stable-privacy. It is also used to seed the generated cloned MAC address for ethernet.cloned-mac-address=stable and wifi.cloned-mac-address=stable. It is also used as DHCP client identifier with ipv4.dhcp-client-id=stable and to derive the DHCP DUID with ipv6.dhcp-duid=stable-[llt,ll,uuid]. Note that depending on the context where it is used, other parameters are also seeded into the generation algorithm. For example, a per-host key is commonly also included, so that different systems end up generating different IDs. Or with ipv6.addr-gen-mode=stable-privacy, also the device's name is included, so that different interfaces yield different addresses. The per-host key is the identity of your machine and stored in /var/lib/NetworkManager/secret_key. See NetworkManager(8) manual about the secret-key and the host identity. The '$' character is treated special to perform dynamic substitutions at runtime. Currently, supported are \"${CONNECTION}\", \"${DEVICE}\", \"${MAC}\", \"${BOOT}\", \"${RANDOM}\". These effectively create unique IDs per-connection, per-device, per-boot, or every time. Note that \"${DEVICE}\" corresponds to the interface name of the device and \"${MAC}\" is the permanent MAC address of the device. Any unrecognized patterns following '$' are treated verbatim, however are reserved for future use. You are thus advised to avoid '$' or escape it as \"$$\". For example, set it to \"${CONNECTION}-${BOOT}-${DEVICE}\" to create a unique id for this connection that changes with every reboot and differs depending on the interface where the profile activates. If the value is unset, a global connection default is consulted. If the value is still unset, the default is similar to \"${CONNECTION}\" and uses a unique, fixed ID for the connection.")
 #define DESCRIBE_DOC_NM_SETTING_CONNECTION_TIMESTAMP N_("The time, in seconds since the Unix Epoch, that the connection was last _successfully_ fully activated. NetworkManager updates the connection timestamp periodically when the connection is active to ensure that an active connection has the latest timestamp. The property is only meant for reading (changes to this property will not be preserved).")
 #define DESCRIBE_DOC_NM_SETTING_CONNECTION_TYPE N_("Base type of the connection. For hardware-dependent connections, should contain the setting name of the hardware-type specific setting (ie, \"802-3-ethernet\" or \"802-11-wireless\" or \"bluetooth\", etc), and for non-hardware dependent connections like VPN or otherwise, should contain the setting name of that setting type (ie, \"vpn\" or \"bridge\", etc).")
-#define DESCRIBE_DOC_NM_SETTING_CONNECTION_UUID N_("The connection.uuid is the real identifier of a profile. It cannot change and it must be unique. It is therefore often best to refer to a profile by UUID, for example with `nmcli connection up uuid $UUID`.  The UUID cannot be changed, except in offline mode. In that case, the special values \"new\", \"generate\" and \"\" are allowed to generate a new random UUID.")
+#define DESCRIBE_DOC_NM_SETTING_CONNECTION_UUID N_("The connection.uuid is the real identifier of a profile. It cannot change and it must be unique. It is therefore often best to refer to a profile by UUID, for example with `nmcli connection up uuid $UUID`. The UUID cannot be changed, except in offline mode. In that case, the special values \"new\", \"generate\" and \"\" are allowed to generate a new random UUID.")
 #define DESCRIBE_DOC_NM_SETTING_CONNECTION_WAIT_ACTIVATION_DELAY N_("Time in milliseconds to wait for connection to be considered activated. The wait will start after the pre-up dispatcher event. The value 0 means no wait time. The default value is -1, which currently has the same meaning as no wait time.")
 #define DESCRIBE_DOC_NM_SETTING_CONNECTION_WAIT_DEVICE_TIMEOUT N_("Timeout in milliseconds to wait for device at startup. During boot, devices may take a while to be detected by the driver. This property will cause to delay NetworkManager-wait-online.service and nm-online to give the device a chance to appear. This works by waiting for the given timeout until a compatible device for the profile is available and managed. The value 0 means no wait time. The default value is -1, which currently has the same meaning as no wait time.")
 #define DESCRIBE_DOC_NM_SETTING_CONNECTION_ZONE N_("The trust level of a the connection.  Free form case-insensitive string (for example \"Home\", \"Work\", \"Public\").  NULL or unspecified zone means the connection will be placed in the default zone as defined by the firewall. When updating this property on a currently activated connection, the change takes effect immediately.")
diff --git a/src/nmcli/generate-docs-nm-settings-nmcli.xml.in b/src/nmcli/generate-docs-nm-settings-nmcli.xml.in
index c3cb530096..464d53b9ab 100644
--- a/src/nmcli/generate-docs-nm-settings-nmcli.xml.in
+++ b/src/nmcli/generate-docs-nm-settings-nmcli.xml.in
@@ -369,7 +369,7 @@
                   alias="con-name"
                   description="A human readable unique identifier for the connection, like "Work Wi-Fi" or "T-Mobile 3G"." />
         <property name="uuid"
-                  description="The connection.uuid is the real identifier of a profile. It cannot change and it must be unique. It is therefore often best to refer to a profile by UUID, for example with `nmcli connection up uuid $UUID`.  The UUID cannot be changed, except in offline mode. In that case, the special values &quot;new&quot;, &quot;generate&quot; and &quot;&quot; are allowed to generate a new random UUID." />
+                  description="The connection.uuid is the real identifier of a profile. It cannot change and it must be unique. It is therefore often best to refer to a profile by UUID, for example with `nmcli connection up uuid $UUID`. The UUID cannot be changed, except in offline mode. In that case, the special values &quot;new&quot;, &quot;generate&quot; and &quot;&quot; are allowed to generate a new random UUID." />
         <property name="stable-id"
                   description="This represents the identity of the connection used for various purposes. It allows to configure multiple profiles to share the identity. Also, the stable-id can contain placeholders that are substituted dynamically and deterministically depending on the context. The stable-id is used for generating IPv6 stable private addresses with ipv6.addr-gen-mode=stable-privacy. It is also used to seed the generated cloned MAC address for ethernet.cloned-mac-address=stable and wifi.cloned-mac-address=stable. It is also used as DHCP client identifier with ipv4.dhcp-client-id=stable and to derive the DHCP DUID with ipv6.dhcp-duid=stable-[llt,ll,uuid]. Note that depending on the context where it is used, other parameters are also seeded into the generation algorithm. For example, a per-host key is commonly also included, so that different systems end up generating different IDs. Or with ipv6.addr-gen-mode=stable-privacy, also the device&apos;s name is included, so that different interfaces yield different addresses. The per-host key is the identity of your machine and stored in /var/lib/NetworkManager/secret_key. See NetworkManager(8) manual about the secret-key and the host identity. The &apos;$&apos; character is treated special to perform dynamic substitutions at runtime. Currently, supported are &quot;${CONNECTION}&quot;, &quot;${DEVICE}&quot;, &quot;${MAC}&quot;, &quot;${BOOT}&quot;, &quot;${RANDOM}&quot;. These effectively create unique IDs per-connection, per-device, per-boot, or every time. Note that &quot;${DEVICE}&quot; corresponds to the interface name of the device and &quot;${MAC}&quot; is the permanent MAC address of the device. Any unrecognized patterns following &apos;$&apos; are treated verbatim, however are reserved for future use. You are thus advised to avoid &apos;$&apos; or escape it as &quot;$$&quot;. For example, set it to &quot;${CONNECTION}-${BOOT}-${DEVICE}&quot; to create a unique id for this connection that changes with every reboot and differs depending on the interface where the profile activates. If the value is unset, a global connection default is consulted. If the value is still unset, the default is similar to &quot;${CONNECTION}&quot; and uses a unique, fixed ID for the connection." />
         <property name="type"
diff --git a/tools/generate-docs-nm-property-infos.py b/tools/generate-docs-nm-property-infos.py
index 25aa272a69..dd40531e70 100755
--- a/tools/generate-docs-nm-property-infos.py
+++ b/tools/generate-docs-nm-property-infos.py
@@ -1,143 +1,438 @@
 #!/usr/bin/env python
 # SPDX-License-Identifier: LGPL-2.1-or-later
 
+import os
 import re
 import sys
+import collections
 import xml.etree.ElementTree as ET
 
 
-def get_setting_name(one_file):
-    setting_name = ""
-    assert re.match(r".*/libnm-core-impl/nm-setting-.*\.c$", one_file)
-    header_path = one_file.replace("libnm-core-impl", "libnm-core-public")
-    header_path = header_path.replace(".c", ".h")
-    try:
-        header_reader = open(header_path, "r")
-    except OSError:
-        print("Can not open header file: %s" % (header_path))
-        exit(1)
+class LineError(Exception):
+    def __init__(self, line_no, msg):
+        Exception.__init__(self, msg)
+        self.line_no = line_no
+
+
+_dbg_level = 0
+try:
+    _dbg_level = int(os.getenv("NM_DEBUG_GENERATE_DOCS", 0))
+except Exception:
+    pass
+
+
+def dbg(msg, level=1):
+    if level <= _dbg_level:
+        print(msg)
+
+
+def iter_unique(iterable, default=None):
+    found = False
+    for i in iterable:
+        assert not found
+        found = True
+        i0 = i
+    if found:
+        return i0
+    return default
+
 
-    line = header_reader.readline()
-    while line != "":
-        setting_name_found = re.search(r"NM_SETTING_.+SETTING_NAME\s+\"(\S+)\"", line)
-        if setting_name_found:
-            setting_name = setting_name_found.group(1)
-            break
-        line = header_reader.readline()
-    header_reader.close()
-    return setting_name
+def xnode_get_or_create(root_node, node_name, name):
+    # From root_node, get the node "<{node_name} name={name} .../>"
+    # or create one, if it doesn't exist.
+    node = iter_unique(
+        (node for node in root_node.findall(node_name) if node.attrib["name"] == name)
+    )
+    if node is None:
+        created = True
+        node = ET.SubElement(root_node, node_name, name=name)
+    else:
+        created = False
 
+    return node, created
+
+
+def get_setting_names(source_file):
+    m = re.match(r"^(.*)/libnm-core-impl/(nm-setting-[^/]*)\.c$", source_file)
+    assert m
+
+    path_prefix, file_base = (m.group(1), m.group(2))
+
+    if file_base == "nm-setting-ip-config":
+        # Special case ip-config, which is a base class.
+        return 0, ("ipv4", "ipv6")
+
+    header_file = "%s/libnm-core-public/%s.h" % (path_prefix, file_base)
 
-def scan_doc_comments(plugin, setting_node, file, start_tag, end_tag):
-    data = []
-    push_flag = 0
     try:
-        file_reader = open(file, "r")
+        f = open(header_file, "r")
     except OSError:
-        print("Can not open file: %s" % (file))
-        exit(1)
+        raise Exception(
+            'Can not open header file "%s" for "%s"' % (header_file, source_file)
+        )
+
+    with f:
+        for line in f:
+            m = re.search(r"^#define +NM_SETTING_.+SETTING_NAME\s+\"(\S+)\"$", line)
+            if m:
+                return 1, (m.group(1),)
+
+    raise Exception(
+        'Can\'t find setting name in header file "%s" for "%s"'
+        % (header_file, source_file)
+    )
 
-    line = file_reader.readline()
-    while line != "":
-        if start_tag in line:
-            push_flag = 1
-        elif end_tag in line and push_flag == 1:
-            push_flag = 0
-            parsed_data = process_data(data)
-            if parsed_data:
-                write_data(setting_node, parsed_data)
-            data = []
-        elif push_flag == 1:
-            data.append(line)
-        line = file_reader.readline()
-    file_reader.close()
-    return
-
-
-keywords = [
-    "property",
-    "variable",
-    "format",
-    "values",
-    "default",
-    "example",
-    "description",
-    "description-docbook",
-]
-kwd_first_line_re = re.compile(
-    r"^\s*\**\s+({}):\s+(.*?)\s*$".format("|".join(keywords))
+
+def get_file_infos(source_files):
+    # This function parses the source files and detects the
+    # used setting name. The returned sections are sorted by setting
+    # name.
+    #
+    # The file "nm-setting-ip-config.c" can contain information
+    # for "ipv4" and "ipv6" settings. Thus, to sort the files
+    # is a bit more involved.
+
+    # First, get a list of priority and setting-names that belong
+    # to the source file. Sort by priority,setting-names. It's
+    # important that "nm-setting-ip-config.c" gets parsed before
+    # "nm-setting-ip[46]-config.c".
+    file_infos = []
+    for source_file in source_files:
+        priority, setting_names = get_setting_names(source_file)
+        file_infos.append((priority, setting_names, source_file))
+    file_infos.sort()
+
+    d = {}
+    for priority, setting_names, source_file in file_infos:
+        for setting_name in setting_names:
+            l = d.get(setting_name, None)
+            if l is None:
+                l = list()
+                d[setting_name] = l
+            l.append(source_file)
+    for key in sorted(d.keys()):
+        for f in d[key]:
+            yield key, f
+
+
+KEYWORD_XML_TYPE_NESTED = "nested"
+KEYWORD_XML_TYPE_NODE = "node"
+KEYWORD_XML_TYPE_ATTR = "attr"
+
+keywords = collections.OrderedDict(
+    [
+        ("property", KEYWORD_XML_TYPE_ATTR),
+        ("variable", KEYWORD_XML_TYPE_ATTR),
+        ("format", KEYWORD_XML_TYPE_ATTR),
+        ("values", KEYWORD_XML_TYPE_ATTR),
+        ("default", KEYWORD_XML_TYPE_ATTR),
+        ("example", KEYWORD_XML_TYPE_ATTR),
+        ("description", KEYWORD_XML_TYPE_ATTR),
+        ("description-docbook", KEYWORD_XML_TYPE_NESTED),
+    ]
 )
-kwd_more_line_re = re.compile(r"^\s*\**\s+(.*?)\s*$")
 
 
-def process_data(data):
+def keywords_allowed(tag, keyword):
+    # certain keywords might not be valid for some tags.
+    # Currently, all of them are always valid.
+    assert keyword in keywords
+    return True
+
+
+def write_data(tag, setting_node, line_no, parsed_data):
+
+    for k in parsed_data.keys():
+        assert keywords_allowed(tag, k)
+        assert k in keywords
+
+    name = parsed_data["property"]
+    property_node, created = xnode_get_or_create(setting_node, "property", name)
+    if not created:
+        raise LineError(line_no, 'Duplicate property <property name="%s"...' % (name,))
+
+    for k, xmltype in keywords.items():
+        if k == "property":
+            continue
+
+        v = parsed_data.get(k, None)
+        if v is None:
+            continue
+
+        if xmltype == KEYWORD_XML_TYPE_NESTED:
+            # Set as XML nodes. The input data is XML itself.
+            des = ET.fromstring("<%s>%s</%s>" % (k, v, k))
+            property_node.append(des)
+        elif xmltype == KEYWORD_XML_TYPE_NODE:
+            node = ET.SubElement(property_node, k)
+            node.text = v
+        elif xmltype == KEYWORD_XML_TYPE_ATTR:
+            property_node.set(k, v)
+        else:
+            assert False
+
+
+kwd_first_line_re = re.compile(r"^ *\* ([-a-z0-9]+): (.*)$")
+kwd_more_line_re = re.compile(r"^ *\*( *)(.*?)\s*$")
+
+
+def parse_data(tag, line_no, lines):
+    assert lines
     parsed_data = {}
-    if not data:
-        return parsed_data
     keyword = ""
-    for line in data:
-        kwd_first_line_found = kwd_first_line_re.search(line)
-        if kwd_first_line_found:
-            keyword = kwd_first_line_found.group(1)
-            if keyword == "description-docbook":
-                value = kwd_first_line_found.group(2) + "\n"
+    first_line = True
+    indent = None
+    for line in lines:
+        assert "\n" not in line
+        line_no += 1
+        m = re.search(r"^     \*(| .*)$", line)
+        if not m:
+            raise LineError(line_no, 'Invalid formatted line "%s"' % (line,))
+        content = m.group(1)
+
+        m = re.search("^ ([-a-z0-9]+):(.*)$", content)
+        text_keyword_started = None
+        if m:
+            keyword = m.group(1)
+            if keyword in parsed_data:
+                raise LineError(line_no, 'Duplicated keyword "%s"' % (keyword,))
+            text = m.group(2)
+            text_keyword_started = text
+            if text:
+                if text[0] != " " or len(text) == 1:
+                    raise LineError(line_no, 'Invalid formatted line "%s"' % (line,))
+                text = text[1:]
+            if not keywords_allowed(tag, keyword):
+                raise LineError(line_no, 'Invalid key "%s" for %s' % (keyword, tag))
+            if parsed_data and keyword == "property":
+                raise LineError(line_no, 'The "property:" keywork must be first')
+            parsed_data[keyword] = text
+            new_keyword_stated = True
+            indent = None
+        else:
+            if content == "":
+                text = ""
+            elif content[0] == " " and len(content) > 1:
+                text = content[1:]
+                assert text
+                if indent is None:
+                    indent = re.search("^( *)", text).group(1)
+                if not text.startswith(indent):
+                    raise LineError(line_no, 'Unexpected indention in "%s"' % (line,))
+                text = text[len(indent) :]
             else:
-                value = kwd_first_line_found.group(2) + " "
-            parsed_data[keyword] = value
-            continue
-        kwd_more_line_found = kwd_more_line_re.search(line)
-        if kwd_more_line_found:
+                raise LineError(line_no, 'Unexpected line "%s"' % (line,))
             if not keyword:
-                print("Extra mess in a comment: %s" % (line))
-                exit(1)
-            if keyword == "description-docbook":
-                value = kwd_more_line_found.group(1) + "\n"
+                raise LineError(line_no, "Expected data in comment: %s" % (line))
+            if text and text[0] == "\\":
+                assert False
+                text = text[1:]
+            if separator == " " and text == "":
+                # No separator to add. This is a blank line
+                pass
             else:
-                value = kwd_more_line_found.group(1) + " "
-            parsed_data[keyword] += value
-    for keyword in keywords:
-        if keyword == "variable" and keyword not in parsed_data:
-            parsed_data[keyword] = parsed_data["property"]
-        elif keyword not in parsed_data:
-            parsed_data[keyword] = ""
-    for key in parsed_data.keys():
-        parsed_data[key] = parsed_data[key].rstrip()
+                parsed_data[keyword] = parsed_data[keyword] + separator + text
+
+        if keywords[keyword] == KEYWORD_XML_TYPE_NESTED:
+            # This is plain XML. They lines are joined by newlines.
+            separator = "\n"
+        elif text_keyword_started == "":
+            # If the previous line was just "tag:$", we don't need a separator
+            # the next time.
+            separator = ""
+        elif not text:
+            # A blank line is used to mark a line break, while otherwise
+            # lines are joined by space.
+            separator = "\n"
+        else:
+            separator = " "
+    if "property" not in parsed_data:
+        raise LineError(line_no, 'Missing "property:" tag')
+    for keyword in keywords.keys():
+        if not keywords_allowed(tag, keyword):
+            continue
+        if keyword not in parsed_data:
+            parsed_data[keyword] = None
     return parsed_data
 
 
-def write_data(setting_node, parsed_data):
-    property_node = ET.SubElement(setting_node, "property")
-    property_node.set("name", parsed_data["property"])
-    property_node.set("variable", parsed_data["variable"])
-    property_node.set("format", parsed_data["format"])
-    property_node.set("values", parsed_data["values"])
-    property_node.set("default", parsed_data["default"])
-    property_node.set("example", parsed_data["example"])
-    property_node.set("description", parsed_data["description"])
-    if parsed_data["description-docbook"]:
-        des = ET.fromstring(
-            "<description-docbook>"
-            + parsed_data["description-docbook"]
-            + "</description-docbook>"
-        )
-        property_node.append(des)
+def process_setting(tag, root_node, source_file, setting_name):
+
+    dbg(
+        "> > tag:%s, source_file:%s, setting_name:%s" % (tag, source_file, setting_name)
+    )
+
+    start_tag = "---" + tag + "---"
+    end_tag = "---end---"
+
+    setting_node, created = xnode_get_or_create(root_node, "setting", setting_name)
+
+    try:
+        f = open(source_file, "r")
+    except OSError:
+        raise Exception("Can not open file: %s" % (source_file))
+
+    lines = None
+    with f:
+        line_no = 0
+        just_had_end_tag = False
+        line_no_start = None
+        for line in f:
+            line_no += 1
+            if line and line[-1] == "\n":
+                line = line[:-1]
+            if just_had_end_tag:
+                # After the end-tag, we still expect one particular line. Be strict about
+                # this.
+                just_had_end_tag = False
+                if line != "     */":
+                    raise LineError(
+                        line_no,
+                        'Invalid end tag "%s". Expects literally "     */" after end-tag'
+                        % (line,),
+                    )
+            elif start_tag in line:
+                if line != "    /* " + start_tag:
+                    raise LineError(
+                        line_no,
+                        'Invalid start tag "%s". Expects literally "    /* %s"'
+                        % (line, start_tag),
+                    )
+                if lines is not None:
+                    raise LineError(
+                        line_no, 'Invalid start tag "%s", missing end-tag' % (line,)
+                    )
+                lines = []
+                line_no_start = line_no
+            elif end_tag in line and lines is not None:
+                if line != "     * " + end_tag:
+                    raise LineError(line_no, 'Invalid end tag: "%s"' % (line,))
+                parsed_data = parse_data(tag, line_no_start, lines)
+                if not parsed_data:
+                    raise Exception('invalid data: line %s, "%s"' % (line_no, lines))
+                dbg("> > > property: %s" % (parsed_data["property"],))
+                if _dbg_level > 1:
+                    for keyword in sorted(parsed_data.keys()):
+                        v = parsed_data[keyword]
+                        if v is not None:
+                            v = '"%s"' % (v,)
+                        dbg(
+                            "> > > > [%s] (%s) = %s" % (keyword, keywords[keyword], v),
+                            level=2,
+                        )
+                write_data(tag, setting_node, line_no_start, parsed_data)
+                lines = None
+            elif lines is not None:
+                lines.append(line)
+        if lines is not None or just_had_end_tag:
+            raise LineError(line_no_start, "Unterminated start tag")
+
+
+def process_settings_docs(tag, output, source_files):
+
+    dbg("> tag:%s, output:%s" % (tag, output))
+
+    root_node = ET.Element("nm-setting-docs")
+
+    for setting_name, source_file in get_file_infos(source_files):
+        try:
+            process_setting(tag, root_node, source_file, setting_name)
+        except LineError as e:
+            raise Exception(
+                "Error parsing %s, line %s (tag:%s, setting_name:%s): %s"
+                % (source_file, e.line_no, tag, setting_name, str(e))
+            )
+        except Exception as e:
+            raise Exception(
+                "Error parsing %s (tag:%s, setting_name:%s): %s"
+                % (source_file, tag, setting_name, str(e))
+            )
+
+    ET.ElementTree(root_node).write(output)
+
+
+def main():
+    if len(sys.argv) < 4:
+        print("Usage: %s [tag] [output-xml-file] [srcfiles...]" % (sys.argv[0]))
+        exit(1)
+
+    process_settings_docs(
+        tag=sys.argv[1], output=sys.argv[2], source_files=sys.argv[3:]
+    )
+
+
+if __name__ == "__main__":
+    main()
+
+
+###############################################################################
+# Tests
+###############################################################################
+
+
+def setup_module():
+    global pytest
+    import pytest
+
+
+def t_srcdir():
+    return os.path.abspath(os.path.dirname(__file__) + "/..")
+
+
+def t_setting_c(name):
+    return t_srcdir() + f"/src/libnm-core-impl/nm-setting-{name}.c"
+
+
+def test_file_location():
+    assert t_srcdir() + "/tools/generate-docs-nm-property-infos.py" == os.path.abspath(
+        __file__
+    )
+    assert os.path.isfile(t_srcdir() + "/src/libnm-core-impl/nm-setting-connection.c")
+
+    assert os.path.isfile(t_setting_c("ip-config"))
+
+
+def test_get_setting_names():
+    assert (1, ("connection",)) == get_setting_names(
+        t_srcdir() + "/src/libnm-core-impl/nm-setting-connection.c"
+    )
+    assert (1, ("ipv4",)) == get_setting_names(
+        t_srcdir() + "/src/libnm-core-impl/nm-setting-ip4-config.c"
+    )
+    assert (0, ("ipv4", "ipv6")) == get_setting_names(
+        t_srcdir() + "/src/libnm-core-impl/nm-setting-ip-config.c"
+    )
+
 
+def test_get_file_infos():
 
-if len(sys.argv) < 4:
-    print("Usage: %s [plugin] [output-xml-file] [srcfiles]" % (sys.argv[0]))
-    exit(1)
+    t = ["connection", "ip-config", "ip4-config", "proxy", "wired"]
 
-argv = list(sys.argv[1:])
-plugin, output, source_files = argv[0], argv[1], argv[2:]
-start_tag = "---" + plugin + "---"
-end_tag = "---end---"
-root_node = ET.Element("nm-setting-docs")
+    assert [
+        (
+            "802-3-ethernet",
+            t_setting_c("wired"),
+        ),
+        (
+            "connection",
+            t_setting_c("connection"),
+        ),
+        (
+            "ipv4",
+            t_setting_c("ip-config"),
+        ),
+        (
+            "ipv4",
+            t_setting_c("ip4-config"),
+        ),
+        (
+            "ipv6",
+            t_setting_c("ip-config"),
+        ),
+        ("proxy", t_setting_c("proxy")),
+    ] == list(get_file_infos([t_setting_c(x) for x in t]))
 
-for one_file in source_files:
-    setting_name = get_setting_name(one_file)
-    if setting_name:
-        setting_node = ET.SubElement(root_node, "setting", name=setting_name)
-        setting_node.text = "\n"
-        scan_doc_comments(plugin, setting_node, one_file, start_tag, end_tag)
 
-ET.ElementTree(root_node).write(output)
+def test_process_setting():
+    root_node = ET.Element("nm-setting-docs")
+    process_setting("nmcli", root_node, t_setting_c("connection"), "connection")