From patchwork Thu Feb 6 17:30:27 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183121 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1842527ile; Thu, 6 Feb 2020 09:42:49 -0800 (PST) X-Google-Smtp-Source: APXvYqxLBcIT3ah6+tUANPfUL4fs3ONgoAsIgFZu5CoYcBTmC46o2Eh+uUF9rlgslWwUVt5EFRzY X-Received: by 2002:a05:620a:56b:: with SMTP id p11mr3621249qkp.32.1581010968894; Thu, 06 Feb 2020 09:42:48 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010968; cv=none; d=google.com; s=arc-20160816; b=hQRC2Y4Vst+SADmvKEKvrn3dSjGfSLCk187kM2axM5iemxW3wWkoomVR/7Xsf5RqVH mpV2A4dgWZrqA+3+vCq9dZXrmxA/uWbtji6qIccDo4vYG+kWXIfsQ2xAv50zl3bEChqP ZmetdpV1TpolDfIP8SIq7VAblgGxbLamadVyZbmM2roAaTIkOTNYWzxDpupRVyvZ6pav UMRSAD2rihf055qOJSijoSc0//TMqx+iXvXgmQEXOVjfQPHkl1Zy11EvGNsF9mZPWqCY E2fNEZwx0Ym3yumUeD3g6d1u8Z1MfjQrzILIIdw9CM5ga/DhembBMptxp2sp+iV+IFfF ouag== 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=iafVdg3waVWv4MsmBKz7Z/kOldmt8SzM/gApHhbQWYM=; b=M/JdYq4VBgjzm+nX88sBpZ5TKRaXK2PC6IFWJafbiF859gCXD06V7pPxGbHnIYPS8F HYxY3v+4/zkvYnxTaIceWtsCT7kZq/ozKU8s3zyobnAw6DM9C36MZLL1H0WNOdHjaJB8 dtXcXtswjPiBCzc3Zj2dr80pvOj7ujWLBiEbkmvF08nOLcLanVBN2Un7WExbjQMbh/U6 2egmCWbievZSz+amBwv+ReZGSkOfLgQybtIFqfR8EsDkvLDkbkNYlNHmGZAwLeRx4et6 A8BGkBr/nuWpk0UP77cU9tFZEB7HU5cQmwJJ9zk5JLasqED/YXx3or/BMgMwSOikZ7LI WdZw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=MbCnjgXj; 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: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id g14si74072qti.136.2020.02.06.09.42.48 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:42:48 -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=MbCnjgXj; 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]:43598 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlAu-0008Rs-Bx for patch@linaro.org; Thu, 06 Feb 2020 12:42:48 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43555) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl03-0006mi-DU for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:37 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzy-0006Qg-To for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:33 -0500 Received: from mail-wr1-x42e.google.com ([2a00:1450:4864:20::42e]:35628) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzv-0006B1-1X for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:29 -0500 Received: by mail-wr1-x42e.google.com with SMTP id w12so8229642wrt.2 for ; Thu, 06 Feb 2020 09:31:25 -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=iafVdg3waVWv4MsmBKz7Z/kOldmt8SzM/gApHhbQWYM=; b=MbCnjgXj0lRGhKJMlw47Kdi598FD6EoG88uBxplHMe7iyr0lAsfEo3bcBNgF3sgYCr PrhAOqpWfDg0AObWJKLoNtrbH8EnmpnhtiT2NIWmp+8KQRg7vOb0Ff2w5zM2SY2x+AW7 Yl0PNE4/0AGFnpqY9cQLsYduBdIFYEOM69ibJ0ihWuYfVCZVKzU0CpoT/UGR2T389AZL J9QrF5hsU8mSvTekiytTNRrWhERxwnGwWjwASSrYIbLEJLkjWeC3FUKhsnBhx6HRTUs5 Vqcdheq2A/eNWWWwexJ/RaVkr/fV+wjMkrXyeowbJrxiHPY7MHDok/cm9/kq/Js5Mqq7 JJVA== 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=iafVdg3waVWv4MsmBKz7Z/kOldmt8SzM/gApHhbQWYM=; b=axk6kzwB4T+HrVg1pn3t8bG1gP9lK7NZXcBMAp6HJtGXS/6pv/M0hHM/OJnMBn6r50 bku4rUQ2ggvpcPl2ZpFI/e7fIzadRzuHEpMR0KgDl+YrsXD5keydy1f1y4xo5J6q+sP/ z4xCkXrZ4BjvC5jzQPia5OeiVZ8JC+Bb+qsvb4WTm5LsPQ7JDgBLYo+fh1jtgP+cGlrq 9VIXGzMx+Q7VmMefeuvFTWfN35k0J2nU3a9E/zLo2AEjk7jmz8yHTDNskRHUlVCftYm8 hBFqaVShApuBLiIIUy53SxVk7r0imksRcsQhxyscyIZYWjllk8g84yCJ7AZm7Fz6//fD liwQ== X-Gm-Message-State: APjAAAUyr9IWCrizaw5zA79oFYAD45Tw5rgMCi9AiKH7gn4MbQo55ubk SXuA+f9Da1nrFQDG/rQ7Vdz4jKF1xyo= X-Received: by 2002:a5d:608f:: with SMTP id w15mr4875905wrt.20.1581010284467; Thu, 06 Feb 2020 09:31:24 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id w15sm5204214wrs.80.2020.02.06.09.31.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:23 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 16/29] qapi/{block, misc, tmp}.json: Use explicit bulleted lists Date: Thu, 6 Feb 2020 17:30:27 +0000 Message-Id: <20200206173040.17337-17-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200206173040.17337-1-peter.maydell@linaro.org> References: <20200206173040.17337-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42e 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_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" A JSON block comment like this: Returns: nothing on success If @node is not a valid block device, DeviceNotFound If @name is not found, GenericError with an explanation renders in the HTML and manpage like this: Returns: nothing on success If node is not a valid block device, DeviceNotFound If name is not found, GenericError with an explanation because whitespace is not significant. Use an actual bulleted list, so that the formatting is correct. This commit gathers up the remaining json files which had places needing this fix. Signed-off-by: Peter Maydell --- qapi/block.json | 33 ++++++++++++++------------------- qapi/misc.json | 36 ++++++++++++++++-------------------- qapi/tpm.json | 4 ++-- 3 files changed, 32 insertions(+), 41 deletions(-) -- 2.20.1 Reviewed-by: Philippe Mathieu-Daudé diff --git a/qapi/block.json b/qapi/block.json index 905297bab2e..e509cc53506 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -115,15 +115,12 @@ # # For the arguments, see the documentation of BlockdevSnapshotInternal. # -# Returns: nothing on success -# -# If @device is not a valid block device, GenericError -# -# If any snapshot matching @name exists, or @name is empty, -# GenericError -# -# If the format of the image used does not support it, -# BlockFormatFeatureNotSupported +# Returns: - nothing on success +# - If @device is not a valid block device, GenericError +# - If any snapshot matching @name exists, or @name is empty, +# GenericError +# - If the format of the image used does not support it, +# BlockFormatFeatureNotSupported # # Since: 1.7 # @@ -154,12 +151,12 @@ # # @name: optional the snapshot's name to be deleted # -# Returns: SnapshotInfo on success -# If @device is not a valid block device, GenericError -# If snapshot not found, GenericError -# If the format of the image used does not support it, -# BlockFormatFeatureNotSupported -# If @id and @name are both not specified, GenericError +# Returns: - SnapshotInfo on success +# - If @device is not a valid block device, GenericError +# - If snapshot not found, GenericError +# - If the format of the image used does not support it, +# BlockFormatFeatureNotSupported +# - If @id and @name are both not specified, GenericError # # Since: 1.7 # @@ -197,10 +194,8 @@ # @force: If true, eject regardless of whether the drive is locked. # If not specified, the default value is false. # -# Returns: Nothing on success -# -# If @device is not a valid block device, DeviceNotFound -# +# Returns: - Nothing on success +# - If @device is not a valid block device, DeviceNotFound # Notes: Ejecting a device with no media results in success # # Since: 0.14.0 diff --git a/qapi/misc.json b/qapi/misc.json index 626a342b008..06c80b58a24 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -418,12 +418,10 @@ # # Return information about the balloon device. # -# Returns: @BalloonInfo on success -# -# If the balloon driver is enabled but not functional because the KVM -# kernel module cannot support it, KvmMissingCap -# -# If no balloon device is present, DeviceNotActive +# Returns: - @BalloonInfo on success +# - If the balloon driver is enabled but not functional because the KVM +# kernel module cannot support it, KvmMissingCap +# - If no balloon device is present, DeviceNotActive # # Since: 0.14.0 # @@ -480,8 +478,8 @@ # # @bar: the index of the Base Address Register for this region # -# @type: 'io' if the region is a PIO region -# 'memory' if the region is a MMIO region +# @type: - 'io' if the region is a PIO region +# - 'memory' if the region is a MMIO region # # @size: memory size # @@ -992,10 +990,10 @@ # # @value: the target size of the balloon in bytes # -# Returns: Nothing on success -# If the balloon driver is enabled but not functional because the KVM +# Returns: - Nothing on success +# - If the balloon driver is enabled but not functional because the KVM # kernel module cannot support it, KvmMissingCap -# If no balloon device is present, DeviceNotActive +# - If no balloon device is present, DeviceNotActive # # Notes: This command just issues a request to the guest. When it returns, # the balloon size may not have changed. A guest can change the balloon @@ -1074,8 +1072,8 @@ # If @device is 'vnc' and @target is 'password', this is the new VNC # password to set. See change-vnc-password for additional notes. # -# Returns: Nothing on success. -# If @device is not a valid block device, DeviceNotFound +# Returns: - Nothing on success. +# - If @device is not a valid block device, DeviceNotFound # # Notes: This interface is deprecated, and it is strongly recommended that you # avoid using it. For changing block devices, use @@ -1225,11 +1223,9 @@ # # @opaque: A free-form string that can be used to describe the fd. # -# Returns: @AddfdInfo on success -# -# If file descriptor was not received, FdNotSupplied -# -# If @fdset-id is a negative value, InvalidParameterValue +# Returns: - @AddfdInfo on success +# - If file descriptor was not received, FdNotSupplied +# - If @fdset-id is a negative value, InvalidParameterValue # # Notes: The list of fd sets is shared by all monitor connections. # @@ -1257,8 +1253,8 @@ # # @fd: The file descriptor that is to be removed. # -# Returns: Nothing on success -# If @fdset-id or @fd is not found, FdNotFound +# Returns: - Nothing on success +# - If @fdset-id or @fd is not found, FdNotFound # # Since: 1.2.0 # diff --git a/qapi/tpm.json b/qapi/tpm.json index 63878aa0f47..dc1f0817399 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -96,8 +96,8 @@ # # A union referencing different TPM backend types' configuration options # -# @type: 'passthrough' The configuration options for the TPM passthrough type -# 'emulator' The configuration options for TPM emulator backend type +# @type: - 'passthrough' The configuration options for the TPM passthrough type +# - 'emulator' The configuration options for TPM emulator backend type # # Since: 1.5 ##