From nobody Mon Feb 9 18:44:11 2026 Delivered-To: importer@patchew.org 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; Authentication-Results: mx.zohomail.com; dkim=fail; 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=fail(p=none dis=none) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1581617193441619.338233178724; Thu, 13 Feb 2020 10:06:33 -0800 (PST) Received: from localhost ([::1]:57308 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j2Isi-0005BV-5n for importer@patchew.org; Thu, 13 Feb 2020 13:06:32 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:34264) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j2Ijq-0000jK-9b for qemu-devel@nongnu.org; Thu, 13 Feb 2020 12:57:23 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j2Ijo-00030L-0D for qemu-devel@nongnu.org; Thu, 13 Feb 2020 12:57:22 -0500 Received: from mail-wr1-x42c.google.com ([2a00:1450:4864:20::42c]:37908) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j2Ijn-0002wC-Ne for qemu-devel@nongnu.org; Thu, 13 Feb 2020 12:57:19 -0500 Received: by mail-wr1-x42c.google.com with SMTP id y17so7808681wrh.5 for ; Thu, 13 Feb 2020 09:57:18 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id p26sm3692913wmc.24.2020.02.13.09.57.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 13 Feb 2020 09:57:16 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=GQ9AbUdIDLadhdpxHBQc+3BZwH1J8H9FJUw/8rdNkPs=; b=jNwgKhRqyCA3zE80oMKZTPOsJ37c/lWiGko1dSItkeShzU46B5ZDYvlKdKet0QZkXn YcwC8sKJvWWajE2aN6780XUrmVxcSwgEAGcAfGa6hW1R/G69hpVpA4AA9gYUM0lYEy+W qZMXzKxJgBEBFhm1PawPDaRv/RyxVffES+bf4qpwvC1Ieu8ik0PrY1GXf4sW3Oi4vRfs VG9q8uziKfS4VnlBIbrYt4jbhnHIfGwPSISt0uH9wTlgeQP70CmffknoRphKMfepqHbt uc9/4NtDCkpfxtsAwjSZfJZm1CSCxrW57EoTdsR2tvL5Vmee18kgzZNlVklPnM3xWr7A pxdQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=GQ9AbUdIDLadhdpxHBQc+3BZwH1J8H9FJUw/8rdNkPs=; b=qLIQ/Sv0ClRI12mHA/5a/TgiJ88G9CRxnimeSdfTRRQChMNHcpdp2gW6jkjF9ZHGyj 4UbQ4qs876I+r0GJfG39CWKjhzyxazdeiW+ekPLHJUwtNPqQPSd52Hbsojdoptb+s/Eo lE47wK8TEFR2+M9qCNW8v+Eis7wU46w3ur4hP0ve9ehLyhoDZ53XETdOplJzggROpWaX 41R6vsrmxm69GYsL3d8pbm/ALI5TT9dppQpiYJJetXwboX4XF+2bEEAbQ4zswDXll8MR HMjJD+PgzZ1C6AtF4H8avkTJ1k2OXzBzn6RJTz1bxyetyISKOjZZe1snynxE/hrttQlU 26VQ== X-Gm-Message-State: APjAAAUPRZqbrL9xsykhUsG4thQREbQFKGgiJ3N2C2d4vY4wVgl5ZSGj 5cpCH53nLGAU/Uug/l3mlW1YBPXHpbA= X-Google-Smtp-Source: APXvYqy5TOuk0xFAv2U8doIHdlfLceZJ6+rAT71ldzia1zDzHrhT96jydTH6js58pPujcTli0+il7g== X-Received: by 2002:a5d:448c:: with SMTP id j12mr22423373wrq.125.1581616637009; Thu, 13 Feb 2020 09:57:17 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v2 19/30] qapi/qapi-schema.json: Put headers in their own doc-comment blocks Date: Thu, 13 Feb 2020 17:56:36 +0000 Message-Id: <20200213175647.17628-20-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200213175647.17628-1-peter.maydell@linaro.org> References: <20200213175647.17628-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42c X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Our current QAPI doc-comment markup allows section headers (introduced with a leading '=3D' or '=3D=3D') anywhere in any documentation comment. This works for texinfo because the texi generator simply prints a texinfo heading directive at that point in the output stream. For rST generation, since we're assembling a tree of docutils nodes, this is awkward because a new section implies starting a new section node at the top level of the tree and generating text into there. New section headings in the middle of the documentation of a command or event would be pretty nonsensical, and in fact we only ever output new headings using 'freeform' doc comment blocks whose only content is the single line of the heading, with two exceptions, which are in the introductory freeform-doc-block at the top of qapi/qapi-schema.json. Split that doc-comment up so that the heading lines are in their own doc-comment. This will allow us to tighten the specification to insist that heading lines are always standalone, rather than requiring the rST document generator to look at every line in a doc comment block and handle headings in odd places. This change makes no difference to the generated texi. Signed-off-by: Peter Maydell --- qapi/qapi-schema.json | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 9751b11f8f1..f7ba60a5d0b 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -1,7 +1,9 @@ # -*- Mode: Python -*- ## # =3D Introduction -# +## + +## # This document describes all commands currently supported by QMP. # # Most of the time their usage is exactly the same as in the user Monitor,= this @@ -25,9 +27,13 @@ # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. -# +## + +## # =3D Stability Considerations -# +## + +## # The current QMP command set (described in this file) may be useful for a # number of use cases, however it's limited and several commands have bad # defined semantics, specially with regard to command completion. --=20 2.20.1