From nobody Tue Apr 7 04:21:20 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1773685716; cv=none; d=zohomail.com; s=zohoarc; b=DskC+50Kc64qTmqkXcdEaMDBZwBkeVJrsRtdtJ5texzCWzrZiJKhVZi2qJfmqbbwBK0lclMZ2WMEsdI+CkznQk+5oiLjBnf3X3HeaJutLjyyWQPSjnwi5QwULwDVfq8wvI9mZqArAMb4EpdRIr7knyJ3zZ9io4tYL/pJtC5x56w= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1773685716; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=Ei4aQY7VT0T8rdfeAOBGN2KI2lTl3AJb+i0rhiwk9r0=; b=jDqS3b3NbThnwRIgRtd06pG7037aHgQpJKCeK6OsuSTRBQ62BQj0Tc2ziZbz8cIVS7toEGhYbNyyD6xwzUdfSE5lDU6T4hlPhw8nFFAkVj3zyaaYDBA7ViHXFZPiJzBxfo2tMbMvNW63894KPtyfXotHtcsJMLJAVjBlKExW5uE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1773685716262965.1253068106694; Mon, 16 Mar 2026 11:28:36 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1w2Cey-0002J6-AQ; Mon, 16 Mar 2026 14:27:24 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1w2Cel-0002DH-Ab for qemu-devel@nongnu.org; Mon, 16 Mar 2026 14:27:11 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1w2Ceg-0007xT-Cr for qemu-devel@nongnu.org; Mon, 16 Mar 2026 14:27:09 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-7-ffODOIcEOAuOXJb4i59YBA-1; Mon, 16 Mar 2026 14:27:01 -0400 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B05EC1800345; Mon, 16 Mar 2026 18:26:58 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.66.45]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 45CCF30001A2; Mon, 16 Mar 2026 18:26:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1773685624; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Ei4aQY7VT0T8rdfeAOBGN2KI2lTl3AJb+i0rhiwk9r0=; b=HOItc/8WRapYvj0epcDgvFbVDEWQ+8/V+dbUyE4WPu7d4pWQTVxWFavxn0ctfKhqZOgDtL guTD3DxyWaotNvfN7Z2knIJeJH/VOS6FJsFMH7tP3OK5BDnNNjDwAq5cKE2Prb/fSPfYEt D5djsOpM5HimmjAZd7GTi1UEvXngBZg= X-MC-Unique: ffODOIcEOAuOXJb4i59YBA-1 X-Mimecast-MFC-AGG-ID: ffODOIcEOAuOXJb4i59YBA_1773685619 From: John Snow To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , Lukas Straub , Richard Henderson , Zhao Liu , Jason Wang , Mauro Carvalho Chehab , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Peter Xu , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Fabiano Rosas , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?C=C3=A9dric=20Le=20Goater?= , qemu-block@nongnu.org, =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Peter Maydell , "Michael S. Tsirkin" , Stefan Berger , Alex Williamson , Marcel Apfelbaum , Kevin Wolf , John Snow , Michael Roth , Stefano Garzarella , Stefan Hajnoczi , Igor Mammedov , Jiri Pirko , Yanan Wang , Paolo Bonzini , Kashyap Chamarthy , Markus Armbruster , Hanna Reitz , Ani Sinha Subject: [PATCH 4/8] qapi: detect potentially semantically ambiguous intro paragraphs Date: Mon, 16 Mar 2026 14:26:03 -0400 Message-ID: <20260316182608.148628-5-jsnow@redhat.com> In-Reply-To: <20260316182608.148628-1-jsnow@redhat.com> References: <20260316182608.148628-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -3 X-Spam_score: -0.4 X-Spam_bar: / X-Spam_report: (-0.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.819, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.903, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1773685717665158500 Content-Type: text/plain; charset="utf-8" Cajole the QAPI Doc parser into yelping if a QAPI Doc Block contains more than one paragraph of plaintext and has no instances of Members, Errors, Returns, or Features that would naturally delineate an introduction from additional details such as notes, examples, and additional details. Signed-off-by: John Snow --- scripts/qapi/parser.py | 44 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index da47ee55bdd..9e8dfc67208 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -960,3 +960,47 @@ def check_args_section( =20 check_args_section(self.args, 'member') check_args_section(self.features, 'feature') + + # Ignore free-form documentation sections + if self.symbol is None: + return + + n_intro_para =3D 0 + has_intro =3D False + has_other =3D False + + for section in self.all_sections: + # Ignore Since: and TODO: sections + if section.kind in (QAPIDoc.Kind.SINCE, QAPIDoc.Kind.TODO): + continue + + # Ignore empty plaintext sections + if section.kind in (QAPIDoc.Kind.INTRO, QAPIDoc.Kind.DETAILS): + if not section.text: + continue + + if section.kind =3D=3D QAPIDoc.Kind.INTRO: + has_intro =3D True + n_intro_para =3D len(section.text.split("\n\n")) + elif not ( + section.kind =3D=3D QAPIDoc.Kind.MEMBER and not sectio= n.text + ): + # This section is something other than an Intro section; + # but we explicitly exclude stub entries for members + # (undocumented fields with no text) from consideration + # because they were auto-generated; they are not useful + # for identifying the case "There are multiple intro + # paragraphs and no other explicit source sections." + has_other =3D True + + # If an intro section is only a single paragraph, we are + # confident it is well and truly just an introduction. If we + # have a single, multi-paragraph intro section and *no other* + # explicit sections in source code, it is potentially a semantic + # goof-em-up where the intro and details sections have bled + # together. Warn about this case. + if has_intro and n_intro_para > 1 and not has_other: + print( + f"Warning: paragraphs for {self.symbol} are ambiguous " + "and could be either intro or details paragraphs." + ) --=20 2.53.0