Message ID | 20200213175647.17628-20-peter.maydell@linaro.org |
---|---|
State | Superseded |
Headers | show
Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp828161ile; Thu, 13 Feb 2020 10:04:59 -0800 (PST) X-Google-Smtp-Source: APXvYqzUcYktuFXx1x9Rc7JNEdGdMLmIBmvCzfBTpJevOO9Xb9DNEynIhXzxnAKpYyg6rOhIq4SA X-Received: by 2002:a05:620a:1130:: with SMTP id p16mr17148780qkk.415.1581617099141; Thu, 13 Feb 2020 10:04:59 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581617099; cv=none; d=google.com; s=arc-20160816; b=iejkQQAPpP+/HEkwxUHpxp4fInDfwPsDw0Ep65SaR+2os0haRpga9HY/c94L0wxKg0 mWOWw23T+4O3CiyCy46FnpKUwBVXXOXZhSqFsrceET7qXrbFs9H0n1vhpXIITT18/bBd ZexaxHbhUcuKN7TSlteqlUgUWac+122TaKTQ7ZEeFBk9SrpFXCrKieZuqeJzObSEIE4t ZMFDOTFsa049Dj+QT3xrmmVac/URJETG8mZmDXvZLYMOg4rwHMqid/KXUtFYuOyWV3pa CN4PXms7Eh9dFZaRHIbsADtyx2l8EkSvGxt9gal0vnZXUcA7ego0XGWEKY4ohll/HheF i02A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=GQ9AbUdIDLadhdpxHBQc+3BZwH1J8H9FJUw/8rdNkPs=; b=FP5wyYRg7Aar2KnWielyhojB7+VkIAmiLrRABBFkbo6sqMX6A5SM/IRCk9AzFmDx4W sSqrKaWDJxPnoLb1f5LXF/BGUcVGoYJNfJx2Ltrza9rAgVKtRY5e1fPE6xzoemocuu13 PADaN7M3X9UxZ3KNFFOwQNnuskJWVT5EESz2NuuMOqcZec2spU6CAIJVAl9Ak8n3tcvB Pn2Nz/oJXO+eJCz5ifv53mRd2jb0aG32GGvNHXYQPLD3joF0x2sr9NRIbAU33vEh9o+o me0kMwC1tklzz168LZXQXPtt4gs39qk+K4K4N+TlkSYedBoBK/wfR4iwCdisGFW4+G/a O0QQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=jNwgKhRq; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: <qemu-devel-bounces+patch=linaro.org@nongnu.org> Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id h10si1519291qtp.161.2020.02.13.10.04.59 for <patch@linaro.org> (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 13 Feb 2020 10:04:59 -0800 (PST) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=jNwgKhRq; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1]:57276 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from <qemu-devel-bounces+patch=linaro.org@nongnu.org>) id 1j2IrC-00031h-Jw for patch@linaro.org; Thu, 13 Feb 2020 13:04:58 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:34264) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from <peter.maydell@linaro.org>) 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 <peter.maydell@linaro.org>) 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 <peter.maydell@linaro.org>) 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 <qemu-devel@nongnu.org>; Thu, 13 Feb 2020 09:57:18 -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-Received: by 2002:a5d:448c:: with SMTP id j12mr22423373wrq.125.1581616637009; Thu, 13 Feb 2020 09:57:17 -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) From: Peter Maydell <peter.maydell@linaro.org> 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: 8bit 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: <qemu-devel.nongnu.org> List-Unsubscribe: <https://lists.nongnu.org/mailman/options/qemu-devel>, <mailto:qemu-devel-request@nongnu.org?subject=unsubscribe> List-Archive: <https://lists.nongnu.org/archive/html/qemu-devel> List-Post: <mailto:qemu-devel@nongnu.org> List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help> List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/qemu-devel>, <mailto:qemu-devel-request@nongnu.org?subject=subscribe> Cc: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= <berrange@redhat.com>, Markus Armbruster <armbru@redhat.com>, Michael Roth <mdroth@linux.vnet.ibm.com>, Stefan Hajnoczi <stefanha@redhat.com>, John Snow <jsnow@redhat.com> Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" <qemu-devel-bounces+patch=linaro.org@nongnu.org> |
Series |
Convert QAPI doc comments to generate rST instead of texinfo
|
expand
|
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 -*- ## # = 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. -# +## + +## # = 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.
Our current QAPI doc-comment markup allows section headers (introduced with a leading '=' or '==') 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 <peter.maydell@linaro.org> --- qapi/qapi-schema.json | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) -- 2.20.1