[PATCH v4 13/19] scripts: apibuild: parse 'Since' version for enums

Victor Toso victortoso at redhat.com
Fri Apr 22 19:23:38 UTC 2022


This patch adds 'version' parameter to the generated XML API for
enums.

It'll require, for new additions, to add a comment with the version
that the enum value was added.

Note that the Since tag is removed from the comment as there is a
proper field for it in the XML.

Signed-off-by: Victor Toso <victortoso at redhat.com>
---
 scripts/apibuild.py | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/scripts/apibuild.py b/scripts/apibuild.py
index bdd3077c48..19e897b1ba 100755
--- a/scripts/apibuild.py
+++ b/scripts/apibuild.py
@@ -2178,6 +2178,26 @@ class docBuilder:
         self.scanModules()
         self.scanVersions()
 
+    # Fetch tags from the comment. Only 'Since' supported at the moment.
+    # Return the tags and the original comment without the tags.
+    def retrieve_comment_tags(self, name: str, comment: str
+                              ) -> (str, str):
+        since = ""
+        if comment is not None:
+            comment_match = re.search(r"\(?Since: v?(\d+\.\d+\.\d+\.?\d?)\)?",
+                                      comment)
+            if comment_match:
+                # Remove Since tag from the comment
+                (start, end) = comment_match.span()
+                comment = comment[:start] + comment[end:]
+                comment = comment.strip()
+                # Only the version
+                since = comment_match.group(1)
+
+        if since == "":
+            self.warning("Missing 'Since' tag for: " + name)
+        return (since, comment)
+
     def modulename_file(self, file):
         module = os.path.basename(file)
         if module[-2:] == '.h':
@@ -2211,7 +2231,15 @@ class docBuilder:
             if info[2] is not None and info[2] != '':
                 output.write(" type='%s'" % info[2])
             if info[1] is not None and info[1] != '':
-                output.write(" info='%s'" % escape(info[1]))
+                # Search for 'Since' version tag
+                (since, comment) = self.retrieve_comment_tags(name, info[1])
+                if len(since) > 0:
+                    output.write(" version='%s'" % escape(since))
+                if len(comment) > 0:
+                    output.write(" info='%s'" % escape(comment))
+            else:
+                self.warning("Missing docstring for enum: " + name)
+
         output.write("/>\n")
 
     def serialize_macro(self, output, name):
-- 
2.35.1



More information about the libvir-list mailing list