{"id":2221083,"url":"http://patchwork.ozlabs.org/api/1.1/covers/2221083/?format=json","web_url":"http://patchwork.ozlabs.org/project/qemu-devel/cover/20260408045531.3006678-1-jsnow@redhat.com/","project":{"id":14,"url":"http://patchwork.ozlabs.org/api/1.1/projects/14/?format=json","name":"QEMU Development","link_name":"qemu-devel","list_id":"qemu-devel.nongnu.org","list_email":"qemu-devel@nongnu.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20260408045531.3006678-1-jsnow@redhat.com>","date":"2026-04-08T04:55:21","name":"[v2,00/10] qapi: enforce section ordering","submitter":{"id":64343,"url":"http://patchwork.ozlabs.org/api/1.1/people/64343/?format=json","name":"John Snow","email":"jsnow@redhat.com"},"mbox":"http://patchwork.ozlabs.org/project/qemu-devel/cover/20260408045531.3006678-1-jsnow@redhat.com/mbox/","series":[{"id":499174,"url":"http://patchwork.ozlabs.org/api/1.1/series/499174/?format=json","web_url":"http://patchwork.ozlabs.org/project/qemu-devel/list/?series=499174","date":"2026-04-08T04:55:23","name":"qapi: enforce section ordering","version":2,"mbox":"http://patchwork.ozlabs.org/series/499174/mbox/"}],"comments":"http://patchwork.ozlabs.org/api/covers/2221083/comments/","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@legolas.ozlabs.org","Authentication-Results":["legolas.ozlabs.org;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256\n header.s=mimecast20190719 header.b=dHq06Brk;\n\tdkim-atps=neutral","legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org\n (client-ip=209.51.188.17; helo=lists.gnu.org;\n envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n receiver=patchwork.ozlabs.org)"],"Received":["from lists.gnu.org (unknown [209.51.188.17])\n\t(using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits))\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4frXC0634Jz1xy1\n\tfor ; Thu, 09 Apr 2026 04:48:28 +1000 (AEST)","from localhost ([::1] helo=lists1p.gnu.org)\n\tby lists.gnu.org with esmtp (Exim 4.90_1)\n\t(envelope-from )\n\tid 1wAXsr-0001FC-CV; Wed, 08 Apr 2026 14:44:13 -0400","from eggs.gnu.org ([2001:470:142:3::10])\n by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from ) id 1wAXsZ-0000os-Dx\n for qemu-devel@nongnu.org; Wed, 08 Apr 2026 14:43:55 -0400","from us-smtp-delivery-124.mimecast.com ([170.10.129.124])\n by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from ) id 1wAKxE-0005St-Bw\n for qemu-devel@nongnu.org; Wed, 08 Apr 2026 00:55:53 -0400","from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com\n (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by\n relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3,\n cipher=TLS_AES_256_GCM_SHA384) id us-mta-679-pSc05oKUOCmPtifITVCc2Q-1; Wed,\n 08 Apr 2026 00:55:46 -0400","from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com\n (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12])\n (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest\n SHA256)\n (No client certificate requested)\n by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS\n id D296C1800344; Wed, 8 Apr 2026 04:55:42 +0000 (UTC)","from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.88.7])\n by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP\n id 9CE6319560A6; Wed, 8 Apr 2026 04:55:33 +0000 (UTC)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com;\n s=mimecast20190719; t=1775624150;\n h=from:from:reply-to:subject:subject:date:date:message-id:message-id:\n to:to:cc:cc:mime-version:mime-version:content-type:content-type:\n content-transfer-encoding:content-transfer-encoding;\n bh=9hOLm5XknLXNzYps7PBO5aaJI5d/9nbRVwZIRPRfnUA=;\n b=dHq06BrknWsPFZeXIF8pxa1aJGK+014UDIqN11AHJqtjTW2MAHtMQrSA9HF9+dwNGRFoM8\n 6SrQydgB5BVP1lJkVWPQ5w4C+SJpXLZ3nfiFS/3jTUUYWkAGMEZp1NXSmtvXkN9rv5ufng\n AfqNP7QRWbpVRILoUByJ3NFrPaQ4jn4=","X-MC-Unique":"pSc05oKUOCmPtifITVCc2Q-1","X-Mimecast-MFC-AGG-ID":"pSc05oKUOCmPtifITVCc2Q_1775624143","From":"John Snow ","To":"qemu-devel@nongnu.org","Cc":"Kashyap Chamarthy ,\n Stefan Berger ,\n Mauro Carvalho Chehab ,\n Michael Roth ,\n =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= ,\n qemu-block@nongnu.org, Pierrick Bouvier ,\n Yanan Wang , Hanna Reitz ,\n Peter Xu , Igor Mammedov ,\n \"Michael S. Tsirkin\" , Kevin Wolf ,\n\t=?utf-8?q?Marc-Andr=C3=A9_Lureau?= ,\n Stefano Garzarella , =?utf-8?q?Daniel_P=2E_Berrang?=\n\t=?utf-8?q?=C3=A9?= , Lukas Straub ,\n Jason Wang , Alex Williamson ,\n Paolo Bonzini , Fabiano Rosas ,\n Zhao Liu ,\n Richard Henderson , =?utf-8?q?C=C3=A9dric_Le_?=\n\t=?utf-8?q?Goater?= , Stefan Hajnoczi ,\n Peter Maydell , Eric Blake ,\n\t=?utf-8?q?Alex_Benn=C3=A9e?= ,\n Kostiantyn Kostiuk , Jiri Pirko ,\n Markus Armbruster , John Snow ,\n Ani Sinha ,\n Marcel Apfelbaum ","Subject":"[PATCH v2 00/10] qapi: enforce section ordering","Date":"Wed, 8 Apr 2026 00:55:21 -0400","Message-ID":"<20260408045531.3006678-1-jsnow@redhat.com>","Content-Type":"text/plain; charset=\"utf-8\"","MIME-Version":"1.0","Content-Transfer-Encoding":"quoted-printable","X-Scanned-By":"MIMEDefang 3.0 on 10.30.177.12","Received-SPF":"pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com;\n helo=us-smtp-delivery-124.mimecast.com","X-Spam_score_int":"-25","X-Spam_score":"-2.6","X-Spam_bar":"--","X-Spam_report":"(-2.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.54,\n DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,\n RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001,\n RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001,\n SPF_HELO_PASS=-0.001,\n SPF_PASS=-0.001 autolearn=unavailable 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":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","Errors-To":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org","Sender":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org"},"content":"Hiya, this series is meant to accomplish mostly one thing: Enforce a\nstricter ordering of sections in QAPI documentation blocks.\n\nThe reason to do this is mostly for the sake of the inliner: if QAPI\ndocumentation blocks have some known, canonical order, it is easier to\nmerge two documentation blocks together for the purposes of showing all\narguments for commands/etc in a simple, flat list without needing to\nfollow hyperlink breadcrumbs.\n\nAnother reason to do this is to simplify where we insert autogenerated\ndocumentation. If the order is enforced, then inserting \"Not Documented\"\nstubs for members and generated \"Returns:\" statements can have a much\nsimpler algorithm that will always match how manually written\ndocumentation is presented, in the same order.\n\nThis is still pretty RFC quality, the tests have not been implemented\nand the implementation of changes in the parser are still pretty\nfuzzy. The main point of this series at this point in time is to review\nthe QAPI source changes and decide if the strategy employed in fixing\nthe section ordering is the direction we ultimately want to go in.\n\nV2:\n - Add quite a few FIXME stubs for tests\n - Much more carefully delineate QAPI source changes into ones required\n to prevent visible changes, and ones that explictly create visible\n changes\n - Various commit message / comment changes\n - Fix heuristic for griping about Intro/Details \"ambiguity\" to also\n ignore generated \"Returns\" sections, which was missing before and\n missed quite a few cases that did impact rendered output\n\nTo verify rendering changes (or lack thereof), I used this strategy:\n\n(1) For a reference output before a change, I ran a build:\n > V=1 DEBUG=1 make -j13;\n\n(2) Then I created some reference output for the intermediate rST\n debugging output files (fish syntax):\n > for i in *.ir; sed -E 's|\\.json:[0-9]{4}|.json:nnnn|g' $i > $i.ref; end\n\n(3) Then after applying a patch, to check for any differences, I re-ran\n the build as in (1) and then:\n > for i in *.ir; sed -E 's|\\.json:[0-9]{4}|.json:nnnn|g' $i > $i.new; end\n > for i in *.ir; meld $i.ref $i.new; end\n\nAn observation: Most of the time, the Intro section is only one\nparagraph anyway. We might be able to save on some explicit \"Details:\"\nsyntax if we just formalize the idea that the intro can only ever be at\nmost one paragraph. I don't know if we want to do that (Do we want to\nkeep the ability to run long in the \"intro\"?) - but it would cut down on\nquite a lot of markup that this series adds.\n\nJohn Snow (10):\n qapi: differentiate \"intro\" and \"details\" sections\n qapi: prohibit 'details' sections between tagged sections\n qapi: add \"Details:\" disambiguation marker\n qapi: add \"Details:\" markers where needed\n qapi: add \"Details:\" markers where potentially needed\n qapi: detect potentially semantically ambiguous intro paragraphs\n qapi: re-order QAPI doc block sections\n qapi: enforce doc block section ordering\n qapi: re-order 'since' sections to always be last\n qapi: enforce strict positioning for \"Since:\" section\n\n docs/devel/qapi-code-gen.rst | 33 +++-\n docs/interop/firmware.json | 4 +-\n docs/interop/vhost-user.json | 3 +-\n docs/sphinx/qapidoc.py | 2 +-\n qapi/accelerator.json | 12 +-\n qapi/acpi.json | 8 +-\n qapi/block-core.json | 183 ++++++++++---------\n qapi/block-export.json | 20 +-\n qapi/block.json | 48 ++---\n qapi/char.json | 36 ++--\n qapi/control.json | 14 +-\n qapi/dump.json | 16 +-\n qapi/machine-s390x.json | 16 +-\n qapi/machine.json | 144 ++++++++-------\n qapi/migration.json | 102 ++++++-----\n qapi/misc-arm.json | 6 +-\n qapi/misc-i386.json | 40 ++--\n qapi/misc.json | 68 ++++---\n qapi/net.json | 42 ++---\n qapi/pci.json | 4 +-\n qapi/qdev.json | 12 +-\n qapi/qom.json | 34 ++--\n qapi/replay.json | 16 +-\n qapi/rocker.json | 16 +-\n qapi/run-state.json | 66 ++++---\n qapi/tpm.json | 12 +-\n qapi/trace.json | 8 +-\n qapi/transaction.json | 4 +-\n qapi/ui.json | 76 ++++----\n qapi/vfio.json | 4 +-\n qapi/virtio.json | 46 ++---\n qapi/yank.json | 2 +-\n qga/qapi-schema.json | 2 +\n scripts/qapi/parser.py | 134 ++++++++++++--\n tests/qapi-schema/doc-good.json | 12 +-\n tests/qapi-schema/doc-good.out | 10 +-\n tests/qapi-schema/doc-good.txt | 18 +-\n tests/qapi-schema/doc-misplaced-details.err | 0\n tests/qapi-schema/doc-misplaced-details.json | 3 +\n tests/qapi-schema/doc-misplaced-details.out | 11 ++\n tests/qapi-schema/doc-missing-details.err | 0\n tests/qapi-schema/doc-missing-details.json | 3 +\n tests/qapi-schema/doc-missing-details.out | 11 ++\n tests/qapi-schema/meson.build | 2 +\n 44 files changed, 784 insertions(+), 519 deletions(-)\n create mode 100644 tests/qapi-schema/doc-misplaced-details.err\n create mode 100644 tests/qapi-schema/doc-misplaced-details.json\n create mode 100644 tests/qapi-schema/doc-misplaced-details.out\n create mode 100644 tests/qapi-schema/doc-missing-details.err\n create mode 100644 tests/qapi-schema/doc-missing-details.json\n create mode 100644 tests/qapi-schema/doc-missing-details.out"}