From nobody Tue Feb 10 09:24:22 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1650481814; cv=none; d=zohomail.com; s=zohoarc; b=BuiKPNEsTUSfcajyg1UtWt8hbeCVSRY79D1CCksmebQGG2Hrf8DX2mZhpZ0tBPzxUHBUJDb/+FqAaJvJE+RTDfw5vY/S6CNSX1UsualYoMFcIygjR9OdtHHbSFiHLC4+HmDcLjMRYdjOp2qfzVb2Jx3uB4WTU6dMsdgrP8/FV/4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1650481814; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=8Ipdewnr77UTIXYDWa3LljF36lp9pqrzYYZfoGiB4oA=; b=ARDwtDDO4iun5bqqrb1uZK9LR5xP8EMX6tk5D+aYvea879QouvDIvsGJfo0xuqwl5WLeN/HBrYVfllOestycT2di4gIraZcaxOYjk7jBPw+uJb69h9Oo7rLqbic1vMGKLpByrph5fTr9ZVqrlhYVOTR4iUfhhkK+T2384KDj9SE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1650481814667932.9739839677218; Wed, 20 Apr 2022 12:10:14 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-438-Cl7tYX7IN_uRQQXHFpW7Ww-1; Wed, 20 Apr 2022 15:09:03 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 61A43805F70; Wed, 20 Apr 2022 19:08:53 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 4474140D0170; Wed, 20 Apr 2022 19:08:53 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id C59461940378; Wed, 20 Apr 2022 19:08:51 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx09.intmail.prod.int.rdu2.redhat.com [10.11.54.9]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id B21121940353 for ; Wed, 20 Apr 2022 19:08:49 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id A6B0F551E8A; Wed, 20 Apr 2022 19:08:49 +0000 (UTC) Received: from tapioca.home (unknown [10.40.193.11]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1CE39551E86 for ; Wed, 20 Apr 2022 19:08:48 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1650481813; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=8Ipdewnr77UTIXYDWa3LljF36lp9pqrzYYZfoGiB4oA=; b=DZ2tdOQGvKfCiu0tkIzInsQhm2nINE573COk5QgNha/SNxuW1yg4ixvunoFTMqoQE4VKcU FoY9J7hJ9p+cTT+HTIm6vfw6XkAS72kFREKQCne7JPcy24/gWKUE6/iklpmkxa28JUkmuc ItchTPVh74H22Paa/2WmE21oEvuSkRg= X-MC-Unique: Cl7tYX7IN_uRQQXHFpW7Ww-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Victor Toso To: libvir-list@redhat.com Subject: [PATCH v3 27/30] scripts: apibuild: parse 'Since' for functions Date: Wed, 20 Apr 2022 21:08:16 +0200 Message-Id: <20220420190819.3093205-28-victortoso@redhat.com> In-Reply-To: <20220420190819.3093205-1-victortoso@redhat.com> References: <20220420190819.3093205-1-victortoso@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.9 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1650481816754100001 Content-Type: text/plain; charset="utf-8" This patch adds 'version' parameter to generated XML API for functions and functypes. The 'version' metadata has been added with e0e0bf6628 by parsing .syms files. This commit does not override that but it will warn if there is not 'Since' metadata with new additions. There is not clear benefit for keeping both. For now, I've added a warning in case there is a mismatch between the version provided by .syms and docstring. Signed-off-by: Victor Toso --- scripts/apibuild.py | 126 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 113 insertions(+), 13 deletions(-) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index b77eea0624..ec10931151 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -111,6 +111,73 @@ ignored_functions =3D { "virErrorCopyNew": "private", } =20 +# The version in the .sym file might differnt from +# the real version that the function was introduced. +# This dict's value is the correct version, as it should +# be in the docstrings. +ignored_function_versions =3D { + 'virDomainSetBlockThreshold': '3.2.0', + 'virGetLastErrorMessage': '1.0.5.2', + 'virNodeDeviceCreate': '0.5.0', + 'virAdmClientClose': '1.3.5', + 'virAdmClientFree': '1.3.5', + 'virAdmClientGetID': '1.3.5', + 'virAdmClientGetInfo': '1.3.5', + 'virAdmClientGetTimestamp': '1.3.5', + 'virAdmClientGetTransport': '1.3.5', + 'virAdmConnectClose': '1.2.17', + 'virAdmConnectGetLibVersion': '1.3.1', + 'virAdmConnectGetURI': '1.3.1', + 'virAdmConnectIsAlive': '1.3.1', + 'virAdmConnectListServers': '1.3.2', + 'virAdmConnectLookupServer': '1.3.3', + 'virAdmConnectOpen': '1.2.17', + 'virAdmConnectRef': '1.2.17', + 'virAdmConnectRegisterCloseCallback': '1.3.1', + 'virAdmConnectUnregisterCloseCallback': '1.3.1', + 'virAdmGetVersion': '1.3.0', + 'virAdmServerFree': '1.3.2', + 'virAdmServerGetClientLimits': '1.3.5', + 'virAdmServerGetName': '1.3.2', + 'virAdmServerGetThreadPoolParameters': '1.3.4', + 'virAdmServerListClients': '1.3.5', + 'virAdmServerLookupClient': '1.3.5', + 'virAdmServerSetClientLimits': '1.3.5', + 'virAdmServerSetThreadPoolParameters': '1.3.4', + 'virAdmServerUpdateTlsFiles': '6.2.0', + 'virConnectFindStoragePoolSources': '0.4.6', + 'virConnectNumOfDefinedDomains': '0.1.6', + 'virConnectOpenAuth': '0.4.1', + 'virDomainBlockPeek': '0.4.4', + 'virDomainMemoryPeek': '0.4.4', + 'virNetworkUpdate': '1.0.0', + 'virConnectClose': '0.0.1', + 'virConnectGetType': '0.0.1', + 'virConnectGetVersion': '0.0.1', + 'virConnectListDomains': '0.0.1', + 'virConnectNumOfDomains': '0.0.1', + 'virConnectOpen': '0.0.1', + 'virConnectOpenReadOnly': '0.0.1', + 'virDomainCreateLinux': '0.0.1', + 'virDomainDestroy': '0.0.1', + 'virDomainFree': '0.0.1', + 'virDomainGetID': '0.0.1', + 'virDomainGetInfo': '0.0.1', + 'virDomainGetMaxMemory': '0.0.1', + 'virDomainGetName': '0.0.1', + 'virDomainGetOSType': '0.0.1', + 'virDomainGetXMLDesc': '0.0.1', + 'virDomainLookupByID': '0.0.1', + 'virDomainLookupByName': '0.0.1', + 'virDomainRestore': '0.0.2', + 'virDomainResume': '0.0.1', + 'virDomainSave': '0.0.2', + 'virDomainSetMaxMemory': '0.0.1', + 'virDomainShutdown': '0.0.1', + 'virDomainSuspend': '0.0.1', + 'virGetVersion': '0.0.1', +} + ignored_macros =3D { "_virSchedParameter": "backward compatibility macro for virTypedParame= ter", "_virBlkioParameter": "backward compatibility macro for virTypedParame= ter", @@ -2185,9 +2252,10 @@ class docBuilder: self.scanVersions() =20 # 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): + # For functions, since tags are on Return comments. + # Return the tags and the original comments, but without the tags. + def retrieve_comment_tags(self, name: str, comment: str, return_commen= t=3D"" + ) -> (str, str, str): since =3D "" if comment is not None: comment_match =3D re.search(r"\(?Since: v?(\d+\.\d+\.\d+\.?\d?= )\)?", @@ -2200,9 +2268,20 @@ class docBuilder: # Only the version since =3D comment_match.group(1) =20 + if since =3D=3D "" and return_comment is not None: + return_match =3D re.search(r"\(?Since: v?(\d+\.\d+\.\d+\.?\d?)= \)?", + return_comment) + if return_match: + # Remove Since tag from the comment + (start, end) =3D return_match.span() + return_comment =3D return_comment[:start] + return_comment= [end:] + return_comment =3D return_comment.strip() + # Only the version + since =3D return_match.group(1) + if since =3D=3D "": self.warning("Missing 'Since' tag for: " + name) - return (since, comment) + return (since, comment, return_comment) =20 def modulename_file(self, file): module =3D os.path.basename(file) @@ -2238,7 +2317,7 @@ class docBuilder: output.write(" type=3D'%s'" % info[2]) if info[1] is not None and info[1] !=3D '': # Search for 'Since' version tag - (since, comment) =3D self.retrieve_comment_tags(name, info= [1]) + (since, comment, _) =3D self.retrieve_comment_tags(name, i= nfo[1]) if len(since) > 0: output.write(" version=3D'%s'" % escape(since)) if len(comment) > 0: @@ -2268,7 +2347,7 @@ class docBuilder: else: output.write(" raw=3D'%s'" % escape(rawValue)) =20 - (since, comment) =3D self.retrieve_comment_tags(name, desc) + (since, comment, _) =3D self.retrieve_comment_tags(name, desc) if len(since) > 0: output.write(" version=3D'%s'" % escape(since)) output.write(">\n") @@ -2302,7 +2381,7 @@ class docBuilder: =20 def serialize_typedef(self, output, name): id =3D self.idx.typedefs[name] - (since, comment) =3D self.retrieve_comment_tags(name, id.extra) + (since, comment, _) =3D self.retrieve_comment_tags(name, id.extra) version_tag =3D len(since) > 0 and f" version=3D'{since}'" or "" if id.info[0:7] =3D=3D 'struct ': output.write(" ", id) =20 + (ret, params, desc) =3D id.info + return_comment =3D (ret is not None and ret[1] is not None) and re= t[1] or "" + (since, comment, return_comment) =3D self.retrieve_comment_tags(na= me, desc, return_comment) + # Simple way to avoid setting empty version + version_tag =3D len(since) > 0 and f" version=3D'{since}'" or "" + # NB: this is consumed by a regex in 'getAPIFilenames' in hvsuppor= t.pl if id.type =3D=3D "function": ver =3D self.versions[name] @@ -2363,9 +2448,10 @@ class docBuilder: name, self.modulename_file(id.header), self.modulename_file(id.module), self.versions[name])) else: - output.write(" \n" % ( + output.write(" \n" % ( name, self.modulename_file(id.header), - self.modulename_file(id.module))) + self.modulename_file(id.module), + version_tag)) # # Processing of conditionals modified by Bill 1/1/05 # @@ -2376,19 +2462,33 @@ class docBuilder: apstr =3D apstr + " && " apstr =3D apstr + cond output.write(" %s\n" % (apstr)) + try: - (ret, params, desc) =3D id.info - output.write(" \n" % (desc)) + # For functions, we get the since version from .syms files. + # This is an extra check to see that docstrings are correct + # and to avoid wrong versions in the .sym files too. + ver =3D name in self.versions and self.versions[name] or None + if len(since) > 0 and ver is not None and since !=3D ver: + if name in ignored_function_versions: + allowedver =3D ignored_function_versions[name] + if allowedver !=3D since: + self.warning(f"Function {name} has allowed version= {allowedver} but docstring says {since}") + else: + self.warning(f"Function {name} has symversion {ver} bu= t docstring says {since}") + + output.write(" \n" % (comment)) self.indexString(name, desc) + if ret[0] is not None: if ret[0] =3D=3D "void": output.write(" \n") - elif (ret[1] is None or ret[1] =3D=3D '') and name not in = ignored_functions: + elif (return_comment =3D=3D '') and name not in ignored_fu= nctions: self.error("Missing documentation for return of functi= on `%s'" % name) else: output.write(" \= n" % ( - ret[0], escape(ret[1]))) + ret[0], escape(return_comment))) self.indexString(name, ret[1]) + for param in params: if param[0] =3D=3D 'void': continue --=20 2.35.1