From patchwork Thu Feb 6 17:30:12 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183104 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1833149ile; Thu, 6 Feb 2020 09:33:48 -0800 (PST) X-Google-Smtp-Source: APXvYqxlNRmKCqV/mDpZQuL/VbOTBNqeTmsX468ixgqvA4LkJ1V6bl1iRRX7y3Gt43mPfsW+kLbE X-Received: by 2002:ac8:4a02:: with SMTP id x2mr3708458qtq.388.1581010427914; Thu, 06 Feb 2020 09:33:47 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010427; cv=none; d=google.com; s=arc-20160816; b=dI6w+IRa+1TlMMLXHUCADHWhPyoskrHqNPB9sOk/PKkkfpcQBl5mx9SzGOsmKEGbhv E9JD8832ftE7WJ3zsX4JL8f7oO6vzPOtBU/+rKZ7AqaIrlEa1HRm0Kdg4hqNCBKiXsF9 GY32DSBBffo87O25crGqWVloe+BJDSZT1/Aw55c7FIMn/0nyfjua5nz04ksRLG+ohgTV Fo2+ReRDg0mjL7hU4rkuktkIPqI3s2s4M/shb0a9c0xVGyPspC73eRUcD1Drin6Wu38N yhNLnSVZlaO2bjU+LjSTjx2maC3eoXDeh3/jl7EFt3+tYVZ2IStYU1bdN2LHXnwMyQ22 OP3A== 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=d/ebdcIXrQTTW84jcoWGJHeNN6IFG3QgpgPcIBhY1sQ=; b=Nuy4ANmrYMynHFEsLlXalZv5n0TLzlNQ28BS5q15F7oMoGDUTrwBMDrun3NM+w7L5d GWGzLvbKOI7wvNMfPvKLtI67Kc5d378xu8r5ku6gpz6PWf4iG5Oj7/UFy1I9JGJ8e4by 9WbCS8D+3FoLA2L15b37zAvMeT+4TtgwOKfAGCDlvTdW5hHoH+Ybs25AzMgSi5D/ULoB d9HXWcs91y+SsdIl4z6G78o8o24GBsoU/obhVpt7KYlViO1voDHAAfLxFBMLey4cUDOc 3TT0EZZeDsW3pdfqZ5mqOPKm91p1JfTZ57Bd1Vn4Jz7O6DcbuLWRyI3N+bEoWJJv30fJ w9fw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="RA/hdVYl"; 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 c20si57094qte.198.2020.02.06.09.33.47 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:33:47 -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="RA/hdVYl"; 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]:43354 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl2B-00020Z-C1 for patch@linaro.org; Thu, 06 Feb 2020 12:33:47 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43289) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzL-00063e-B8 for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:52 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzJ-0003q1-Ie for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:51 -0500 Received: from mail-wm1-x334.google.com ([2a00:1450:4864:20::334]:37716) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzH-0003gK-Rm for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:49 -0500 Received: by mail-wm1-x334.google.com with SMTP id f129so995344wmf.2 for ; Thu, 06 Feb 2020 09:30:47 -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=d/ebdcIXrQTTW84jcoWGJHeNN6IFG3QgpgPcIBhY1sQ=; b=RA/hdVYl4Su/0rRFK3HyMmx1LC0aj65RCNgTuDAF6SMpz7xCWipxVcbpKgz+tJv2cM fjvK+9gTF7gOml7BUw6oyBNc1/WPGgUYM1DIzIKw2fy2BU+cPkOCLrjQXz2fVz3ZVREk WZTfEZOZ3ZAAGJbO3QGS7PdVGOTq0k8fmbKzbZ9hTD2NuwIND/osnmFFX74+8k4tQ0rL 9R/BVnS9mkCdlhjn5Xtk5zmoJhWcuOA+Gbw3HFIv/opRoC11tDFx3z5oAn2dNdsYbHL5 gyzWFlV9XZPgbKqLmxfb72QqK3aYDXhhAAUvoAZqhe3rI//WNK7hYx7Y0AvBGSPggVrb Y8/g== 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=d/ebdcIXrQTTW84jcoWGJHeNN6IFG3QgpgPcIBhY1sQ=; b=MmQxp4gjESyFgWVW0USYbo29dLH3oT72kqDo+/kc04RSldALb9dLPa+bX33nKu8GM+ pFUT7Dkp2B45YURYQ+XYo7hVH1GzbNnyIG9oO1pITHZM1fEA1z3XYATHZwEEx6oCe2SO GJ85Wu2ba7jLrA25iEUjzeVz8WW1wkCwJWH0yWqE1yH/IcCJlvQSBTbs+V5OKFxm+BcP ASWab/3479w3OntOJh7U0+iCMCPmT/n0uaSP/PYpvHxhYOkp4eEfaRAVla7zq8Tc/BO2 LYSCzyDv7te95ofuMwIJilBJQaROWc0R+hoQNtUuY37cCBjBIuCFe4h8M7gbb9v1DgpV a2eQ== X-Gm-Message-State: APjAAAWZ+BD23bB7vsP1AjLG82inNGoOhCxdVYRyT7i2OWj1d4gbMWk3 TkOwqvTe77pfbOQ+HIpE/aAuJ7L7Rl4= X-Received: by 2002:a1c:e246:: with SMTP id z67mr6050971wmg.52.1581010246179; Thu, 06 Feb 2020 09:30:46 -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.30.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:30:44 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 01/29] configure: Allow user to specify sphinx-build binary Date: Thu, 6 Feb 2020 17:30:12 +0000 Message-Id: <20200206173040.17337-2-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::334 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" Currently we insist on using 'sphinx-build' from the $PATH; allow the user to specify the binary to use. This will be more useful as we become pickier about the capabilities we require (eg needing a Python 3 sphinx-build). Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée Reviewed-by: Wainer dos Santos Moschetta --- configure | 10 +++++++++- Makefile | 2 +- 2 files changed, 10 insertions(+), 2 deletions(-) -- 2.20.1 diff --git a/configure b/configure index 115dc38085f..0aceb8e50db 100755 --- a/configure +++ b/configure @@ -584,6 +584,7 @@ query_pkg_config() { } pkg_config=query_pkg_config sdl2_config="${SDL2_CONFIG-${cross_prefix}sdl2-config}" +sphinx_build=sphinx-build # If the user hasn't specified ARFLAGS, default to 'rv', just as make does. ARFLAGS="${ARFLAGS-rv}" @@ -975,6 +976,8 @@ for opt do ;; --python=*) python="$optarg" ;; + --sphinx-build=*) sphinx_build="$optarg" + ;; --gcov=*) gcov_tool="$optarg" ;; --smbd=*) smbd="$optarg" @@ -1677,6 +1680,7 @@ Advanced options (experts only): --make=MAKE use specified make [$make] --install=INSTALL use specified install [$install] --python=PYTHON use specified python [$python] + --sphinx-build=SPHINX use specified sphinx-build [$sphinx_build] --smbd=SMBD use specified smbd [$smbd] --with-git=GIT use specified git [$git] --static enable static build [$static] @@ -4799,7 +4803,7 @@ has_sphinx_build() { # sphinx-build doesn't exist at all or if it is too old. mkdir -p "$TMPDIR1/sphinx" touch "$TMPDIR1/sphinx/index.rst" - sphinx-build -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1 + $sphinx_build -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1 } # Check if tools are available to build documentation. @@ -6474,6 +6478,9 @@ echo "QEMU_LDFLAGS $QEMU_LDFLAGS" echo "make $make" echo "install $install" echo "python $python ($python_version)" +if test "$docs" != "no"; then + echo "sphinx-build $sphinx_build" +fi echo "slirp support $slirp $(echo_version $slirp $slirp_version)" if test "$slirp" != "no" ; then echo "smbd $smbd" @@ -7503,6 +7510,7 @@ echo "INSTALL_DATA=$install -c -m 0644" >> $config_host_mak echo "INSTALL_PROG=$install -c -m 0755" >> $config_host_mak echo "INSTALL_LIB=$install -c -m 0644" >> $config_host_mak echo "PYTHON=$python" >> $config_host_mak +echo "SPHINX_BUILD=$sphinx_build" >> $config_host_mak echo "CC=$cc" >> $config_host_mak if $iasl -h > /dev/null 2>&1; then echo "IASL=$iasl" >> $config_host_mak diff --git a/Makefile b/Makefile index 461d40bea6c..20bf0cc771a 100644 --- a/Makefile +++ b/Makefile @@ -1024,7 +1024,7 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \ # Note the use of different doctree for each (manual, builder) tuple; # this works around Sphinx not handling parallel invocation on # a single doctree: https://github.com/sphinx-doc/sphinx/issues/2946 -build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") +build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" $(SPHINX_BUILD) $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") # We assume all RST files in the manual's directory are used in it manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \ $(wildcard $(SRC_PATH)/docs/$1/*.rst.inc) \ From patchwork Thu Feb 6 17:30:13 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183107 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1836390ile; Thu, 6 Feb 2020 09:36:56 -0800 (PST) X-Google-Smtp-Source: APXvYqxMmJh1Cg/SntmO7nITvHep/lY3Wc3gZSHY0FfAgDR9N0AgD420p4HFYIep4NH21cRcL3uE X-Received: by 2002:a05:620a:1327:: with SMTP id p7mr3558454qkj.148.1581010616431; Thu, 06 Feb 2020 09:36:56 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010616; cv=none; d=google.com; s=arc-20160816; b=vSDh9r+Do7pa4X7dshPdNm/51T4EkXHRuuhEubC20u34as2cLHSreL4Tc4QrzLTJMI 3xKFTKIm84r7vWCsxagwwgaOzZx1ozGguYgh93+64rzF3i4q7O9zHFdHMfC1ER1n8coI cV7HsAIsW8tPg9UM+6T+rVlOs3UWFkwd6CeLi2V7xYyAPxJWyD9gsGCQQiKjxzCdYENW C81bI7XKvU/H8FDMOlxcsc6v7wUZRv1t+WnWHjcY35ZhsDRX5BY8h+2QhB21F63kXxHU hb5ZPY1OkcRqRB0QozS1W3Fqp7qPjQmeW3VLxVe+kKwzyBiPf0wDDvHfdAMrLhBOe8Eu cYlw== 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=wr8RlgOBQK+lZKQOUvmEh0ytBymCGpyT+5O+C4ZgoYs=; b=mJgKktLRlMvOvCW6WrggXfuS8YPQT2Z4bEFXzUbJuBSQGEzGt9JFcSuKZgyuqDZPNm Pp6K8XrZMbHLAQiqQeQ9/BtBck4BPhI5H8TIAzalXjhPH1/CjFmPP43vhhXShlrcuUbj YHWUFvEYzqkq2XfSWQZLjnaSCJkNibQDjaOTkuVDL2y8qCwZ3Q4fw0PWgyFm6dhFpoyF NGZXpPvVSXyCPLwwvYkQwphch9VFcfryCH3II0OMygYFuyaO3Z5vgk2qnq5Ilx1vbTZ3 tUN6C9b48r/p3Ss6lnng4A/ScTMAbPg61tnTdIEu+yG/6CiBSQVIVHfw44+IsZSAvWO4 XHyg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=AG4Qohl8; 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 c188si1715921qkb.310.2020.02.06.09.36.56 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:36:56 -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=AG4Qohl8; 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]:43416 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl5D-00062J-S8 for patch@linaro.org; Thu, 06 Feb 2020 12:36:55 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43304) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzM-00065H-GX for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:53 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzL-0003xh-BL for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:52 -0500 Received: from mail-wr1-x431.google.com ([2a00:1450:4864:20::431]:44167) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzK-0003pP-59 for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:51 -0500 Received: by mail-wr1-x431.google.com with SMTP id m16so8168129wrx.11 for ; Thu, 06 Feb 2020 09:30:50 -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=wr8RlgOBQK+lZKQOUvmEh0ytBymCGpyT+5O+C4ZgoYs=; b=AG4Qohl8KXnqXx7w1lxhvhIjoRFVP/mtyDy7TzyzuWUDFyG2HCwN6JaSrmqnz+Hg9s RJMYJAVXA6gsl09QeiusAZg61TmewYZch16aHJ5d+OeiAG4/RN2YWYP2c0FGHr0IwKGL olObe3TeoBPytc53Phc7RcuVY6XpFDguTNHPdYQYg+pFimpLvKsbQfZVfQbYybbZRqaL ADpXQmy+AITpQz4sir9M5oI6iiAdABTl6g7qZWxmCVidBeNjc5KOeD80Iw7lnAQOo85k +6b+S0qjcQCGtEVsb4sZmwzOmvh6twdwcaU5k8Df2pHPqGo06nnKJhoBfZwk8kLOIDaa Hyig== 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=wr8RlgOBQK+lZKQOUvmEh0ytBymCGpyT+5O+C4ZgoYs=; b=UHk2/hMKmlwkiYRaZ5xgXuU3BdXhQTouU1qx6HIyDB4abEbCoHGu5987ovGlLnvOsA a6AWfFubN23Io9XON+R3jTIcJfOLnfI6Ttf0tfR3kprvQRaywLabWE6EapzxmuqdvpN+ +RcLKbGkzEhjAqGIvI9dawVphMFm99A/N4Hk/G/EqWwqA1Gw8FPalXuegi2UHW35VUHD XsbfUUcWP51TohGkAtT7h7cWUQzGGaPUoELdbP2u4R1YAXJHS3VVIaiFEAzAuOD2Wh8M 9q7FXcLpygFgEosWjOrXhWASSOcEp8O8fFmESF0E7ZtzT4Pr3/3QVVEsnPsT1zt4cnAK Uuiw== X-Gm-Message-State: APjAAAXyidt/UGY9p6OpqgZ25/Yi6qjbNfBZ0U8CnodhNotwSM7HVa8O nABaxA95Jesj6cKgqgwKVtckueiISao= X-Received: by 2002:a05:6000:1201:: with SMTP id e1mr4969750wrx.386.1581010248573; Thu, 06 Feb 2020 09:30:48 -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.30.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:30:47 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 02/29] configure: Check that sphinx-build is using Python 3 Date: Thu, 6 Feb 2020 17:30:13 +0000 Message-Id: <20200206173040.17337-3-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::431 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" Currently configure's has_sphinx_build() check simply runs a dummy sphinx-build and either passes or fails. This means that "no sphinx-build at all" and "sphinx-build exists but is too old" are both reported the same way. Further, we want to assume that all the Python we write is running with at least Python 3.5; configure checks that for our scripts, but Sphinx extensions run with whatever Python version sphinx-build itself is using. Add a check to our conf.py which makes sphinx-build fail if it would be running our extensions with an old Python, and handle this in configure so we can report failure helpfully to the user. This will mean that configure --enable-docs will fail like this if the sphinx-build provided is not suitable: Warning: sphinx-build exists but it is either too old or uses too old a Python version ERROR: User requested feature docs configure was not able to find it. Install texinfo, Perl/perl-podlators and a Python 3 version of python-sphinx (As usual, the default is to simply not build the docs, as we would if sphinx-build wasn't present at all.) Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée Reviewed-by: Wainer dos Santos Moschetta --- configure | 12 ++++++++++-- docs/conf.py | 10 ++++++++++ 2 files changed, 20 insertions(+), 2 deletions(-) -- 2.20.1 diff --git a/configure b/configure index 0aceb8e50db..2c5cad13edd 100755 --- a/configure +++ b/configure @@ -4808,11 +4808,19 @@ has_sphinx_build() { # Check if tools are available to build documentation. if test "$docs" != "no" ; then - if has makeinfo && has pod2man && has_sphinx_build; then + if has_sphinx_build; then + sphinx_ok=yes + else + sphinx_ok=no + fi + if has makeinfo && has pod2man && test "$sphinx_ok" = "yes"; then docs=yes else if test "$docs" = "yes" ; then - feature_not_found "docs" "Install texinfo, Perl/perl-podlators and python-sphinx" + if has $sphinx_build && test "$sphinx_ok" != "yes"; then + echo "Warning: $sphinx_build exists but it is either too old or uses too old a Python version" >&2 + fi + feature_not_found "docs" "Install texinfo, Perl/perl-podlators and a Python 3 version of python-sphinx" fi docs=no fi diff --git a/docs/conf.py b/docs/conf.py index ee7faa6b4e7..7588bf192ee 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,6 +28,16 @@ import os import sys +import sphinx +from sphinx.errors import VersionRequirementError + +# Make Sphinx fail cleanly if using an old Python, rather than obscurely +# failing because some code in one of our extensions doesn't work there. +# Unfortunately this doesn't display very neatly (there's an unavoidable +# Python backtrace) but at least the information gets printed... +if sys.version_info < (3,5): + raise VersionRequirementError( + "QEMU requires a Sphinx that uses Python 3.5 or better\n") # The per-manual conf.py will set qemu_docdir for a single-manual build; # otherwise set it here if this is an entire-manual-set build. From patchwork Thu Feb 6 17:30:14 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183106 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1836103ile; Thu, 6 Feb 2020 09:36:41 -0800 (PST) X-Google-Smtp-Source: APXvYqx8Yq7fBQa98IddAEDZF7gnX62E9Y+aWFoWL0Z4bSK8KJ/dEshkxkfaIO80dXcBTsXFQn2f X-Received: by 2002:ac8:530c:: with SMTP id t12mr3478944qtn.83.1581010600914; Thu, 06 Feb 2020 09:36:40 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010600; cv=none; d=google.com; s=arc-20160816; b=CXj7T1hdkJGqwUkqb+zZEKp9OP1ZE4fkBxPZSfqbUH8UuQeSRSotzOtlW3ATB/aVkA m1CUb03xSdvmleQwE9AwH/l5s2lNK3z/HlyEfhmCWJsFCKmk+Tf+TdeGznOdG6i8Xwyi BgfoWSwAGLU64NhLhyMMNEAMIjaVC2i3wvR8JT7C1BaCxoQshxRmkQ8/w6Qo/7WU4KnX c+Px75uvWDPa78TnxoySv5bGP2TqQ9R9c4c+SxZxaR/r50IUjuBSFMgtBdT/0wv3ZXxD LwmzyAoHHviNFRuZTXrYA3FXXi2qx56SP1cvoSPbwO0w+tjCxjFBfInLru5WjZkc+aed XzMQ== 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=E1tpXHsNOMFCBxdlvbzgg+MYBNzwjBDboyeQBHHvZGM=; b=Pl4T6qvDXs3Y5IYRVwXwUzHLBeAkINlhzJltjsqsg6vMdIyyHqTyo16ITsjlnCWKjA jq6QfTDD2vN2zpztOcOoahW94x6Tp43q7L9oUQ+zFuimhJqrNXusodUHh47nuq9KerhD VoV06KL4ys2wGHXyYQ+SVX9p0rI6UCGNGrcmZf2QsO0XqixLB6UsgCDzF3WJ/IcTxxgw MFY/5LadTu6mPkDbhIKOw389Y8DKqU+bXxYmMV9EpLKq2y2EpCzL5GermJO7Vvk/I4Ej v2UMaExWtXcfqCSVBlqivSqEAs3fUJ1sjzkL6+ShzOrLlJZomGiwX/1qtcWwtuTtv55t dFtg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=X03e9Yrq; 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 x2si1838613qkx.254.2020.02.06.09.36.40 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:36:40 -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=X03e9Yrq; 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]:43400 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl4p-0005gD-Gf for patch@linaro.org; Thu, 06 Feb 2020 12:36:32 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43314) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzN-00066M-En for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:55 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzM-00042x-Dz for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:53 -0500 Received: from mail-wr1-x441.google.com ([2a00:1450:4864:20::441]:33713) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzM-0003zG-6x for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:52 -0500 Received: by mail-wr1-x441.google.com with SMTP id u6so8237862wrt.0 for ; Thu, 06 Feb 2020 09:30:52 -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=E1tpXHsNOMFCBxdlvbzgg+MYBNzwjBDboyeQBHHvZGM=; b=X03e9YrqTAPYxUiKW42wPsUzBqsGmw3nZnKORBmgEzr/aY6kNuxIb5KNdx81teMjvf BPfUbK07JtvPbqwJgM9J/k1DSu4/o7LhZYVIRmNYechWV/o46CqqtxwcrR+t6YBBqfv1 NYILT2TPjDTg0xGToL1mpnuuomQoIHqHXTDSy9en35iLRgEDaLwj2TcDJ/95JrhZjEwQ EnGYcebb4DwF6HzVJ0SupnjUcd0ItNub7pzRJlKEI2ONv8yVADlpjw0wyUuwz36RBS0K cTXo7ajIUHXxmMd5+Bx7qV2AJtfp8y/zdedfQOAiFjUcovrW1uMi6iuwlJLf6q2+FcWr Kq9Q== 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=E1tpXHsNOMFCBxdlvbzgg+MYBNzwjBDboyeQBHHvZGM=; b=XNEz2TxAYMXlPZ5jHi/hqJ8zM5IuDU0G8SAXfzZJBLKKyM471caXvhK7yF5JKbi+Pj 6aww5yDF/ugPIZLxDFRczvw9FZV7R6ZCPWLJUBnTPis6tLlB8nVb42NpTwzLHDQbU70W dIhuYEZWQnJZtbAzbryeE1T0Zx4ByAIBt6WINoJN4lEMmf8DoxUj6cwimbjtKWGgd3X4 ebI91IIWrBffWniKxBZj66pNHmNbY0xASWh4vK7Vj8Hg/50YYDXoAk9R0WW3pP5M7WHC gmkC/wKi0XkJ4CZ2aIpTNSSCsl5i1aOvpqaj5s6FdZJIjpzc0rGxJweWbswOe77JDl6h v2ww== X-Gm-Message-State: APjAAAUFnCpI0ZxNa1OqyuKS2ivrFy4qTBWmhkp9uSpIPWqjrxiZdUBC 3i6O5sxxLmjS/BUtdmxPw1HYKhCB8Y0= X-Received: by 2002:a5d:53c1:: with SMTP id a1mr4731013wrw.373.1581010250763; Thu, 06 Feb 2020 09:30:50 -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.30.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:30:49 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 03/29] Makefile: Fix typo in dependency list for interop manpages Date: Thu, 6 Feb 2020 17:30:14 +0000 Message-Id: <20200206173040.17337-4-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::441 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" Fix a typo in the dependency list for the manpages built from the 'interop' manual, which meant we were accidentally not including the .hx file in the dependency list. Fixes: e13c59fa4414215500e6 Signed-off-by: Peter Maydell Reviewed-by: Philippe Mathieu-Daudé --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) -- 2.20.1 diff --git a/Makefile b/Makefile index 20bf0cc771a..274a24f7aa4 100644 --- a/Makefile +++ b/Makefile @@ -1052,7 +1052,7 @@ $(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system) $(call define-manpage-rule,interop,\ qemu-ga.8 qemu-img.1 qemu-nbd.8 qemu-trace-stap.1 virtfs-proxy-helper.1,\ - $(SRC_PATH/qemu-img-cmds.hx)) + $(SRC_PATH)/qemu-img-cmds.hx) $(call define-manpage-rule,system,qemu-block-drivers.7) From patchwork Thu Feb 6 17:30:15 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183111 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1838356ile; Thu, 6 Feb 2020 09:38:42 -0800 (PST) X-Google-Smtp-Source: APXvYqzRJClk8Meq1+jeIk7FElaX0PfZEhK+1zCsaEhr1Rt8GghPJoYwR6CZg8iC/MwghYGmJaPf X-Received: by 2002:a05:620a:1422:: with SMTP id k2mr3197601qkj.407.1581010722790; Thu, 06 Feb 2020 09:38:42 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010722; cv=none; d=google.com; s=arc-20160816; b=XNbw6OQbHP+h8+I2KGI69xmL3zwuSlNdIeOc7abaxU+SOL/REwlVLMcgnV/0ZwmX24 ExkdrkmRdO+6yuGI/1GuPewiEYzFrTiEpbTjM8UZdhO3NSkpA7Lb5v2fbjvLAPaXFyVs w0QXQI8XEiuo7xGl7Nakxb5YP0MzY9tjzJPWM9eOAIcpT0ziZP/UR2NOMmEz1wyKqMDN RITp8CcJu1y6nYTLOwGu52k6bdkCcRfhjhaMDvF3nClgrdDlj0AuaD+PfHf36G4pIose FWIeuvsLC8pvRCI02zff5OLFP4FJy+JcfdT9QUoRwKzVY/pYkbnNPkv5sAyt2Jikh6KK 2WZw== 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=DdTyceGkkwj9dEzcBkZjrrEjb4XQeMiC6gg82f8sScs=; b=c6ZH/+uatfE0BJVySL5QIm41Nwe1b3wamkMDd2lCifKQN6APdLIzz+1+Ee5fRCSEbC xb8OCBXhtYQ+VOs4TcZ3W6fe39tO+pJ+ekDB2u0hj79RiPtGapTvFxaDcwVW/sMXZGin pOHnguKRKHG5KGl+eUjRh3v5eg8fpjl3A7KS+09lC60Rq9fkQv517zZ+mnAjUYC0ypEh zdqWD9+uNc3R+XkK9Gce+0IRuaSLlIYtR1Lkaqzi40Ud6bH59L7fqSOePNap+qvn2gWz exGOeHWXZq8OwXR1aScKAWpoijHuF+jyLHtoeID3pzwWWdCsnsuFnkWE/RkglZGZqSQC umww== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=qOnzYlFP; 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 y27si63716qta.299.2020.02.06.09.38.42 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:38:42 -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=qOnzYlFP; 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]:43472 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl6w-0001G3-8r for patch@linaro.org; Thu, 06 Feb 2020 12:38:42 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43326) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzQ-0006AF-3J for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:56 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzP-0004Ds-59 for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:56 -0500 Received: from mail-wm1-x330.google.com ([2a00:1450:4864:20::330]:35043) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzO-0004Ah-Uk for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:55 -0500 Received: by mail-wm1-x330.google.com with SMTP id b17so1011295wmb.0 for ; Thu, 06 Feb 2020 09:30:54 -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=DdTyceGkkwj9dEzcBkZjrrEjb4XQeMiC6gg82f8sScs=; b=qOnzYlFP2huECs+jOx6ZRFEEzjmdM7EPXg8vfEK7BrZvsEpWdOj7n+vMVqu063ucbB IZA6ML1S8L5PJWd2YhW9enEH5XPIJOeW8BkpQSVE992NQ9HIBbV2k6B8nsMdmB8lpRdJ RIPuJJ5MIlydCHfLC0EpCv5AGOI9pHh1xP1dIkr+hTitAdJDJR2Njm+nEBL9K+y4Md4z uJOPLUYmiEaa3CSBYjqtudwo4R1EJL/hlhNOMkjbaS3mlGZxMcXdbQ/5KCvUOTE+tpmu wg/3s9oYvN24E5f+XG4Pm62BaZBohmVkjxzlZ9a5PR2miPCQO7HpTc2NBKgAkQ3qOiHh q2sw== 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=DdTyceGkkwj9dEzcBkZjrrEjb4XQeMiC6gg82f8sScs=; b=V0ZJseGG9ACcMxoUOM7Aup+YD4Dp6LnRouZspMugvyUN4qy8PO1VhHeNAIwxNWsdzT calZqAah8b4F9EjySTLtLCijtfu0yLpV1swdX9ln4tfivxnsjwu75GgKWak/U8QRPI/g bKtoF6Dhgz3ksUc+Er39k+k9TEY6LMjamB0Klgyuwar1JJpd+Mr/sSda4Ir9gB5e9/BA Drsjd2YHfVs2I/bxEODmBJv2plSI2hUNMeSUR3OL5q+LF0C7yRaA2Y+B7CfAFk/JBKLx yx5oTDKuR0u9xr1Nng8QlvMuNwdknPWXvTG54Djf0UFF4dGiTQSb73Eud3106Ctasjlc 3EOw== X-Gm-Message-State: APjAAAWgfkdzHKKgEXsMtG0N+gSPwsL1VuX5R7+MD7O2mEqlVTv7Mv+t m6+tNVZrU8ZaAsrS65/5rX9Tkdpp7QA= X-Received: by 2002:a1c:113:: with SMTP id 19mr5927295wmb.95.1581010253331; Thu, 06 Feb 2020 09:30:53 -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.30.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:30:51 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 04/29] qga/qapi-schema.json: Fix missing '-' in GuestDiskBusType doc comment Date: Thu, 6 Feb 2020 17:30:15 +0000 Message-Id: <20200206173040.17337-5-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::330 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" The doc comment for GuestDiskBusType doesn't match up with the enumeration because of a missing hyphen in 'file-backed-virtual'. This means the docs are rendered wrongly: "virtual" Win virtual bus type "file-backed" virtual: Win file-backed bus type "file-backed-virtual" Not documented Add the missing hyphen. Signed-off-by: Peter Maydell Reviewed-by: Eric Blake --- qga/qapi-schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) -- 2.20.1 Reviewed-by: Markus Armbruster diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index fb4605cc19c..23ce6af597d 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -809,7 +809,7 @@ # @sas: Win serial-attaches SCSI bus type # @mmc: Win multimedia card (MMC) bus type # @virtual: Win virtual bus type -# @file-backed virtual: Win file-backed bus type +# @file-backed-virtual: Win file-backed bus type # # Since: 2.2; 'Unknown' and all entries below since 2.4 ## From patchwork Thu Feb 6 17:30:16 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183113 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1840485ile; Thu, 6 Feb 2020 09:40:49 -0800 (PST) X-Google-Smtp-Source: APXvYqycmbqloS3ieL3NTH0ijS9172amfE5EQkp//J9nWEh3bzgb5lN6GIaj2T5fUNHAi8ZH62QL X-Received: by 2002:a05:6214:94b:: with SMTP id dn11mr3254181qvb.12.1581010849070; Thu, 06 Feb 2020 09:40:49 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010849; cv=none; d=google.com; s=arc-20160816; b=uWSWctAreydRy1Jv48GYy+omgmAvGcrw3jXxia/a74IQ4iAzXU/P8G0o534fub+pxx oiGl5gWroOHh6j8hXuIdMJAYEEmXMUcY+s0j6jZVQ9IxnbmMtUPlshXahm6IhL4pvT3K ofhiDgkhU1HCsRZDrcLOjjxYTzHHmPLq1IUIkqS/G1PbPskFhLioKxKcG4S2KGQoJkGr ynqpiSq+7ycRafOdmV90kJlYGhXiWM+793BjY8m1fDLR+CAlRekZEUGKf4qhOTLKbfk4 ru4RItvf2HzEqFUbc9+sEsA3B1iyNO/fyPxOaYxngHOZNojX2hlnYe79XEObLDWQKa49 aKZQ== 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=Lnpsrwwtw9p6atBL1H/6UxQGUHAlGeRQgeMneuYQwo4=; b=bSb/0aAvNxIF+uQKuIqgxNEF11FC/3jedkhglIooJ1pECu619juC8ok6dBb+CrhlwE NdKVwCKvYYuKaZ4LX9W+HctoHEIp9Wre81A4v+WDRliHo2dCcJP6RBUr7XXF9iE5Vd+U wifBVZTx6IxPZsw+5fk367ke/BMczPTIqvb74HDgfEIswiGMDzLY8/dKbN/wE52yUblY ebZhPancGcS/ryyoBvLNX+8WOd6K7ulbyX3JAFhe7hXgxQwDkucThjCWiJYHINRzCivr 1NTwNYq8uMniysx1leZfN40C/QSsW+L1mS5JDJXNoJ9iiC82ZV8nFBCb1mv82g/s9XHi ClhQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=rmW2qzF5; 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 p25si84130qtq.34.2020.02.06.09.40.48 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:40:49 -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=rmW2qzF5; 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]:43532 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl8y-0004ie-Iq for patch@linaro.org; Thu, 06 Feb 2020 12:40:48 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43340) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzT-0006Ia-NK for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:01 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzS-0004Pu-1g for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:59 -0500 Received: from mail-wm1-x342.google.com ([2a00:1450:4864:20::342]:54797) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzR-0004ME-QR for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:30:57 -0500 Received: by mail-wm1-x342.google.com with SMTP id g1so873236wmh.4 for ; Thu, 06 Feb 2020 09:30:57 -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=Lnpsrwwtw9p6atBL1H/6UxQGUHAlGeRQgeMneuYQwo4=; b=rmW2qzF5RIA9EB7aCZXP9NKnjxVmwy9FFJIn3jNMWdOFisSGCM2/gw0Yc1/h4sa9Fx Ml1ragLegtv5KtL3zgizlyu8xYRjVYE1Hnk7751mzKwf58UV+IsUnLlMOiev1ftgTZTw l6Wn6eUf31OI9BOIxNyLJ/FS7ygkHtX85W3+Lv67bHFfaT0wA28DsfQ5iwo5QSYomOmd eK7w5SsuADppV0f7MkmG5O3/3J+bo+iIyOSjIYs+qE9QKl47p7cWixS7ULvC9C1Q8cd0 15m2bDamt9uD6onO3nXhNadN46xy7sVGigzzvGT4crFMC9WtcNpdoXqHbtGnyiWCFO5y +X5w== 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=Lnpsrwwtw9p6atBL1H/6UxQGUHAlGeRQgeMneuYQwo4=; b=opIJ91ps06BozY5U+ozvTFxWNMIItWVQw1if14Li+2Nu9idH/XvXAgGY8nTZCWz1XG e+JyzOTqjQS+CuDx2SPaszgUBzxigm76+kIA5IaWsdZxPyaJK/meygaA0yRQE3m6iEbr 4Za91nxzKT+RiWuQq61y6F7kUvt+nT30KiN38F3SWNq499moDz+1w+CRxzKW2AIo4eF4 TGKoKOpTgn/gHeX52o3LomsXPCphxvN+pJ+7i9S+lYATt9TW+GJWp480hKOOB1BdIDM9 +mUS7V3sD8M6KdriFwX5kLWafJnVldZPT/eyyOpY37tMq9wjw0NWIUXCGqp10jZh62B6 Igkg== X-Gm-Message-State: APjAAAWY/SR5MavwiPs3TM9+ErskbPUUh4UCPJNu9GALlB5uTSIZUL6v C3E2rtMVKXm+NFyY1ZdVHR537on1OsI= X-Received: by 2002:a1c:dc08:: with SMTP id t8mr5706791wmg.139.1581010255653; Thu, 06 Feb 2020 09:30:55 -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.30.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:30:54 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 05/29] qga/qapi-schema.json: Fix indent level on doc comments Date: Thu, 6 Feb 2020 17:30:16 +0000 Message-Id: <20200206173040.17337-6-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::342 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" The texinfo doc generation doesn't care much about indentation levels, but we would like to add a rST backend, and rST does care about indentation. Make the doc comments more strongly consistent about indentation for multiline constructs like: @arg: description line 1 description line 2 Returns: line one line 2 so that there is always exactly one space after the colon, and subsequent lines align with the first. This commit is a purely whitespace change, and it does not alter the generated .texi files (because the texi generation code strips away all the extra whitespace). This does mean that we end up with some over-length lines. Note that when the documentation for an argument fits on a single line like this: @arg: one line only then stray extra spaces after the ':' don't affect the rST output, so I have not attempted to methodically fix them, though the preference is a single space here too. Signed-off-by: Peter Maydell --- qga/qapi-schema.json | 62 ++++++++++++++++++++++---------------------- 1 file changed, 31 insertions(+), 31 deletions(-) -- 2.20.1 Reviewed-by: Markus Armbruster diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 23ce6af597d..7661b2b3b45 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -416,7 +416,7 @@ # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below) # # Note: This may fail to properly report the current state as a result of -# some other guest processes having issued an fs freeze/thaw. +# some other guest processes having issued an fs freeze/thaw. # # Since: 0.15.0 ## @@ -431,13 +431,13 @@ # unfreeze. # # Note: On Windows, the command is implemented with the help of a -# Volume Shadow-copy Service DLL helper. The frozen state is limited -# for up to 10 seconds by VSS. +# Volume Shadow-copy Service DLL helper. The frozen state is limited +# for up to 10 seconds by VSS. # # Returns: Number of file systems currently frozen. On error, all filesystems -# will be thawed. If no filesystems are frozen as a result of this call, -# then @guest-fsfreeze-status will remain "thawed" and calling -# @guest-fsfreeze-thaw is not necessary. +# will be thawed. If no filesystems are frozen as a result of this call, +# then @guest-fsfreeze-status will remain "thawed" and calling +# @guest-fsfreeze-thaw is not necessary. # # Since: 0.15.0 ## @@ -455,7 +455,7 @@ # Invalid mount points are ignored. # # Returns: Number of file systems currently frozen. On error, all filesystems -# will be thawed. +# will be thawed. # # Since: 2.2 ## @@ -511,12 +511,12 @@ # Discard (or "trim") blocks which are not in use by the filesystem. # # @minimum: -# Minimum contiguous free range to discard, in bytes. Free ranges -# smaller than this may be ignored (this is a hint and the guest -# may not respect it). By increasing this value, the fstrim -# operation will complete more quickly for filesystems with badly -# fragmented free space, although not all blocks will be discarded. -# The default value is zero, meaning "discard every free block". +# Minimum contiguous free range to discard, in bytes. Free ranges +# smaller than this may be ignored (this is a hint and the guest +# may not respect it). By increasing this value, the fstrim +# operation will complete more quickly for filesystems with badly +# fragmented free space, although not all blocks will be discarded. +# The default value is zero, meaning "discard every free block". # # Returns: A @GuestFilesystemTrimResponse which contains the # status of all trimmed paths. (since 2.4) @@ -693,7 +693,7 @@ # @ip-addresses: List of addresses assigned to @name # # @statistics: various statistic counters related to @name -# (since 2.11) +# (since 2.11) # # Since: 1.1 ## @@ -743,7 +743,7 @@ # This is a read-only operation. # # Returns: The list of all VCPUs the guest knows about. Each VCPU is put on the -# list exactly once, but their order is unspecified. +# list exactly once, but their order is unspecified. # # Since: 1.5 ## @@ -937,8 +937,8 @@ # This is a read-only operation. # # Returns: The list of all memory blocks the guest knows about. -# Each memory block is put on the list exactly once, but their order -# is unspecified. +# Each memory block is put on the list exactly once, but their order +# is unspecified. # # Since: 2.3 ## @@ -971,9 +971,9 @@ # @response: the result of memory block operation. # # @error-code: the error number. -# When memory block operation fails, we assign the value of -# 'errno' to this member, it indicates what goes wrong. -# When the operation succeeds, it will be omitted. +# When memory block operation fails, we assign the value of +# 'errno' to this member, it indicates what goes wrong. +# When the operation succeeds, it will be omitted. # # Since: 2.3 ## @@ -1040,15 +1040,15 @@ # @exited: true if process has already terminated. # @exitcode: process exit code if it was normally terminated. # @signal: signal number (linux) or unhandled exception code -# (windows) if the process was abnormally terminated. +# (windows) if the process was abnormally terminated. # @out-data: base64-encoded stdout of the process # @err-data: base64-encoded stderr of the process -# Note: @out-data and @err-data are present only -# if 'capture-output' was specified for 'guest-exec' +# Note: @out-data and @err-data are present only +# if 'capture-output' was specified for 'guest-exec' # @out-truncated: true if stdout was not fully captured -# due to size limitation. +# due to size limitation. # @err-truncated: true if stderr was not fully captured -# due to size limitation. +# due to size limitation. # # Since: 2.5 ## @@ -1131,8 +1131,8 @@ ## # @GuestUser: -# @user: Username -# @domain: Logon domain (windows only) +# @user: Username +# @domain: Logon domain (windows only) # @login-time: Time of login of this user on the computer. If multiple # instances of the user are logged in, the earliest login time is # reported. The value is in fractional seconds since epoch time. @@ -1156,10 +1156,10 @@ ## # @GuestTimezone: # -# @zone: Timezone name. These values may differ depending on guest/OS and -# should only be used for informational purposes. -# @offset: Offset to UTC in seconds, negative numbers for time zones west of -# GMT, positive numbers for east +# @zone: Timezone name. These values may differ depending on guest/OS and +# should only be used for informational purposes. +# @offset: Offset to UTC in seconds, negative numbers for time zones west of +# GMT, positive numbers for east # # Since: 2.10 ## From patchwork Thu Feb 6 17:30:17 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183105 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1833369ile; Thu, 6 Feb 2020 09:34:02 -0800 (PST) X-Google-Smtp-Source: APXvYqwSVQH7rBKL/w6bEVnC5v8ykOpiNV2/QqcyNm4omx8bojL1rW56zL/TQ3uZ1aG3EeSpS3TO X-Received: by 2002:a05:620a:2013:: with SMTP id c19mr3433435qka.496.1581010442483; Thu, 06 Feb 2020 09:34:02 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010442; cv=none; d=google.com; s=arc-20160816; b=Vkt3s404YP8AAK4kW7s13rvGRtgIMi3VNNRm9Fz3Ky3cEqc/p2nJsFRvvq/QRjohT+ HVuHPfmd4waD+LxbVGTKfeBJm+4bL2T2VXKS37KddnSCL9moprFEElaG9ZqG3xbbvKKb l3MTZjsBHP7BHHAxWSWie2U5Q8jn8SRqyJxbrHIoFq9fcJCFxRMXLOg7WgLaZefMHo/e 7bBCJA9ZZ8IjaFYj/4eu3bMdhAiei8KIqhn5xvFDFik8cQ2Tth/rmYDP2Kw4Raal2rKR MV7tHnFBEISD0by/EGaPx/o9HPnL65vTPSQLdzvGmm9EOWBN48xoITeAJmSWBkyeMVvV 3MYQ== 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=j01HaJa7YmpTA4lG3GLiIjZ2qBKws2nRm9bPekFuhHI=; b=IvJ5SM66ml9qKTQ4FEZJ0qAUYgm/tx+qAfBcfIikmFoHmGeVbm3TlvGwTcxSzGyAma Ixg7DYV3eqZtAPXo4w3628l54o1jA0YO3TO1auLVi6/IXqIfmiLKKX885zhPC8nBxoni 7ACZ8ihwunqzlSHEorOljS8qi395hYMHH9aawk5+wOaUfOsvOIExUxoXrpR2RZ9Katwt z+b2MGopgu+9EKHJY7KDES4Kre9OY6baBPKQyyp+STZVWYUuUU4jt6oEjx6OMGKWumMU WRgve3FZD3AY8ienBx08/hZTA5xRrbOB0ip3H7hqfsFKuJ2EuKcRZ4GL5HbZgwUWx33N sjNg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=wnMghCK4; 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 g21si1947299qki.127.2020.02.06.09.34.02 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:34:02 -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=wnMghCK4; 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]:43364 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl2P-0002VB-Ux for patch@linaro.org; Thu, 06 Feb 2020 12:34:02 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43364) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzX-0006RJ-BN for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:05 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzU-0004ZF-9W for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:03 -0500 Received: from mail-wr1-x435.google.com ([2a00:1450:4864:20::435]:38036) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzU-0004VV-20 for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:00 -0500 Received: by mail-wr1-x435.google.com with SMTP id y17so8203128wrh.5 for ; Thu, 06 Feb 2020 09:30:59 -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=j01HaJa7YmpTA4lG3GLiIjZ2qBKws2nRm9bPekFuhHI=; b=wnMghCK4szupAcemQr4p8BKf7eYSGJqDiPFlFFS2oislWOUjm1CWSv4u/I+qm05YdO 9l5s2Y2a8zl9JzCmpEfjNj6jXffyI5FgqEqd/ghxW0vb0lzGNmpLoA2hwUTAMAmmtaXk m4b3D5P3jkcigEaTZhkNiCz2kiOnoH/N2DbIT783WosuMUOwVYw8ts8CQXu8Rz0RA77Q 7mnSPLtI5hesjdaVUVVD0wPKNbV7r3QpdKSiDEvSQzFOHYNcTZ67j0qKzWueEaACkyUf mdRc3aLHVBTAue/PDRPyfnxdwA7/OYgPEqsNirBtDdr8+WJwm6HNjb7SD+lH6NGpIiv8 mbew== 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=j01HaJa7YmpTA4lG3GLiIjZ2qBKws2nRm9bPekFuhHI=; b=eDqZEKEC1wf8yrnk67xt4OQdGrLd87nZzIwMY0BcWQS4VfDsG4DNHsrhSSQHMPkGEP gJ51Gi8vxIuX6x/BqSDVHgFrOTAkG359s7yr+yoahXSOGD2TsdLoU9mkFFoGsaV5X4X4 OHnLyJIGqD3LVd8chB1oIOtd+fCKe1Mwk0le/sVrLL0vlhf71JsGvJ7MrTWxAiyYiF+X OeEMS9/aAt1nKu8JQGFYxXWXYkXHi6HogX0h8/JDV38n+Joeo4FJzUFCEeI0aH9fERHC 63NHlO90/JcfOtXhKK3KTeEFgOmxp1411+V9milbzdbwDH60qHoi7fy0fxut5vKlTObM Hhxg== X-Gm-Message-State: APjAAAXZAZE69bMXgnlJPdqflAnZOHjHGhW/e0dbBPseE+5RyxV9FQc1 +1DEI9wdb49TmbS8kJAOmh+oUJBA1Js= X-Received: by 2002:a5d:4702:: with SMTP id y2mr4676037wrq.37.1581010257979; Thu, 06 Feb 2020 09:30:57 -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.30.55 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:30:56 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 06/29] qga/qapi-schema.json: minor format fixups for rST Date: Thu, 6 Feb 2020 17:30:17 +0000 Message-Id: <20200206173040.17337-7-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::435 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" rST format requires a blank line before the start of a bulleted or enumerated list. Two places in qapi-schema.json were missing this blank line. Some places were using an indented line as a sort of single-item bulleted list, which in the texinfo output comes out all run onto a single line; use a real bulleted list instead. Some places unnecessarily indented lists, which confuses rST. guest-fstrim:minimum's documentation was indented the right amount to share a line with @minimum, but wasn't actually doing so. The indent on the bulleted list in the guest-set-vcpus Returns section meant rST misindented it. Changes to the generated texinfo are very minor (the new bulletted lists, and a few extra blank lines). Signed-off-by: Peter Maydell --- qga/qapi-schema.json | 86 +++++++++++++++++++++++--------------------- 1 file changed, 45 insertions(+), 41 deletions(-) -- 2.20.1 diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 7661b2b3b45..0e3a00ee052 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -510,8 +510,7 @@ # # Discard (or "trim") blocks which are not in use by the filesystem. # -# @minimum: -# Minimum contiguous free range to discard, in bytes. Free ranges +# @minimum: Minimum contiguous free range to discard, in bytes. Free ranges # smaller than this may be ignored (this is a hint and the guest # may not respect it). By increasing this value, the fstrim # operation will complete more quickly for filesystems with badly @@ -546,7 +545,8 @@ # (or set its status to "shutdown") due to other reasons. # # The following errors may be returned: -# If suspend to disk is not supported, Unsupported +# +# - If suspend to disk is not supported, Unsupported # # Notes: It's strongly recommended to issue the guest-sync command before # sending commands when the guest resumes @@ -575,12 +575,14 @@ # # This command does NOT return a response on success. There are two options # to check for success: -# 1. Wait for the SUSPEND QMP event from QEMU -# 2. Issue the query-status QMP command to confirm the VM status is -# "suspended" +# +# 1. Wait for the SUSPEND QMP event from QEMU +# 2. Issue the query-status QMP command to confirm the VM status is +# "suspended" # # The following errors may be returned: -# If suspend to ram is not supported, Unsupported +# +# - If suspend to ram is not supported, Unsupported # # Notes: It's strongly recommended to issue the guest-sync command before # sending commands when the guest resumes @@ -607,12 +609,14 @@ # # This command does NOT return a response on success. There are two options # to check for success: -# 1. Wait for the SUSPEND QMP event from QEMU -# 2. Issue the query-status QMP command to confirm the VM status is -# "suspended" +# +# 1. Wait for the SUSPEND QMP event from QEMU +# 2. Issue the query-status QMP command to confirm the VM status is +# "suspended" # # The following errors may be returned: -# If hybrid suspend is not supported, Unsupported +# +# - If hybrid suspend is not supported, Unsupported # # Notes: It's strongly recommended to issue the guest-sync command before # sending commands when the guest resumes @@ -767,17 +771,17 @@ # Returns: The length of the initial sublist that has been successfully # processed. The guest agent maximizes this value. Possible cases: # -# - 0: if the @vcpus list was empty on input. Guest state -# has not been changed. Otherwise, -# - Error: processing the first node of @vcpus failed for the -# reason returned. Guest state has not been changed. -# Otherwise, +# - 0: if the @vcpus list was empty on input. Guest state +# has not been changed. Otherwise, +# - Error: processing the first node of @vcpus failed for the +# reason returned. Guest state has not been changed. +# Otherwise, # - < length(@vcpus): more than zero initial nodes have been processed, -# but not the entire @vcpus list. Guest state has -# changed accordingly. To retrieve the error -# (assuming it persists), repeat the call with the -# successfully processed initial sublist removed. -# Otherwise, +# but not the entire @vcpus list. Guest state has +# changed accordingly. To retrieve the error +# (assuming it persists), repeat the call with the +# successfully processed initial sublist removed. +# Otherwise, # - length(@vcpus): call successful. # # Since: 1.5 @@ -1182,35 +1186,35 @@ # @GuestOSInfo: # # @kernel-release: -# * POSIX: release field returned by uname(2) -# * Windows: build number of the OS +# * POSIX: release field returned by uname(2) +# * Windows: build number of the OS # @kernel-version: -# * POSIX: version field returned by uname(2) -# * Windows: version number of the OS +# * POSIX: version field returned by uname(2) +# * Windows: version number of the OS # @machine: -# * POSIX: machine field returned by uname(2) -# * Windows: one of x86, x86_64, arm, ia64 +# * POSIX: machine field returned by uname(2) +# * Windows: one of x86, x86_64, arm, ia64 # @id: -# * POSIX: as defined by os-release(5) -# * Windows: contains string "mswindows" +# * POSIX: as defined by os-release(5) +# * Windows: contains string "mswindows" # @name: -# * POSIX: as defined by os-release(5) -# * Windows: contains string "Microsoft Windows" +# * POSIX: as defined by os-release(5) +# * Windows: contains string "Microsoft Windows" # @pretty-name: -# * POSIX: as defined by os-release(5) -# * Windows: product name, e.g. "Microsoft Windows 10 Enterprise" +# * POSIX: as defined by os-release(5) +# * Windows: product name, e.g. "Microsoft Windows 10 Enterprise" # @version: -# * POSIX: as defined by os-release(5) -# * Windows: long version string, e.g. "Microsoft Windows Server 2008" +# * POSIX: as defined by os-release(5) +# * Windows: long version string, e.g. "Microsoft Windows Server 2008" # @version-id: -# * POSIX: as defined by os-release(5) -# * Windows: short version identifier, e.g. "7" or "20012r2" +# * POSIX: as defined by os-release(5) +# * Windows: short version identifier, e.g. "7" or "20012r2" # @variant: -# * POSIX: as defined by os-release(5) -# * Windows: contains string "server" or "client" +# * POSIX: as defined by os-release(5) +# * Windows: contains string "server" or "client" # @variant-id: -# * POSIX: as defined by os-release(5) -# * Windows: contains string "server" or "client" +# * POSIX: as defined by os-release(5) +# * Windows: contains string "server" or "client" # # Notes: # From patchwork Thu Feb 6 17:30:18 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183108 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1836524ile; Thu, 6 Feb 2020 09:37:03 -0800 (PST) X-Google-Smtp-Source: APXvYqyeRV+pSPBZVWZ1943nW5Rx7lhh+erKDT9RG0OhLyugpdPn0tJ1vRV+STvnew+e6F9mAiY4 X-Received: by 2002:ad4:4a2e:: with SMTP id n14mr3376574qvz.62.1581010623760; Thu, 06 Feb 2020 09:37:03 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010623; cv=none; d=google.com; s=arc-20160816; b=0ma3ptOD0CeIMaxyQFzpK0TXGSlt5N80+PJy3T3WMdV/qP3UQIcuuxZ6aKNIcrQZ8E zYb0+/OAmdqxEKfJPaYpBgZGFRlTngcez7YMHvdFXCt5aDCWRAe6iN7+DPu7QkBhIjf/ Uj5RX5wUOUwE5e1mkO2CBse4tHrKEZGGU1MJp2Vq62QVfNHTMcDoWtakTGUvS7fdAlSo fp/cAnI3HM7s4dRHmakBb4cImMspXdx2vgdh7UDzgh7H380QCBS6vu2wPnXm5lhHo35H De2JG2VtQPRu6CrHc0EkpOgiOUwylm9P7u57yDlMoT94NqwctLp0A2gDWGrq2duWy1YN e68A== 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=ssc89zv9+RZLwcUi0++cKCgLk2IYFvvZeGFDNP5kcHY=; b=RTLWV/0Vn6Ksn3YxE1LwiX32gtiP3zshUrOTFSB1vD9LAfyCn4f1jKaCPitVDTAPR4 rQnmvBrzxacRU++IiZyf1ZCUyVLDofVLtCFXqF795TaT1M+tNGCsrnkk3rcX9cWy8RAq QwkJCUr+Bhm/0zk1RQtZhhLnZh8yzfUFcRqQ5lItTKeJdHYr+shIJRbFNQ0XKQAw8thF U50J5w04o+y92ugRFzagJJYBy/1h9a7UPUGrA71Q/fOvCwp8OHEMhV668k4S9bpkmQ/y ZT3NFwwEyxSvPAOcLB+/y63YNqR+x/OU/K2WOfgmjoxdDwY0EWhThxzaSR8gxXXBkJtZ 00aA== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=caW5XHqQ; 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 j4si54354qtq.307.2020.02.06.09.37.03 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:37:03 -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=caW5XHqQ; 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]:43404 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl5L-0005qH-4n for patch@linaro.org; Thu, 06 Feb 2020 12:37:03 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43371) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzY-0006UO-AV for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:05 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzX-0004me-Ag for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:04 -0500 Received: from mail-wm1-x341.google.com ([2a00:1450:4864:20::341]:55485) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzX-0004if-3H for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:03 -0500 Received: by mail-wm1-x341.google.com with SMTP id q9so864001wmj.5 for ; Thu, 06 Feb 2020 09:31:02 -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=ssc89zv9+RZLwcUi0++cKCgLk2IYFvvZeGFDNP5kcHY=; b=caW5XHqQfUoLTPjn917Juh1gUyb8Sk1xcneOxhzBNUuJ/IxFgEm5zWR/gtaoEEh/yY IWwkKvQoNaMaK/82/tsVt8Sp7Xq5NKXglFiPR3g4wbFf1qX13eEmgrpFYTO66KR9KkmO m24gh4zAYn0fdYGLyk5OOPp9Y+gGw3ybFH1XbHQXICBVHP14oV7RFVznta7ALaidaLSv VW64aQIn7dUZxcWQ18bjUT68hh9jebqWM/zcW/PdesGCcp5oY/h0ATqWArhw/qWYJlL8 Shh0NpsyJI7kfEBJgTwfh6zcV7gT+9jdRzE9dSBW2N/1aE9RLejnjiuiDIxVajCp7hji qeuw== 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=ssc89zv9+RZLwcUi0++cKCgLk2IYFvvZeGFDNP5kcHY=; b=loLO5usjUtcGQCtgFi+HvRlS3WV9Gl+0Fel0XQT5x45bZxsZTkpyKGnzsZ+UcCS9WQ ACnhzDeIa0rlkfV4/nzlYiW9NSfA9iPoFuzTfilGkEKFsxyGuEKLPOKnp9WkcLJIA1YT 3K5+/2zGX+rqCCRSUbZg5GFqufsCBn8RxtlfBNdgqvxZPXJzobEn4l6ZxWQ26yd5VQ+x KRb/OAvwlVhiTJv4IxEbAQa0zhPA0msAF0hXT80z2ESLfzAKKGY64a7HEku9bH7dnr85 Yk164PBwrHlh/vzqNEUAC3euR6Zua6k3fptV/c6bdlVtrb64L/hmesYQKfasC11cceD5 a5Qw== X-Gm-Message-State: APjAAAVK+a6Q+QrYoD2yeY3PO3EmWk/b6Kao4hfRuoiJpJpOGLl3UdY6 cJ9GEZ0AybXemhCdfBMZisz03GvP63w= X-Received: by 2002:a1c:a947:: with SMTP id s68mr5803956wme.61.1581010261044; Thu, 06 Feb 2020 09:31:01 -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.30.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:30:59 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 07/29] qapi/block-core.json: Use literal block for ascii art Date: Thu, 6 Feb 2020 17:30:18 +0000 Message-Id: <20200206173040.17337-8-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::341 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" The ascii-art graph in the BlockLatencyHistogramInfo documentation doesn't render correctly in either the HTML or the manpage output, because in both cases the whitespace is collapsed. Use the '|' format that emits a literal 'example' block so the graph is displayed correctly. Signed-off-by: Peter Maydell --- qapi/block-core.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) -- 2.20.1 diff --git a/qapi/block-core.json b/qapi/block-core.json index ef94a296868..372f35ee5f0 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -550,13 +550,13 @@ # For the example above, @bins may be something like [3, 1, 5, 2], # and corresponding histogram looks like: # -# 5| * -# 4| * -# 3| * * -# 2| * * * -# 1| * * * * -# +------------------ -# 10 50 100 +# | 5| * +# | 4| * +# | 3| * * +# | 2| * * * +# | 1| * * * * +# | +------------------ +# | 10 50 100 # # Since: 4.0 ## From patchwork Thu Feb 6 17:30:19 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183110 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1836660ile; Thu, 6 Feb 2020 09:37:11 -0800 (PST) X-Google-Smtp-Source: APXvYqwUDUj+EGzZZm+7lma3/J1OF1a0Mv5zgp0ROMExczBncWctlCIUECMTmuAz7D45wHEF1WBr X-Received: by 2002:a0c:a998:: with SMTP id a24mr3409588qvb.11.1581010631169; Thu, 06 Feb 2020 09:37:11 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010631; cv=none; d=google.com; s=arc-20160816; b=0TmWtEPe3hcpOfwXzm+mlRu9yq8OEVCBJC1hyNzDOgU/cglWMPpex4+qQvru4StVdz mx9w+pyf8VG3RqDo4xr8iiioLDc+6EGuCmCZAowrQggZWBd5qEnsyu/L9VHdozrIa+S2 NM9ELVqVQr/nUhbb5KIdGWNGw1YAEjxD8DnM3QuEW5ws5lPpRCxc4SRgKm0mjsBuqReO 3WKYC4xpE/KhfsSFGcdY7LOmI9Ec9CXHzTV1HC+2Nxf1ZUwQAXslViwT3jxC3oqPHP4i xeKi5rmyXO+t2OaGpLoLC3PXLIeCJjrEGNKfddzJEF5rKaHNXvHUJO4Nic9K/YGt/5zd 3hQQ== 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=Nii6KloRzb9ik6RzFqLYY2ekJtWFz5U3rmF8nlmzCmo=; b=uJ1C51V6sc4v8ENWurTuzuvFl38E8eMG96tV2ODILS+54eE5Xn+1tZwu2UqsximCtf N7OtPNyxH0iMngEoU0we8Y1+JyqBRtiQcVkcTpy2WnMDuJ4suRwk0AWlSq0f7DnP9KNH yRyGMbdm2eTrgBRyNCUB+Okb5Ywlwvi/BBXhCA557qV8/iU2xuV3ab8UPt+YGiebtF01 ZBkOsb+BZgzgnblhczsLdoSxOwZio6lkc0lVgSJ7SJXXVaargYz1PNuM0uwWLo5CnZsu HpzueIECTfUqCA2PFa7raq7pa0dRp5rVTBX70EQc5doCYJ7FPEtUtPrYDVt68HxBXHi1 omHw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=jAyfY9wY; 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 t19si68063qto.107.2020.02.06.09.37.11 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:37:11 -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=jAyfY9wY; 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]:43432 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl5S-0006rq-J1 for patch@linaro.org; Thu, 06 Feb 2020 12:37:10 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43393) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzd-0006bi-QY for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:13 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkza-00052Y-Q8 for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:09 -0500 Received: from mail-wr1-x42f.google.com ([2a00:1450:4864:20::42f]:34008) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkza-0004xL-G9 for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:06 -0500 Received: by mail-wr1-x42f.google.com with SMTP id t2so8226526wrr.1 for ; Thu, 06 Feb 2020 09:31:06 -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=Nii6KloRzb9ik6RzFqLYY2ekJtWFz5U3rmF8nlmzCmo=; b=jAyfY9wY/xHuw40YiHJFg6rjKaLGq845BPPmpl+V4DZDiF2viIOZBC7SoK/4MOhvej uWlHQiLGyox+Hu1ztOIwI4AF6gVKRkZu4h6m4GQuCHPDAWqWIwciixolDf3vLEpc8Uup wudF6tR9h4pzTF78XBIr19x77GhDBjun/uB7s/RKsN5KaMKGirvQPMkZzp1Ea3g8jBgI HN3MwR2HonXYP1rj4XjxWffa1znWIVLKPq/x5UDbmLtDUIWV/9aj0cMjqal5uLq+T0Y8 itNXMjAANWLy5pclm5bh8Do9D454kNSIEw6NutMR/rkAHQNiPMB0Q3Eh/kcpUHuoSc6a c0ZA== 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=Nii6KloRzb9ik6RzFqLYY2ekJtWFz5U3rmF8nlmzCmo=; b=Bn23vUnjAE687XGNy3MtK8kE5LVvFK0fxzVkWo2QXrIpNiSBJYX67fEXB6Bdj2F7Pq Pu0X6xi9zV9q4zsN/q3vP1e7yg+Evb/IhxL4+GPFzWxWOBKAt1e9lKx/hK9lU7I1wFhr fhnhIVuha1bGcAEOiQn/YeY+Ocm+iZ1bkskExL6eXgrrl3sPX7aBC9Hm631RblqZxiGk bA5ljPn7enrV66csCSxvzqfsvQBLUe+P2t7vtJNGLci5SjV/xk3XlktvoOUk4sGA/LU5 grcKs67Pu2KYkYSvKh3BO+WIskH0a61cBLU8X4AqnQxIV2JvxwbtrsKss+UO3NSqAYXm SBQA== X-Gm-Message-State: APjAAAXtp/By5N1IkEtTR7dGgmbuBiZiY0LKx70YAjrm1fACMCL03eVR IXwf3flw3D/JDntUP4eGzvuK8iNCI3c= X-Received: by 2002:adf:fa50:: with SMTP id y16mr5224226wrr.204.1581010263936; Thu, 06 Feb 2020 09:31:03 -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.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:02 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 08/29] qapi: Use ':' after @argument in doc comments Date: Thu, 6 Feb 2020 17:30:19 +0000 Message-Id: <20200206173040.17337-9-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::42f 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" Some qapi doc comments have forgotten the ':' after the @argument, like this: # @filename Filename for the new image file # @size Size of the virtual disk in bytes The result is that these are parsed as part of the body text and appear as a run-on line: filename Filename for the new image file size Size of the virtual disk in bytes" followed by filename: string Not documented size: int Not documented in the 'Members' section. Correct the formatting. Signed-off-by: Peter Maydell --- qapi/block-core.json | 236 +++++++++++++++++++++---------------------- 1 file changed, 118 insertions(+), 118 deletions(-) -- 2.20.1 Reviewed-by: Markus Armbruster diff --git a/qapi/block-core.json b/qapi/block-core.json index 372f35ee5f0..076a4a4808e 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -3235,9 +3235,9 @@ ## # @SshHostKeyCheckMode: # -# @none Don't check the host key at all -# @hash Compare the host key with a given hash -# @known_hosts Check the host key against the known_hosts file +# @none: Don't check the host key at all +# @hash: Compare the host key with a given hash +# @known_hosts: Check the host key against the known_hosts file # # Since: 2.12 ## @@ -3247,8 +3247,8 @@ ## # @SshHostKeyCheckHashType: # -# @md5 The given hash is an md5 hash -# @sha1 The given hash is an sha1 hash +# @md5: The given hash is an md5 hash +# @sha1: The given hash is an sha1 hash # # Since: 2.12 ## @@ -3258,8 +3258,8 @@ ## # @SshHostKeyHash: # -# @type The hash algorithm used for the hash -# @hash The expected hash value +# @type: The hash algorithm used for the hash +# @hash: The expected hash value # # Since: 2.12 ## @@ -4265,13 +4265,13 @@ # # Driver specific image creation options for file. # -# @filename Filename for the new image file -# @size Size of the virtual disk in bytes -# @preallocation Preallocation mode for the new image (default: off; -# allowed values: off, -# falloc (if defined CONFIG_POSIX_FALLOCATE), -# full (if defined CONFIG_POSIX)) -# @nocow Turn off copy-on-write (valid only on btrfs; default: off) +# @filename: Filename for the new image file +# @size: Size of the virtual disk in bytes +# @preallocation: Preallocation mode for the new image (default: off; +# allowed values: off, +# falloc (if defined CONFIG_POSIX_FALLOCATE), +# full (if defined CONFIG_POSIX)) +# @nocow: Turn off copy-on-write (valid only on btrfs; default: off) # # Since: 2.12 ## @@ -4286,12 +4286,12 @@ # # Driver specific image creation options for gluster. # -# @location Where to store the new image file -# @size Size of the virtual disk in bytes -# @preallocation Preallocation mode for the new image (default: off; -# allowed values: off, -# falloc (if defined CONFIG_GLUSTERFS_FALLOCATE), -# full (if defined CONFIG_GLUSTERFS_ZEROFILL)) +# @location: Where to store the new image file +# @size: Size of the virtual disk in bytes +# @preallocation: Preallocation mode for the new image (default: off; +# allowed values: off, +# falloc (if defined CONFIG_GLUSTERFS_FALLOCATE), +# full (if defined CONFIG_GLUSTERFS_ZEROFILL)) # # Since: 2.12 ## @@ -4305,11 +4305,11 @@ # # Driver specific image creation options for LUKS. # -# @file Node to create the image format on -# @size Size of the virtual disk in bytes -# @preallocation Preallocation mode for the new image -# (since: 4.2) -# (default: off; allowed values: off, metadata, falloc, full) +# @file: Node to create the image format on +# @size: Size of the virtual disk in bytes +# @preallocation: Preallocation mode for the new image +# (since: 4.2) +# (default: off; allowed values: off, metadata, falloc, full) # # Since: 2.12 ## @@ -4324,8 +4324,8 @@ # # Driver specific image creation options for NFS. # -# @location Where to store the new image file -# @size Size of the virtual disk in bytes +# @location: Where to store the new image file +# @size: Size of the virtual disk in bytes # # Since: 2.12 ## @@ -4338,9 +4338,9 @@ # # Driver specific image creation options for parallels. # -# @file Node to create the image format on -# @size Size of the virtual disk in bytes -# @cluster-size Cluster size in bytes (default: 1 MB) +# @file: Node to create the image format on +# @size: Size of the virtual disk in bytes +# @cluster-size: Cluster size in bytes (default: 1 MB) # # Since: 2.12 ## @@ -4354,11 +4354,11 @@ # # Driver specific image creation options for qcow. # -# @file Node to create the image format on -# @size Size of the virtual disk in bytes -# @backing-file File name of the backing file if a backing file -# should be used -# @encrypt Encryption options if the image should be encrypted +# @file: Node to create the image format on +# @size: Size of the virtual disk in bytes +# @backing-file: File name of the backing file if a backing file +# should be used +# @encrypt: Encryption options if the image should be encrypted # # Since: 2.12 ## @@ -4385,24 +4385,24 @@ # # Driver specific image creation options for qcow2. # -# @file Node to create the image format on -# @data-file Node to use as an external data file in which all guest -# data is stored so that only metadata remains in the qcow2 -# file (since: 4.0) -# @data-file-raw True if the external data file must stay valid as a -# standalone (read-only) raw image without looking at qcow2 -# metadata (default: false; since: 4.0) -# @size Size of the virtual disk in bytes -# @version Compatibility level (default: v3) -# @backing-file File name of the backing file if a backing file -# should be used -# @backing-fmt Name of the block driver to use for the backing file -# @encrypt Encryption options if the image should be encrypted -# @cluster-size qcow2 cluster size in bytes (default: 65536) -# @preallocation Preallocation mode for the new image (default: off; -# allowed values: off, falloc, full, metadata) -# @lazy-refcounts True if refcounts may be updated lazily (default: off) -# @refcount-bits Width of reference counts in bits (default: 16) +# @file: Node to create the image format on +# @data-file: Node to use as an external data file in which all guest +# data is stored so that only metadata remains in the qcow2 +# file (since: 4.0) +# @data-file-raw: True if the external data file must stay valid as a +# standalone (read-only) raw image without looking at qcow2 +# metadata (default: false; since: 4.0) +# @size: Size of the virtual disk in bytes +# @version: Compatibility level (default: v3) +# @backing-file: File name of the backing file if a backing file +# should be used +# @backing-fmt: Name of the block driver to use for the backing file +# @encrypt: Encryption options if the image should be encrypted +# @cluster-size: qcow2 cluster size in bytes (default: 65536) +# @preallocation: Preallocation mode for the new image (default: off; +# allowed values: off, falloc, full, metadata) +# @lazy-refcounts: True if refcounts may be updated lazily (default: off) +# @refcount-bits: Width of reference counts in bits (default: 16) # # Since: 2.12 ## @@ -4425,13 +4425,13 @@ # # Driver specific image creation options for qed. # -# @file Node to create the image format on -# @size Size of the virtual disk in bytes -# @backing-file File name of the backing file if a backing file -# should be used -# @backing-fmt Name of the block driver to use for the backing file -# @cluster-size Cluster size in bytes (default: 65536) -# @table-size L1/L2 table size (in clusters) +# @file: Node to create the image format on +# @size: Size of the virtual disk in bytes +# @backing-file: File name of the backing file if a backing file +# should be used +# @backing-fmt: Name of the block driver to use for the backing file +# @cluster-size: Cluster size in bytes (default: 65536) +# @table-size: L1/L2 table size (in clusters) # # Since: 2.12 ## @@ -4448,10 +4448,10 @@ # # Driver specific image creation options for rbd/Ceph. # -# @location Where to store the new image file. This location cannot -# point to a snapshot. -# @size Size of the virtual disk in bytes -# @cluster-size RBD object size +# @location: Where to store the new image file. This location cannot +# point to a snapshot. +# @size: Size of the virtual disk in bytes +# @cluster-size: RBD object size # # Since: 2.12 ## @@ -4499,23 +4499,23 @@ # # Driver specific image creation options for VMDK. # -# @file Where to store the new image file. This refers to the image -# file for monolithcSparse and streamOptimized format, or the -# descriptor file for other formats. -# @size Size of the virtual disk in bytes -# @extents Where to store the data extents. Required for monolithcFlat, -# twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For -# monolithicFlat, only one entry is required; for -# twoGbMaxExtent* formats, the number of entries required is -# calculated as extent_number = virtual_size / 2GB. Providing -# more extents than will be used is an error. -# @subformat The subformat of the VMDK image. Default: "monolithicSparse". -# @backing-file The path of backing file. Default: no backing file is used. -# @adapter-type The adapter type used to fill in the descriptor. Default: ide. -# @hwversion Hardware version. The meaningful options are "4" or "6". -# Default: "4". -# @zeroed-grain Whether to enable zeroed-grain feature for sparse subformats. -# Default: false. +# @file: Where to store the new image file. This refers to the image +# file for monolithcSparse and streamOptimized format, or the +# descriptor file for other formats. +# @size: Size of the virtual disk in bytes +# @extents: Where to store the data extents. Required for monolithcFlat, +# twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For +# monolithicFlat, only one entry is required; for +# twoGbMaxExtent* formats, the number of entries required is +# calculated as extent_number = virtual_size / 2GB. Providing +# more extents than will be used is an error. +# @subformat: The subformat of the VMDK image. Default: "monolithicSparse". +# @backing-file: The path of backing file. Default: no backing file is used. +# @adapter-type: The adapter type used to fill in the descriptor. Default: ide. +# @hwversion: Hardware version. The meaningful options are "4" or "6". +# Default: "4". +# @zeroed-grain: Whether to enable zeroed-grain feature for sparse subformats. +# Default: false. # # Since: 4.0 ## @@ -4533,9 +4533,9 @@ ## # @SheepdogRedundancyType: # -# @full Create a fully replicated vdi with x copies -# @erasure-coded Create an erasure coded vdi with x data strips and -# y parity strips +# @full: Create a fully replicated vdi with x copies +# @erasure-coded: Create an erasure coded vdi with x data strips and +# y parity strips # # Since: 2.12 ## @@ -4545,7 +4545,7 @@ ## # @SheepdogRedundancyFull: # -# @copies Number of copies to use (between 1 and 31) +# @copies: Number of copies to use (between 1 and 31) # # Since: 2.12 ## @@ -4555,8 +4555,8 @@ ## # @SheepdogRedundancyErasureCoded: # -# @data-strips Number of data strips to use (one of {2,4,8,16}) -# @parity-strips Number of parity strips to use (between 1 and 15) +# @data-strips: Number of data strips to use (one of {2,4,8,16}) +# @parity-strips: Number of parity strips to use (between 1 and 15) # # Since: 2.12 ## @@ -4580,13 +4580,13 @@ # # Driver specific image creation options for Sheepdog. # -# @location Where to store the new image file -# @size Size of the virtual disk in bytes -# @backing-file File name of a base image -# @preallocation Preallocation mode for the new image (default: off; -# allowed values: off, full) -# @redundancy Redundancy of the image -# @object-size Object size of the image +# @location: Where to store the new image file +# @size: Size of the virtual disk in bytes +# @backing-file: File name of a base image +# @preallocation: Preallocation mode for the new image (default: off; +# allowed values: off, full) +# @redundancy: Redundancy of the image +# @object-size: Object size of the image # # Since: 2.12 ## @@ -4603,8 +4603,8 @@ # # Driver specific image creation options for SSH. # -# @location Where to store the new image file -# @size Size of the virtual disk in bytes +# @location: Where to store the new image file +# @size: Size of the virtual disk in bytes # # Since: 2.12 ## @@ -4617,10 +4617,10 @@ # # Driver specific image creation options for VDI. # -# @file Node to create the image format on -# @size Size of the virtual disk in bytes -# @preallocation Preallocation mode for the new image (default: off; -# allowed values: off, metadata) +# @file: Node to create the image format on +# @size: Size of the virtual disk in bytes +# @preallocation: Preallocation mode for the new image (default: off; +# allowed values: off, metadata) # # Since: 2.12 ## @@ -4645,17 +4645,17 @@ # # Driver specific image creation options for vhdx. # -# @file Node to create the image format on -# @size Size of the virtual disk in bytes -# @log-size Log size in bytes, must be a multiple of 1 MB -# (default: 1 MB) -# @block-size Block size in bytes, must be a multiple of 1 MB and not -# larger than 256 MB (default: automatically choose a block -# size depending on the image size) -# @subformat vhdx subformat (default: dynamic) -# @block-state-zero Force use of payload blocks of type 'ZERO'. Non-standard, -# but default. Do not set to 'off' when using 'qemu-img -# convert' with subformat=dynamic. +# @file: Node to create the image format on +# @size: Size of the virtual disk in bytes +# @log-size: Log size in bytes, must be a multiple of 1 MB +# (default: 1 MB) +# @block-size: Block size in bytes, must be a multiple of 1 MB and not +# larger than 256 MB (default: automatically choose a block +# size depending on the image size) +# @subformat: vhdx subformat (default: dynamic) +# @block-state-zero: Force use of payload blocks of type 'ZERO'. Non-standard, +# but default. Do not set to 'off' when using 'qemu-img +# convert' with subformat=dynamic. # # Since: 2.12 ## @@ -4683,12 +4683,12 @@ # # Driver specific image creation options for vpc (VHD). # -# @file Node to create the image format on -# @size Size of the virtual disk in bytes -# @subformat vhdx subformat (default: dynamic) -# @force-size Force use of the exact byte size instead of rounding to the -# next size that can be represented in CHS geometry -# (default: false) +# @file: Node to create the image format on +# @size: Size of the virtual disk in bytes +# @subformat: vhdx subformat (default: dynamic) +# @force-size: Force use of the exact byte size instead of rounding to the +# next size that can be represented in CHS geometry +# (default: false) # # Since: 2.12 ## @@ -4703,7 +4703,7 @@ # # Options for creating an image format on a given node. # -# @driver block driver to create the image format +# @driver: block driver to create the image format # # Since: 2.12 ## From patchwork Thu Feb 6 17:30:20 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183130 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1849004ile; Thu, 6 Feb 2020 09:49:08 -0800 (PST) X-Google-Smtp-Source: APXvYqx/9tpf8fbiHJfIC5mUrjX22ZPsNAdZwEY2SuTPebdm7uI/oDlE2NEur/mPL6kVmWYSVFpK X-Received: by 2002:ae9:c018:: with SMTP id u24mr3658871qkk.339.1581011348787; Thu, 06 Feb 2020 09:49:08 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581011348; cv=none; d=google.com; s=arc-20160816; b=JRAVgMjZaw1eU2AG7SW2gfnBbvnMuam6GDHjvXPQT7GxzTEh4zIyNocU21nSTtbbwq 9aeItHQBioIYP387hFOBfTx0lM4TxAMpVnfg1A98J5O+AiRaico+WWmPTvo4/7rnn/X8 jZKB0jNMvzl8Wi+TojJNrUSj/hnirZglCKynH34HanAGSx6/d82PZMCH2cN0SFjxMO5O D84WpjPBRGw2BtVDawvbzN9Kbmih9FIuRTXhXGtS+nlMAhCXeUJB2ZVtXRQdDNAirtSq rbshQhU5ifi3vR7udE9SFntg95wNhcAHzHXQ/OvrrzfVFhiEnTRoTdE9vBQC6dhQ1ZAT vswg== 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=xgEZfV10KVwym47ddO9nXG+T95nZ8PI5TI4fV+/G1Nw=; b=jjJUwuGgvEe8b6CoWmChpvaUae2TyKb5b492wBwrR1COntFdBlipfr2xWkC251wxCp Z/TT6o925hubNK0hilSPXfM0qKp1i+H/dqdIT4FckCkenoJJ72DcnPhsRb2YilUMRj9z we08e8rJD935AkowNl+Qk4IzU2cjEUuD7wFyi8wPCPbQRZzEkvueEGfTRkORvn8mOyRQ 2RrKMR/sFf/BSQBDExO4kv04jgIcuzttCG5vgLADHLpt0N7e+OCbW7LuS4VE6SLbEOQ6 /w0W34oWrLcD3zezNRpnIw9xBijOz4BDnxL5MC0moeVSwImEHG2B/VbyS1pZN/6G2W5u zNfw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=QhQ08Gl9; 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 i27si1847416qvb.150.2020.02.06.09.49.08 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:49:08 -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=QhQ08Gl9; 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]:43762 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlH2-0003Bc-49 for patch@linaro.org; Thu, 06 Feb 2020 12:49:08 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43520) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzy-0006lD-SA for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:41 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzl-0005fa-0M for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:28 -0500 Received: from mail-wm1-x343.google.com ([2a00:1450:4864:20::343]:51613) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzi-0005Xq-Op for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:16 -0500 Received: by mail-wm1-x343.google.com with SMTP id t23so900875wmi.1 for ; Thu, 06 Feb 2020 09:31:14 -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=xgEZfV10KVwym47ddO9nXG+T95nZ8PI5TI4fV+/G1Nw=; b=QhQ08Gl9eBHdty9Y97OtJUbyd2ME8WhHB8tno4eB1uQuTGNKmPP4ehncLJnmFA89u3 kR9COy3ffIYd0YfrvLLVjcXlCZITMyNIgnI5wnVTbZRroMA2P6vvu7qu7MYRC4sDB3Ol CcntQtNiM9k2UdRM1Zd+NkV/+ZyanBfyYtGLDpgOgF7FRPTeEC13T4BykvRew/mXrWbY uGfIRku+YxC35CeBGBZpfCV6Yi91S/IPXQg9liGe/JMIk0ocLnzN3eH+JE6JFHzP5CVP ReLMU4q2D36/BnyDw+LIJQKkc4ap2L6k5jOerA6NmnuoOU2V53+ldTeW2FRFXHba6mho JHSg== 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=xgEZfV10KVwym47ddO9nXG+T95nZ8PI5TI4fV+/G1Nw=; b=UlnqaKV45Z6anbHtTutR2pv4JJmean8Xlp1qE5bcOUfjjv5gajtVtFL4b3wIKi2ga9 ijlw0PkOBvPWVqnNlMEboQDMyo3zA2nLy6uN94zwnIzwOnMOXmbIBxHFEaDhWmNrUlsJ xG4WAxXQp14OpFdXuyt1qUtrOo1LpNER9z9UQv/UIg1S9ARNzrFP8fzx2kYR5i5RXJ7Q LJq9MTvJU2Y79yAgf9lqu/i5XObBkR3qrIO8fEAJ1kwyGzCYviJ8XGKmP7cfx4KOzqwo FvSktSRXvwvQiutMa5gU6J8vtfBvFKh8EEyrHLQ2AqB4FF1XeEqtbE8/9bEp8FxE47oA RBYg== X-Gm-Message-State: APjAAAVkW8agkc7z3Hhw1rKbhh09RdGXhjEZFGOvL/9pUJsiXswIIl7o 6t1MY8m2h4EzoguHeSvfjJ2mTMd8VCA= X-Received: by 2002:a1c:df09:: with SMTP id w9mr5387823wmg.143.1581010267982; Thu, 06 Feb 2020 09:31:07 -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.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:06 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 09/29] qapi: Fix indent level on doc comments in json files Date: Thu, 6 Feb 2020 17:30:20 +0000 Message-Id: <20200206173040.17337-10-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::343 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" The texinfo doc generation doesn't care much about indentation levels, but we would like to add a rST backend, and rST does care about indentation. Make the doc comments more strongly consistent about indentation for multiline constructs like: @arg: description line 1 description line 2 Returns: line one line 2 so that there is always exactly one space after the colon, and subsequent lines align with the first. This commit is a purely whitespace change, and it does not alter the generated .texi files (because the texi generation code strips away all the extra whitespace). This does mean that we end up with some over-length lines. Note that when the documentation for an argument fits on a single line like this: @arg: one line only then stray extra spaces after the ':' don't affect the rST output, so I have not attempted to methodically fix them, though the preference is a single space here too. Signed-off-by: Peter Maydell --- qapi/block-core.json | 776 +++++++++++++++++++-------------------- qapi/block.json | 14 +- qapi/char.json | 8 +- qapi/dump.json | 4 +- qapi/introspect.json | 12 +- qapi/job.json | 32 +- qapi/machine-target.json | 18 +- qapi/machine.json | 12 +- qapi/migration.json | 198 +++++----- qapi/misc-target.json | 8 +- qapi/misc.json | 102 ++--- qapi/net.json | 20 +- qapi/qdev.json | 10 +- qapi/qom.json | 4 +- qapi/rocker.json | 12 +- qapi/run-state.json | 34 +- qapi/sockets.json | 8 +- qapi/trace.json | 14 +- qapi/transaction.json | 4 +- qapi/ui.json | 36 +- 20 files changed, 663 insertions(+), 663 deletions(-) -- 2.20.1 diff --git a/qapi/block-core.json b/qapi/block-core.json index 076a4a4808e..006a0bf7a7c 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -162,7 +162,7 @@ # @backing-image: info of the backing image (since 1.6) # # @format-specific: structure supplying additional format-specific -# information (since 1.7) +# information (since 1.7) # # Since: 1.3 # @@ -708,7 +708,7 @@ # Get a list of BlockInfo for all virtual block devices. # # Returns: a list of @BlockInfo describing each virtual block device. Filter -# nodes that were created implicitly are skipped over. +# nodes that were created implicitly are skipped over. # # Since: 0.14.0 # @@ -1352,8 +1352,8 @@ # @existing: QEMU should look for an existing image file. # # @absolute-paths: QEMU should create a new image with absolute paths -# for the backing file. If there is no backing file available, the new -# image will not be backed either. +# for the backing file. If there is no backing file available, the new +# image will not be backed either. # # Since: 1.1 ## @@ -1370,8 +1370,8 @@ # @node-name: graph node name to generate the snapshot from (Since 2.0) # # @snapshot-file: the target of the new overlay image. If the file -# exists, or if it is a device, the overlay will be created in the -# existing file/device. Otherwise, a new file will be created. +# exists, or if it is a device, the overlay will be created in the +# existing file/device. Otherwise, a new file will be created. # # @snapshot-node-name: the graph node name of the new image (Since 2.0) # @@ -1456,8 +1456,8 @@ # a node name is autogenerated. (Since: 4.2) # # Note: @on-source-error and @on-target-error only affect background -# I/O. If an error occurs during a guest write request, the device's -# rerror/werror actions will be used. +# I/O. If an error occurs during a guest write request, the device's +# rerror/werror actions will be used. # # Since: 4.2 ## @@ -1578,13 +1578,13 @@ # to verify "image-node-name" is in the chain # described by "device". # -# @device: The device name or node-name of the root node that owns -# image-node-name. +# @device: The device name or node-name of the root node that owns +# image-node-name. # -# @backing-file: The string to write as the backing file. This -# string is not validated, so care should be taken -# when specifying the string or the image chain may -# not be able to be reopened again. +# @backing-file: The string to write as the backing file. This +# string is not validated, so care should be taken +# when specifying the string or the image chain may +# not be able to be reopened again. # # Returns: Nothing on success # @@ -1605,7 +1605,7 @@ # @job-id: identifier for the newly-created block job. If # omitted, the device name will be used. (Since 2.7) # -# @device: the device name or node-name of a root node +# @device: the device name or node-name of a root node # # @base-node: The node name of the backing image to write data into. # If not specified, this is the deepest backing image. @@ -1625,36 +1625,36 @@ # node; other strings, even if addressing the same file, are not # accepted (deprecated, use @base-node instead) # -# @backing-file: The backing file string to write into the overlay -# image of 'top'. If 'top' is the active layer, -# specifying a backing file string is an error. This -# filename is not validated. +# @backing-file: The backing file string to write into the overlay +# image of 'top'. If 'top' is the active layer, +# specifying a backing file string is an error. This +# filename is not validated. # -# If a pathname string is such that it cannot be -# resolved by QEMU, that means that subsequent QMP or -# HMP commands must use node-names for the image in -# question, as filename lookup methods will fail. +# If a pathname string is such that it cannot be +# resolved by QEMU, that means that subsequent QMP or +# HMP commands must use node-names for the image in +# question, as filename lookup methods will fail. # -# If not specified, QEMU will automatically determine -# the backing file string to use, or error out if -# there is no obvious choice. Care should be taken -# when specifying the string, to specify a valid -# filename or protocol. -# (Since 2.1) +# If not specified, QEMU will automatically determine +# the backing file string to use, or error out if +# there is no obvious choice. Care should be taken +# when specifying the string, to specify a valid +# filename or protocol. +# (Since 2.1) # -# If top == base, that is an error. -# If top == active, the job will not be completed by itself, -# user needs to complete the job with the block-job-complete -# command after getting the ready event. (Since 2.0) +# If top == base, that is an error. +# If top == active, the job will not be completed by itself, +# user needs to complete the job with the block-job-complete +# command after getting the ready event. (Since 2.0) # -# If the base image is smaller than top, then the base image -# will be resized to be the same size as top. If top is -# smaller than the base image, the base will not be -# truncated. If you want the base image size to match the -# size of the smaller top, you can safely truncate it -# yourself once the commit operation successfully completes. +# If the base image is smaller than top, then the base image +# will be resized to be the same size as top. If top is +# smaller than the base image, the base will not be +# truncated. If you want the base image size to match the +# size of the smaller top, you can safely truncate it +# yourself once the commit operation successfully completes. # -# @speed: the maximum speed, in bytes per second +# @speed: the maximum speed, in bytes per second # # @filter-node-name: the node name that should be assigned to the # filter driver that the commit job inserts into the graph @@ -2439,52 +2439,52 @@ # @iops_wr: write I/O operations per second # # @bps_max: total throughput limit during bursts, -# in bytes (Since 1.7) +# in bytes (Since 1.7) # # @bps_rd_max: read throughput limit during bursts, -# in bytes (Since 1.7) +# in bytes (Since 1.7) # # @bps_wr_max: write throughput limit during bursts, -# in bytes (Since 1.7) +# in bytes (Since 1.7) # # @iops_max: total I/O operations per second during bursts, -# in bytes (Since 1.7) +# in bytes (Since 1.7) # # @iops_rd_max: read I/O operations per second during bursts, -# in bytes (Since 1.7) +# in bytes (Since 1.7) # # @iops_wr_max: write I/O operations per second during bursts, -# in bytes (Since 1.7) +# in bytes (Since 1.7) # # @bps_max_length: maximum length of the @bps_max burst -# period, in seconds. It must only -# be set if @bps_max is set as well. -# Defaults to 1. (Since 2.6) +# period, in seconds. It must only +# be set if @bps_max is set as well. +# Defaults to 1. (Since 2.6) # # @bps_rd_max_length: maximum length of the @bps_rd_max -# burst period, in seconds. It must only -# be set if @bps_rd_max is set as well. -# Defaults to 1. (Since 2.6) +# burst period, in seconds. It must only +# be set if @bps_rd_max is set as well. +# Defaults to 1. (Since 2.6) # # @bps_wr_max_length: maximum length of the @bps_wr_max -# burst period, in seconds. It must only -# be set if @bps_wr_max is set as well. -# Defaults to 1. (Since 2.6) +# burst period, in seconds. It must only +# be set if @bps_wr_max is set as well. +# Defaults to 1. (Since 2.6) # # @iops_max_length: maximum length of the @iops burst -# period, in seconds. It must only -# be set if @iops_max is set as well. -# Defaults to 1. (Since 2.6) +# period, in seconds. It must only +# be set if @iops_max is set as well. +# Defaults to 1. (Since 2.6) # # @iops_rd_max_length: maximum length of the @iops_rd_max -# burst period, in seconds. It must only -# be set if @iops_rd_max is set as well. -# Defaults to 1. (Since 2.6) +# burst period, in seconds. It must only +# be set if @iops_rd_max is set as well. +# Defaults to 1. (Since 2.6) # # @iops_wr_max_length: maximum length of the @iops_wr_max -# burst period, in seconds. It must only -# be set if @iops_wr_max is set as well. -# Defaults to 1. (Since 2.6) +# burst period, in seconds. It must only +# be set if @iops_wr_max is set as well. +# Defaults to 1. (Since 2.6) # # @iops_size: an I/O size in bytes (Since 1.7) # @@ -2511,31 +2511,31 @@ # transaction. All fields are optional. When setting limits, if a field is # missing the current value is not changed. # -# @iops-total: limit total I/O operations per second -# @iops-total-max: I/O operations burst -# @iops-total-max-length: length of the iops-total-max burst period, in seconds -# It must only be set if @iops-total-max is set as well. -# @iops-read: limit read operations per second -# @iops-read-max: I/O operations read burst -# @iops-read-max-length: length of the iops-read-max burst period, in seconds -# It must only be set if @iops-read-max is set as well. -# @iops-write: limit write operations per second -# @iops-write-max: I/O operations write burst -# @iops-write-max-length: length of the iops-write-max burst period, in seconds -# It must only be set if @iops-write-max is set as well. -# @bps-total: limit total bytes per second -# @bps-total-max: total bytes burst -# @bps-total-max-length: length of the bps-total-max burst period, in seconds. -# It must only be set if @bps-total-max is set as well. -# @bps-read: limit read bytes per second -# @bps-read-max: total bytes read burst -# @bps-read-max-length: length of the bps-read-max burst period, in seconds -# It must only be set if @bps-read-max is set as well. -# @bps-write: limit write bytes per second -# @bps-write-max: total bytes write burst -# @bps-write-max-length: length of the bps-write-max burst period, in seconds -# It must only be set if @bps-write-max is set as well. -# @iops-size: when limiting by iops max size of an I/O in bytes +# @iops-total: limit total I/O operations per second +# @iops-total-max: I/O operations burst +# @iops-total-max-length: length of the iops-total-max burst period, in seconds +# It must only be set if @iops-total-max is set as well. +# @iops-read: limit read operations per second +# @iops-read-max: I/O operations read burst +# @iops-read-max-length: length of the iops-read-max burst period, in seconds +# It must only be set if @iops-read-max is set as well. +# @iops-write: limit write operations per second +# @iops-write-max: I/O operations write burst +# @iops-write-max-length: length of the iops-write-max burst period, in seconds +# It must only be set if @iops-write-max is set as well. +# @bps-total: limit total bytes per second +# @bps-total-max: total bytes burst +# @bps-total-max-length: length of the bps-total-max burst period, in seconds. +# It must only be set if @bps-total-max is set as well. +# @bps-read: limit read bytes per second +# @bps-read-max: total bytes read burst +# @bps-read-max-length: length of the bps-read-max burst period, in seconds +# It must only be set if @bps-read-max is set as well. +# @bps-write: limit write bytes per second +# @bps-write-max: total bytes write burst +# @bps-write-max-length: length of the bps-write-max burst period, in seconds +# It must only be set if @bps-write-max is set as well. +# @iops-size: when limiting by iops max size of an I/O in bytes # # Since: 2.11 ## @@ -2582,28 +2582,28 @@ # # @device: the device or node name of the top image # -# @base: the common backing file name. -# It cannot be set if @base-node is also set. +# @base: the common backing file name. +# It cannot be set if @base-node is also set. # # @base-node: the node name of the backing file. -# It cannot be set if @base is also set. (Since 2.8) +# It cannot be set if @base is also set. (Since 2.8) # # @backing-file: The backing file string to write into the top -# image. This filename is not validated. +# image. This filename is not validated. # -# If a pathname string is such that it cannot be -# resolved by QEMU, that means that subsequent QMP or -# HMP commands must use node-names for the image in -# question, as filename lookup methods will fail. +# If a pathname string is such that it cannot be +# resolved by QEMU, that means that subsequent QMP or +# HMP commands must use node-names for the image in +# question, as filename lookup methods will fail. # -# If not specified, QEMU will automatically determine -# the backing file string to use, or error out if there -# is no obvious choice. Care should be taken when -# specifying the string, to specify a valid filename or -# protocol. -# (Since 2.1) +# If not specified, QEMU will automatically determine +# the backing file string to use, or error out if there +# is no obvious choice. Care should be taken when +# specifying the string, to specify a valid filename or +# protocol. +# (Since 2.1) # -# @speed: the maximum speed, in bytes per second +# @speed: the maximum speed, in bytes per second # # @on-error: the action to take on an error (default report). # 'stop' and 'enospc' can only be used if the block device @@ -2653,8 +2653,8 @@ # the name of the parameter), but since QEMU 2.7 it can have # other values. # -# @speed: the maximum speed, in bytes per second, or 0 for unlimited. -# Defaults to 0. +# @speed: the maximum speed, in bytes per second, or 0 for unlimited. +# Defaults to 0. # # Returns: Nothing on success # If no background operation is active on this device, DeviceNotActive @@ -2820,8 +2820,8 @@ # # Determines how to handle discard requests. # -# @ignore: Ignore the request -# @unmap: Forward as an unmap request +# @ignore: Ignore the request +# @unmap: Forward as an unmap request # # Since: 2.9 ## @@ -2834,10 +2834,10 @@ # Describes the operation mode for the automatic conversion of plain # zero writes by the OS to driver specific optimized zero write commands. # -# @off: Disabled (default) -# @on: Enabled -# @unmap: Enabled and even try to unmap blocks if possible. This requires -# also that @BlockdevDiscardOptions is set to unmap for this device. +# @off: Disabled (default) +# @on: Enabled +# @unmap: Enabled and even try to unmap blocks if possible. This requires +# also that @BlockdevDiscardOptions is set to unmap for this device. # # Since: 2.1 ## @@ -2849,9 +2849,9 @@ # # Selects the AIO backend to handle I/O requests # -# @threads: Use qemu's thread pool -# @native: Use native AIO backend (only Linux and Windows) -# @io_uring: Use linux io_uring (since 5.0) +# @threads: Use qemu's thread pool +# @native: Use native AIO backend (only Linux and Windows) +# @io_uring: Use linux io_uring (since 5.0) # # Since: 2.9 ## @@ -2864,10 +2864,10 @@ # # Includes cache-related options for block devices # -# @direct: enables use of O_DIRECT (bypass the host page cache; -# default: false) -# @no-flush: ignore any flush requests for the device (default: -# false) +# @direct: enables use of O_DIRECT (bypass the host page cache; +# default: false) +# @no-flush: ignore any flush requests for the device (default: +# false) # # Since: 2.9 ## @@ -2905,18 +2905,18 @@ # # Driver specific block device options for the file backend. # -# @filename: path to the image file -# @pr-manager: the id for the object that will handle persistent reservations -# for this device (default: none, forward the commands via SG_IO; -# since 2.11) -# @aio: AIO backend (default: threads) (since: 2.8) -# @locking: whether to enable file locking. If set to 'auto', only enable -# when Open File Descriptor (OFD) locking API is available -# (default: auto, since 2.10) -# @drop-cache: invalidate page cache during live migration. This prevents -# stale data on the migration destination with cache.direct=off. -# Currently only supported on Linux hosts. -# (default: on, since: 4.0) +# @filename: path to the image file +# @pr-manager: the id for the object that will handle persistent reservations +# for this device (default: none, forward the commands via SG_IO; +# since 2.11) +# @aio: AIO backend (default: threads) (since: 2.8) +# @locking: whether to enable file locking. If set to 'auto', only enable +# when Open File Descriptor (OFD) locking API is available +# (default: auto, since 2.10) +# @drop-cache: invalidate page cache during live migration. This prevents +# stale data on the migration destination with cache.direct=off. +# Currently only supported on Linux hosts. +# (default: on, since: 4.0) # @x-check-cache-dropped: whether to check that page cache was dropped on live # migration. May cause noticeable delays if the image # file is large, do not use in production. @@ -2949,7 +2949,7 @@ # # Driver specific block device options for the null backend. # -# @size: size of the device in bytes. +# @size: size of the device in bytes. # @latency-ns: emulated latency (in nanoseconds) in processing # requests. Default to zero which completes requests immediately. # (Since 2.4) @@ -2966,8 +2966,8 @@ # # Driver specific block device options for the NVMe backend. # -# @device: PCI controller address of the NVMe device in -# format hhhh:bb:ss.f (host:bus:slot.function) +# @device: PCI controller address of the NVMe device in +# format hhhh:bb:ss.f (host:bus:slot.function) # @namespace: namespace number of the device, starting from 1. # # Note that the PCI @device must have been unbound from any host @@ -2983,15 +2983,15 @@ # # Driver specific block device options for the vvfat protocol. # -# @dir: directory to be exported as FAT image -# @fat-type: FAT type: 12, 16 or 32 -# @floppy: whether to export a floppy image (true) or -# partitioned hard disk (false; default) -# @label: set the volume label, limited to 11 bytes. FAT16 and -# FAT32 traditionally have some restrictions on labels, which are -# ignored by most operating systems. Defaults to "QEMU VVFAT". -# (since 2.4) -# @rw: whether to allow write operations (default: false) +# @dir: directory to be exported as FAT image +# @fat-type: FAT type: 12, 16 or 32 +# @floppy: whether to export a floppy image (true) or +# partitioned hard disk (false; default) +# @label: set the volume label, limited to 11 bytes. FAT16 and +# FAT32 traditionally have some restrictions on labels, which are +# ignored by most operating systems. Defaults to "QEMU VVFAT". +# (since 2.4) +# @rw: whether to allow write operations (default: false) # # Since: 2.9 ## @@ -3005,7 +3005,7 @@ # Driver specific block device options for image format that have no option # besides their data source. # -# @file: reference to or definition of the data source block device +# @file: reference to or definition of the data source block device # # Since: 2.9 ## @@ -3034,9 +3034,9 @@ # Driver specific block device options for image format that have no option # besides their data source and an optional backing file. # -# @backing: reference to or definition of the backing file block -# device, null disables the backing file entirely. -# Defaults to the backing file stored the image file. +# @backing: reference to or definition of the backing file block +# device, null disables the backing file entirely. +# Defaults to the backing file stored the image file. # # Since: 2.9 ## @@ -3049,15 +3049,15 @@ # # General overlap check modes. # -# @none: Do not perform any checks +# @none: Do not perform any checks # -# @constant: Perform only checks which can be done in constant time and -# without reading anything from disk +# @constant: Perform only checks which can be done in constant time and +# without reading anything from disk # -# @cached: Perform only checks which can be done without reading anything -# from disk +# @cached: Perform only checks which can be done without reading anything +# from disk # -# @all: Perform all available overlap checks +# @all: Perform all available overlap checks # # Since: 2.9 ## @@ -3096,10 +3096,10 @@ # Specifies which metadata structures should be guarded against unintended # overwriting. # -# @flags: set of flags for separate specification of each metadata structure -# type +# @flags: set of flags for separate specification of each metadata structure +# type # -# @mode: named mode which chooses a specific set of flags +# @mode: named mode which chooses a specific set of flags # # Since: 2.9 ## @@ -3132,9 +3132,9 @@ # # Driver specific block device options for qcow. # -# @encrypt: Image decryption options. Mandatory for -# encrypted images, except when doing a metadata-only -# probe of the image. +# @encrypt: Image decryption options. Mandatory for +# encrypted images, except when doing a metadata-only +# probe of the image. # # Since: 2.10 ## @@ -3169,51 +3169,51 @@ # # Driver specific block device options for qcow2. # -# @lazy-refcounts: whether to enable the lazy refcounts -# feature (default is taken from the image file) +# @lazy-refcounts: whether to enable the lazy refcounts +# feature (default is taken from the image file) # -# @pass-discard-request: whether discard requests to the qcow2 -# device should be forwarded to the data source +# @pass-discard-request: whether discard requests to the qcow2 +# device should be forwarded to the data source # # @pass-discard-snapshot: whether discard requests for the data source # should be issued when a snapshot operation (e.g. # deleting a snapshot) frees clusters in the qcow2 file # -# @pass-discard-other: whether discard requests for the data source -# should be issued on other occasions where a cluster -# gets freed +# @pass-discard-other: whether discard requests for the data source +# should be issued on other occasions where a cluster +# gets freed # -# @overlap-check: which overlap checks to perform for writes -# to the image, defaults to 'cached' (since 2.2) +# @overlap-check: which overlap checks to perform for writes +# to the image, defaults to 'cached' (since 2.2) # -# @cache-size: the maximum total size of the L2 table and -# refcount block caches in bytes (since 2.2) +# @cache-size: the maximum total size of the L2 table and +# refcount block caches in bytes (since 2.2) # -# @l2-cache-size: the maximum size of the L2 table cache in -# bytes (since 2.2) +# @l2-cache-size: the maximum size of the L2 table cache in +# bytes (since 2.2) # -# @l2-cache-entry-size: the size of each entry in the L2 cache in -# bytes. It must be a power of two between 512 -# and the cluster size. The default value is -# the cluster size (since 2.12) +# @l2-cache-entry-size: the size of each entry in the L2 cache in +# bytes. It must be a power of two between 512 +# and the cluster size. The default value is +# the cluster size (since 2.12) # -# @refcount-cache-size: the maximum size of the refcount block cache -# in bytes (since 2.2) +# @refcount-cache-size: the maximum size of the refcount block cache +# in bytes (since 2.2) # -# @cache-clean-interval: clean unused entries in the L2 and refcount -# caches. The interval is in seconds. The default value -# is 600 on supporting platforms, and 0 on other -# platforms. 0 disables this feature. (since 2.5) +# @cache-clean-interval: clean unused entries in the L2 and refcount +# caches. The interval is in seconds. The default value +# is 600 on supporting platforms, and 0 on other +# platforms. 0 disables this feature. (since 2.5) # -# @encrypt: Image decryption options. Mandatory for -# encrypted images, except when doing a metadata-only -# probe of the image. (since 2.10) +# @encrypt: Image decryption options. Mandatory for +# encrypted images, except when doing a metadata-only +# probe of the image. (since 2.10) # -# @data-file: reference to or definition of the external data file. -# This may only be specified for images that require an -# external data file. If it is not specified for such -# an image, the data file name is loaded from the image -# file. (since 4.0) +# @data-file: reference to or definition of the external data file. +# This may only be specified for images that require an +# external data file. If it is not specified for such +# an image, the data file name is loaded from the image +# file. (since 4.0) # # Since: 2.9 ## @@ -3304,8 +3304,8 @@ # # Trigger events supported by blkdebug. # -# @l1_shrink_write_table: write zeros to the l1 table to shrink image. -# (since 2.11) +# @l1_shrink_write_table: write zeros to the l1 table to shrink image. +# (since 2.11) # # @l1_shrink_free_l2_clusters: discard the l2 tables. (since 2.11) # @@ -3363,25 +3363,25 @@ # # Describes a single error injection for blkdebug. # -# @event: trigger event +# @event: trigger event # -# @state: the state identifier blkdebug needs to be in to -# actually trigger the event; defaults to "any" +# @state: the state identifier blkdebug needs to be in to +# actually trigger the event; defaults to "any" # -# @iotype: the type of I/O operations on which this error should -# be injected; defaults to "all read, write, -# write-zeroes, discard, and flush operations" -# (since: 4.1) +# @iotype: the type of I/O operations on which this error should +# be injected; defaults to "all read, write, +# write-zeroes, discard, and flush operations" +# (since: 4.1) # -# @errno: error identifier (errno) to be returned; defaults to -# EIO +# @errno: error identifier (errno) to be returned; defaults to +# EIO # -# @sector: specifies the sector index which has to be affected -# in order to actually trigger the event; defaults to "any -# sector" +# @sector: specifies the sector index which has to be affected +# in order to actually trigger the event; defaults to "any +# sector" # -# @once: disables further events after this one has been -# triggered; defaults to false +# @once: disables further events after this one has been +# triggered; defaults to false # # @immediately: fail immediately; defaults to false # @@ -3401,13 +3401,13 @@ # # Describes a single state-change event for blkdebug. # -# @event: trigger event +# @event: trigger event # -# @state: the current state identifier blkdebug needs to be in; -# defaults to "any" +# @state: the current state identifier blkdebug needs to be in; +# defaults to "any" # -# @new_state: the state identifier blkdebug is supposed to assume if -# this event is triggered +# @new_state: the state identifier blkdebug is supposed to assume if +# this event is triggered # # Since: 2.9 ## @@ -3421,41 +3421,41 @@ # # Driver specific block device options for blkdebug. # -# @image: underlying raw block device (or image file) +# @image: underlying raw block device (or image file) # -# @config: filename of the configuration file +# @config: filename of the configuration file # -# @align: required alignment for requests in bytes, must be -# positive power of 2, or 0 for default +# @align: required alignment for requests in bytes, must be +# positive power of 2, or 0 for default # -# @max-transfer: maximum size for I/O transfers in bytes, must be -# positive multiple of @align and of the underlying -# file's request alignment (but need not be a power of -# 2), or 0 for default (since 2.10) +# @max-transfer: maximum size for I/O transfers in bytes, must be +# positive multiple of @align and of the underlying +# file's request alignment (but need not be a power of +# 2), or 0 for default (since 2.10) # -# @opt-write-zero: preferred alignment for write zero requests in bytes, -# must be positive multiple of @align and of the -# underlying file's request alignment (but need not be a -# power of 2), or 0 for default (since 2.10) +# @opt-write-zero: preferred alignment for write zero requests in bytes, +# must be positive multiple of @align and of the +# underlying file's request alignment (but need not be a +# power of 2), or 0 for default (since 2.10) # -# @max-write-zero: maximum size for write zero requests in bytes, must be -# positive multiple of @align, of @opt-write-zero, and of -# the underlying file's request alignment (but need not -# be a power of 2), or 0 for default (since 2.10) +# @max-write-zero: maximum size for write zero requests in bytes, must be +# positive multiple of @align, of @opt-write-zero, and of +# the underlying file's request alignment (but need not +# be a power of 2), or 0 for default (since 2.10) # -# @opt-discard: preferred alignment for discard requests in bytes, must -# be positive multiple of @align and of the underlying -# file's request alignment (but need not be a power of -# 2), or 0 for default (since 2.10) +# @opt-discard: preferred alignment for discard requests in bytes, must +# be positive multiple of @align and of the underlying +# file's request alignment (but need not be a power of +# 2), or 0 for default (since 2.10) # -# @max-discard: maximum size for discard requests in bytes, must be -# positive multiple of @align, of @opt-discard, and of -# the underlying file's request alignment (but need not -# be a power of 2), or 0 for default (since 2.10) +# @max-discard: maximum size for discard requests in bytes, must be +# positive multiple of @align, of @opt-discard, and of +# the underlying file's request alignment (but need not +# be a power of 2), or 0 for default (since 2.10) # -# @inject-error: array of error injection descriptions +# @inject-error: array of error injection descriptions # -# @set-state: array of state-change descriptions +# @set-state: array of state-change descriptions # # @take-child-perms: Permissions to take on @image in addition to what # is necessary anyway (which depends on how the @@ -3485,14 +3485,14 @@ # # Driver specific block device options for blklogwrites. # -# @file: block device +# @file: block device # -# @log: block device used to log writes to @file +# @log: block device used to log writes to @file # # @log-sector-size: sector size used in logging writes to @file, determines # granularity of offsets and sizes of writes (default: 512) # -# @log-append: append to an existing log (default: false) +# @log-append: append to an existing log (default: false) # # @log-super-update-interval: interval of write requests after which the log # super block is updated to disk (default: 4096) @@ -3511,9 +3511,9 @@ # # Driver specific block device options for blkverify. # -# @test: block device to be tested +# @test: block device to be tested # -# @raw: raw image used for verification +# @raw: raw image used for verification # # Since: 2.9 ## @@ -3526,7 +3526,7 @@ # # Driver specific block device options for blkreplay. # -# @image: disk image which should be controlled with blkreplay +# @image: disk image which should be controlled with blkreplay # # Since: 4.2 ## @@ -3551,10 +3551,10 @@ # # Driver specific block device options for Quorum # -# @blkverify: true if the driver must print content mismatch +# @blkverify: true if the driver must print content mismatch # set to false by default # -# @children: the children block devices to use +# @children: the children block devices to use # # @vote-threshold: the vote limit under which a read will fail # @@ -3578,16 +3578,16 @@ # # Driver specific block device options for Gluster # -# @volume: name of gluster volume where VM image resides +# @volume: name of gluster volume where VM image resides # -# @path: absolute path to image file in gluster volume +# @path: absolute path to image file in gluster volume # -# @server: gluster servers description +# @server: gluster servers description # -# @debug: libgfapi log level (default '4' which is Error) -# (Since 2.8) +# @debug: libgfapi log level (default '4' which is Error) +# (Since 2.8) # -# @logfile: libgfapi log file (default /dev/stderr) (Since 2.8) +# @logfile: libgfapi log file (default /dev/stderr) (Since 2.8) # # Since: 2.9 ## @@ -3622,30 +3622,30 @@ ## # @BlockdevOptionsIscsi: # -# @transport: The iscsi transport type +# @transport: The iscsi transport type # -# @portal: The address of the iscsi portal +# @portal: The address of the iscsi portal # -# @target: The target iqn name +# @target: The target iqn name # -# @lun: LUN to connect to. Defaults to 0. +# @lun: LUN to connect to. Defaults to 0. # -# @user: User name to log in with. If omitted, no CHAP -# authentication is performed. +# @user: User name to log in with. If omitted, no CHAP +# authentication is performed. # # @password-secret: The ID of a QCryptoSecret object providing # the password for the login. This option is required if # @user is specified. # -# @initiator-name: The iqn name we want to identify to the target -# as. If this option is not specified, an initiator name is -# generated automatically. +# @initiator-name: The iqn name we want to identify to the target +# as. If this option is not specified, an initiator name is +# generated automatically. # -# @header-digest: The desired header digest. Defaults to -# none-crc32c. +# @header-digest: The desired header digest. Defaults to +# none-crc32c. # -# @timeout: Timeout in seconds after which a request will -# timeout. 0 means no timeout and is the default. +# @timeout: Timeout in seconds after which a request will +# timeout. 0 means no timeout and is the default. # # Driver specific block device options for iscsi # @@ -3674,29 +3674,29 @@ ## # @BlockdevOptionsRbd: # -# @pool: Ceph pool name. +# @pool: Ceph pool name. # -# @image: Image name in the Ceph pool. +# @image: Image name in the Ceph pool. # -# @conf: path to Ceph configuration file. Values -# in the configuration file will be overridden by -# options specified via QAPI. +# @conf: path to Ceph configuration file. Values +# in the configuration file will be overridden by +# options specified via QAPI. # -# @snapshot: Ceph snapshot name. +# @snapshot: Ceph snapshot name. # -# @user: Ceph id name. +# @user: Ceph id name. # # @auth-client-required: Acceptable authentication modes. -# This maps to Ceph configuration option -# "auth_client_required". (Since 3.0) +# This maps to Ceph configuration option +# "auth_client_required". (Since 3.0) # -# @key-secret: ID of a QCryptoSecret object providing a key -# for cephx authentication. -# This maps to Ceph configuration option -# "key". (Since 3.0) +# @key-secret: ID of a QCryptoSecret object providing a key +# for cephx authentication. +# This maps to Ceph configuration option +# "key". (Since 3.0) # -# @server: Monitor host address and port. This maps -# to the "mon_host" Ceph option. +# @server: Monitor host address and port. This maps +# to the "mon_host" Ceph option. # # Since: 2.9 ## @@ -3715,10 +3715,10 @@ # # Driver specific block device options for sheepdog # -# @vdi: Virtual disk image name -# @server: The Sheepdog server to connect to -# @snap-id: Snapshot ID -# @tag: Snapshot tag name +# @vdi: Virtual disk image name +# @server: The Sheepdog server to connect to +# @snap-id: Snapshot ID +# @tag: Snapshot tag name # # Only one of @snap-id and @tag may be present. # @@ -3768,7 +3768,7 @@ # # An enumeration of NFS transport types # -# @inet: TCP transport +# @inet: TCP transport # # Since: 2.9 ## @@ -3780,9 +3780,9 @@ # # Captures the address of the socket # -# @type: transport type used for NFS (only TCP supported) +# @type: transport type used for NFS (only TCP supported) # -# @host: host address for NFS server +# @host: host address for NFS server # # Since: 2.9 ## @@ -3795,29 +3795,29 @@ # # Driver specific block device option for NFS # -# @server: host address +# @server: host address # -# @path: path of the image on the host +# @path: path of the image on the host # -# @user: UID value to use when talking to the -# server (defaults to 65534 on Windows and getuid() -# on unix) +# @user: UID value to use when talking to the +# server (defaults to 65534 on Windows and getuid() +# on unix) # -# @group: GID value to use when talking to the -# server (defaults to 65534 on Windows and getgid() -# in unix) +# @group: GID value to use when talking to the +# server (defaults to 65534 on Windows and getgid() +# in unix) # -# @tcp-syn-count: number of SYNs during the session -# establishment (defaults to libnfs default) +# @tcp-syn-count: number of SYNs during the session +# establishment (defaults to libnfs default) # -# @readahead-size: set the readahead size in bytes (defaults -# to libnfs default) +# @readahead-size: set the readahead size in bytes (defaults +# to libnfs default) # -# @page-cache-size: set the pagecache size in bytes (defaults -# to libnfs default) +# @page-cache-size: set the pagecache size in bytes (defaults +# to libnfs default) # -# @debug: set the NFS debug level (max 2) (defaults -# to libnfs default) +# @debug: set the NFS debug level (max 2) (defaults +# to libnfs default) # # Since: 2.9 ## @@ -3837,22 +3837,22 @@ # Driver specific block device options shared by all protocols supported by the # curl backend. # -# @url: URL of the image file +# @url: URL of the image file # -# @readahead: Size of the read-ahead cache; must be a multiple of -# 512 (defaults to 256 kB) +# @readahead: Size of the read-ahead cache; must be a multiple of +# 512 (defaults to 256 kB) # -# @timeout: Timeout for connections, in seconds (defaults to 5) +# @timeout: Timeout for connections, in seconds (defaults to 5) # -# @username: Username for authentication (defaults to none) +# @username: Username for authentication (defaults to none) # -# @password-secret: ID of a QCryptoSecret object providing a password -# for authentication (defaults to no password) +# @password-secret: ID of a QCryptoSecret object providing a password +# for authentication (defaults to no password) # -# @proxy-username: Username for proxy authentication (defaults to none) +# @proxy-username: Username for proxy authentication (defaults to none) # -# @proxy-password-secret: ID of a QCryptoSecret object providing a password -# for proxy authentication (defaults to no password) +# @proxy-password-secret: ID of a QCryptoSecret object providing a password +# for proxy authentication (defaults to no password) # # Since: 2.9 ## @@ -3871,9 +3871,9 @@ # Driver specific block device options for HTTP connections over the curl # backend. URLs must start with "http://". # -# @cookie: List of cookies to set; format is -# "name1=content1; name2=content2;" as explained by -# CURLOPT_COOKIE(3). Defaults to no cookies. +# @cookie: List of cookies to set; format is +# "name1=content1; name2=content2;" as explained by +# CURLOPT_COOKIE(3). Defaults to no cookies. # # @cookie-secret: ID of a QCryptoSecret object providing the cookie data in a # secure way. See @cookie for the format. (since 2.10) @@ -3891,12 +3891,12 @@ # Driver specific block device options for HTTPS connections over the curl # backend. URLs must start with "https://". # -# @cookie: List of cookies to set; format is -# "name1=content1; name2=content2;" as explained by -# CURLOPT_COOKIE(3). Defaults to no cookies. +# @cookie: List of cookies to set; format is +# "name1=content1; name2=content2;" as explained by +# CURLOPT_COOKIE(3). Defaults to no cookies. # -# @sslverify: Whether to verify the SSL certificate's validity (defaults to -# true) +# @sslverify: Whether to verify the SSL certificate's validity (defaults to +# true) # # @cookie-secret: ID of a QCryptoSecret object providing the cookie data in a # secure way. See @cookie for the format. (since 2.10) @@ -3927,8 +3927,8 @@ # Driver specific block device options for FTPS connections over the curl # backend. URLs must start with "ftps://". # -# @sslverify: Whether to verify the SSL certificate's validity (defaults to -# true) +# @sslverify: Whether to verify the SSL certificate's validity (defaults to +# true) # # Since: 2.9 ## @@ -3941,11 +3941,11 @@ # # Driver specific block device options for NBD. # -# @server: NBD server address +# @server: NBD server address # -# @export: export name +# @export: export name # -# @tls-creds: TLS credentials ID +# @tls-creds: TLS credentials ID # # @x-dirty-bitmap: A "qemu:dirty-bitmap:NAME" string to query in place of # traditional "base:allocation" block status (see @@ -3973,8 +3973,8 @@ # # Driver specific block device options for the raw driver. # -# @offset: position where the block device starts -# @size: the assumed size of the device +# @offset: position where the block device starts +# @size: the assumed size of the device # # Since: 2.9 ## @@ -3987,9 +3987,9 @@ # # Driver specific block device options for VxHS # -# @vdisk-id: UUID of VxHS volume -# @server: vxhs server IP, port -# @tls-creds: TLS credentials ID +# @vdisk-id: UUID of VxHS volume +# @server: vxhs server IP, port +# @tls-creds: TLS credentials ID # # Since: 2.10 ## @@ -4003,9 +4003,9 @@ # # Driver specific block device options for the throttle driver # -# @throttle-group: the name of the throttle-group object to use. It -# must already exist. -# @file: reference to or definition of the data source block device +# @throttle-group: the name of the throttle-group object to use. It +# must already exist. +# @file: reference to or definition of the data source block device # Since: 2.11 ## { 'struct': 'BlockdevOptionsThrottle', @@ -4018,19 +4018,19 @@ # Options for creating a block device. Many options are available for all # block devices, independent of the block driver: # -# @driver: block driver name -# @node-name: the node name of the new node (Since 2.0). -# This option is required on the top level of blockdev-add. -# Valid node names start with an alphabetic character and may -# contain only alphanumeric characters, '-', '.' and '_'. Their -# maximum length is 31 characters. -# @discard: discard-related options (default: ignore) -# @cache: cache-related options -# @read-only: whether the block device should be read-only (default: false). -# Note that some block drivers support only read-only access, -# either generally or in certain configurations. In this case, -# the default value does not work and the option must be -# specified explicitly. +# @driver: block driver name +# @node-name: the node name of the new node (Since 2.0). +# This option is required on the top level of blockdev-add. +# Valid node names start with an alphabetic character and may +# contain only alphanumeric characters, '-', '.' and '_'. Their +# maximum length is 31 characters. +# @discard: discard-related options (default: ignore) +# @cache: cache-related options +# @read-only: whether the block device should be read-only (default: false). +# Note that some block drivers support only read-only access, +# either generally or in certain configurations. In this case, +# the default value does not work and the option must be +# specified explicitly. # @auto-read-only: if true and @read-only is false, QEMU may automatically # decide not to open the image read-write as requested, but # fall back to read-only instead (and switch between the modes @@ -4039,8 +4039,8 @@ # (default: false, since 3.1) # @detect-zeroes: detect and optimize zero writes (Since 2.1) # (default: off) -# @force-share: force share all permission on added nodes. -# Requires read-only=true. (Since 2.10) +# @force-share: force share all permission on added nodes. +# Requires read-only=true. (Since 2.10) # # Remaining options are determined by the block driver. # @@ -4106,8 +4106,8 @@ # # Reference to a block device. # -# @definition: defines a new block device inline -# @reference: references the ID of an existing block device +# @definition: defines a new block device inline +# @reference: references the ID of an existing block device # # Since: 2.9 ## @@ -4120,11 +4120,11 @@ # # Reference to a block device. # -# @definition: defines a new block device inline -# @reference: references the ID of an existing block device. -# An empty string means that no block device should -# be referenced. Deprecated; use null instead. -# @null: No block device should be referenced (since 2.10) +# @definition: defines a new block device inline +# @reference: references the ID of an existing block device. +# An empty string means that no block device should +# be referenced. Deprecated; use null instead. +# @null: No block device should be referenced (since 2.10) # # Since: 2.9 ## @@ -4765,12 +4765,12 @@ # # @device: Block device name (deprecated, use @id instead) # -# @id: The name or QOM path of the guest device (since: 2.8) +# @id: The name or QOM path of the guest device (since: 2.8) # -# @force: if false (the default), an eject request will be sent to -# the guest if it has locked the tray (and the tray will not be opened -# immediately); if true, the tray will be opened regardless of whether -# it is locked +# @force: if false (the default), an eject request will be sent to +# the guest if it has locked the tray (and the tray will not be opened +# immediately); if true, the tray will be opened regardless of whether +# it is locked # # Since: 2.5 # @@ -4803,9 +4803,9 @@ # # If the tray was already closed before, this will be a no-op. # -# @device: Block device name (deprecated, use @id instead) +# @device: Block device name (deprecated, use @id instead) # -# @id: The name or QOM path of the guest device (since: 2.8) +# @id: The name or QOM path of the guest device (since: 2.8) # # Since: 2.5 # @@ -4837,7 +4837,7 @@ # # If the tray is open and there is no medium inserted, this will be a no-op. # -# @id: The name or QOM path of the guest device +# @id: The name or QOM path of the guest device # # Since: 2.12 # @@ -4877,7 +4877,7 @@ # device's tray must currently be open (unless there is no attached guest # device) and there must be no medium inserted already. # -# @id: The name or QOM path of the guest device +# @id: The name or QOM path of the guest device # # @node-name: name of a node in the block driver state graph # @@ -4911,11 +4911,11 @@ # Specifies the new read-only mode of a block device subject to the # @blockdev-change-medium command. # -# @retain: Retains the current read-only mode +# @retain: Retains the current read-only mode # -# @read-only: Makes the device read-only +# @read-only: Makes the device read-only # -# @read-write: Makes the device writable +# @read-write: Makes the device writable # # Since: 2.3 # @@ -4932,18 +4932,18 @@ # combines blockdev-open-tray, blockdev-remove-medium, blockdev-insert-medium # and blockdev-close-tray). # -# @device: Block device name (deprecated, use @id instead) +# @device: Block device name (deprecated, use @id instead) # -# @id: The name or QOM path of the guest device -# (since: 2.8) +# @id: The name or QOM path of the guest device +# (since: 2.8) # -# @filename: filename of the new image to be loaded +# @filename: filename of the new image to be loaded # -# @format: format to open the new image with (defaults to -# the probed format) +# @format: format to open the new image with (defaults to +# the probed format) # -# @read-only-mode: change the read-only mode of the device; defaults -# to 'retain' +# @read-only-mode: change the read-only mode of the device; defaults +# to 'retain' # # Since: 2.5 # @@ -5028,8 +5028,8 @@ # the access size # # @fatal: if set, the image is marked corrupt and therefore unusable after this -# event and must be repaired (Since 2.2; before, every -# BLOCK_IMAGE_CORRUPTED event was fatal) +# event and must be repaired (Since 2.2; before, every +# BLOCK_IMAGE_CORRUPTED event was fatal) # # Note: If action is "stop", a STOP event will eventually follow the # BLOCK_IO_ERROR event. @@ -5077,10 +5077,10 @@ # # @reason: human readable string describing the error cause. # (This field is a debugging aid for humans, it should not -# be parsed by applications) (since: 2.2) +# be parsed by applications) (since: 2.2) # # Note: If action is "stop", a STOP event will eventually follow the -# BLOCK_IO_ERROR event +# BLOCK_IO_ERROR event # # Since: 0.13.0 # @@ -5222,7 +5222,7 @@ # @speed: rate limit, bytes per second # # Note: The "ready to complete" status is always reset by a @BLOCK_JOB_ERROR -# event +# event # # Since: 1.3 # @@ -5356,15 +5356,15 @@ # @node: the name of the node that will be added. # # Note: this command is experimental, and its API is not stable. It -# does not support all kinds of operations, all kinds of children, nor -# all block drivers. +# does not support all kinds of operations, all kinds of children, nor +# all block drivers. # -# FIXME Removing children from a quorum node means introducing gaps in the -# child indices. This cannot be represented in the 'children' list of -# BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename(). +# FIXME Removing children from a quorum node means introducing gaps in the +# child indices. This cannot be represented in the 'children' list of +# BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename(). # -# Warning: The data in a new quorum child MUST be consistent with that of -# the rest of the array. +# Warning: The data in a new quorum child MUST be consistent with that of +# the rest of the array. # # Since: 2.7 # @@ -5411,7 +5411,7 @@ # is already attached # # Note: this command is experimental and intended for test cases that need -# control over IOThreads only. +# control over IOThreads only. # # Since: 2.12 # diff --git a/qapi/block.json b/qapi/block.json index 145c268bb64..905297bab2e 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -190,12 +190,12 @@ # # Ejects a device from a removable drive. # -# @device: Block device name (deprecated, use @id instead) +# @device: Block device name (deprecated, use @id instead) # -# @id: The name or QOM path of the guest device (since: 2.8) +# @id: The name or QOM path of the guest device (since: 2.8) # -# @force: If true, eject regardless of whether the drive is locked. -# If not specified, the default value is false. +# @force: If true, eject regardless of whether the drive is locked. +# If not specified, the default value is false. # # Returns: Nothing on success # @@ -251,7 +251,7 @@ # export name. (Since 2.12) # # @writable: Whether clients should be able to write to the device via the -# NBD connection (default false). +# NBD connection (default false). # @bitmap: Also export the dirty bitmap reachable from @device, so the # NBD client can use NBD_OPT_SET_META_CONTEXT with @@ -278,10 +278,10 @@ # Potential additional modes to be added in the future: # # hide: Just hide export from new clients, leave existing connections as is. -# Remove export after all clients are disconnected. +# Remove export after all clients are disconnected. # # soft: Hide export from new clients, answer with ESHUTDOWN for all further -# requests from existing clients. +# requests from existing clients. # # Since: 2.12 ## diff --git a/qapi/char.json b/qapi/char.json index a6e81ac7bc6..8a9f1e75097 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -262,11 +262,11 @@ # @tn3270: enable tn3270 protocol on server # sockets (default: false) (Since: 2.10) # @websocket: enable websocket protocol on server -# sockets (default: false) (Since: 3.1) +# sockets (default: false) (Since: 3.1) # @reconnect: For a client socket, if a socket is disconnected, -# then attempt a reconnect after the given number of seconds. -# Setting this to zero disables this function. (default: 0) -# (Since: 2.2) +# then attempt a reconnect after the given number of seconds. +# Setting this to zero disables this function. (default: 0) +# (Since: 2.2) # # Since: 1.4 ## diff --git a/qapi/dump.json b/qapi/dump.json index 2b35409a7b2..a1eed7b15c5 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -38,8 +38,8 @@ # using gdb to process the core file. # # IMPORTANT: this option can make QEMU allocate several gigabytes -# of RAM. This can happen for a large guest, or a -# malicious guest pretending to be large. +# of RAM. This can happen for a large guest, or a +# malicious guest pretending to be large. # # Also, paging=true has the following limitations: # diff --git a/qapi/introspect.json b/qapi/introspect.json index 031a954fa9a..8756e7920e1 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -34,15 +34,15 @@ # alternate that includes the original type alongside something else. # # Returns: array of @SchemaInfo, where each element describes an -# entity in the ABI: command, event, type, ... +# entity in the ABI: command, event, type, ... # -# The order of the various SchemaInfo is unspecified; however, all -# names are guaranteed to be unique (no name will be duplicated with -# different meta-types). +# The order of the various SchemaInfo is unspecified; however, all +# names are guaranteed to be unique (no name will be duplicated with +# different meta-types). # # Note: the QAPI schema is also used to help define *internal* -# interfaces, by defining QAPI types. These are not part of the QMP -# wire ABI, and therefore not returned by this command. +# interfaces, by defining QAPI types. These are not part of the QMP +# wire ABI, and therefore not returned by this command. # # Since: 2.5 ## diff --git a/qapi/job.json b/qapi/job.json index a121b615fb0..5e658281f5c 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -214,28 +214,28 @@ # # Information about a job. # -# @id: The job identifier +# @id: The job identifier # -# @type: The kind of job that is being performed +# @type: The kind of job that is being performed # -# @status: Current job state/status +# @status: Current job state/status # -# @current-progress: Progress made until now. The unit is arbitrary and the -# value can only meaningfully be used for the ratio of -# @current-progress to @total-progress. The value is -# monotonically increasing. +# @current-progress: Progress made until now. The unit is arbitrary and the +# value can only meaningfully be used for the ratio of +# @current-progress to @total-progress. The value is +# monotonically increasing. # -# @total-progress: Estimated @current-progress value at the completion of -# the job. This value can arbitrarily change while the -# job is running, in both directions. +# @total-progress: Estimated @current-progress value at the completion of +# the job. This value can arbitrarily change while the +# job is running, in both directions. # -# @error: If this field is present, the job failed; if it is -# still missing in the CONCLUDED state, this indicates -# successful completion. +# @error: If this field is present, the job failed; if it is +# still missing in the CONCLUDED state, this indicates +# successful completion. # -# The value is a human-readable error message to describe -# the reason for the job failure. It should not be parsed -# by applications. +# The value is a human-readable error message to describe +# the reason for the job failure. It should not be parsed +# by applications. # # Since: 3.0 ## diff --git a/qapi/machine-target.json b/qapi/machine-target.json index 04623224720..f2c82949d80 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -40,13 +40,13 @@ # model details. # # Note: When a non-migration-safe CPU model is expanded in static mode, some -# features enabled by the CPU model may be omitted, because they can't be -# implemented by a static CPU model definition (e.g. cache info passthrough and -# PMU passthrough in x86). If you need an accurate representation of the -# features enabled by a non-migration-safe CPU model, use @full. If you need a -# static representation that will keep ABI compatibility even when changing QEMU -# version or machine-type, use @static (but keep in mind that some features may -# be omitted). +# features enabled by the CPU model may be omitted, because they can't be +# implemented by a static CPU model definition (e.g. cache info passthrough and +# PMU passthrough in x86). If you need an accurate representation of the +# features enabled by a non-migration-safe CPU model, use @full. If you need a +# static representation that will keep ABI compatibility even when changing QEMU +# version or machine-type, use @static (but keep in mind that some features may +# be omitted). # # Since: 2.8.0 ## @@ -148,7 +148,7 @@ # with wrong types. # # Note: this command isn't specific to s390x, but is only implemented -# on this architecture currently. +# on this architecture currently. # # Since: 2.8.0 ## @@ -191,7 +191,7 @@ # with wrong types. # # Note: this command isn't specific to s390x, but is only implemented -# on this architecture currently. +# on this architecture currently. # # Since: 2.8.0 ## diff --git a/qapi/machine.json b/qapi/machine.json index b3d30bc8162..704b2b0fe31 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -680,7 +680,7 @@ # 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. # # @none: None (no memory side cache in this proximity domain, -# or cache write policy unknown) +# or cache write policy unknown) # # @write-back: Write Back (WB) # @@ -706,7 +706,7 @@ # @level: the cache level described in this structure. # # @associativity: the cache associativity, -# none/direct-mapped/complex(complex cache indexing). +# none/direct-mapped/complex(complex cache indexing). # # @policy: the write policy, none/write-back/write-through. # @@ -823,10 +823,10 @@ # @core-id: core number within die the CPU belongs to# @thread-id: thread number within core the CPU belongs to # # Note: currently there are 5 properties that could be present -# but management should be prepared to pass through other -# properties with device_add command to allow for future -# interface extension. This also requires the filed names to be kept in -# sync with the properties passed to -device/device_add. +# but management should be prepared to pass through other +# properties with device_add command to allow for future +# interface extension. This also requires the filed names to be kept in +# sync with the properties passed to -device/device_add. # # Since: 2.7 ## diff --git a/qapi/migration.json b/qapi/migration.json index b7348d0c8bf..aa160e9e42d 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -28,22 +28,22 @@ # @normal-bytes: number of normal bytes sent (since 1.2) # # @dirty-pages-rate: number of pages dirtied by second by the -# guest (since 1.3) +# guest (since 1.3) # # @mbps: throughput in megabits/sec. (since 1.6) # # @dirty-sync-count: number of times that dirty ram was synchronized (since 2.1) # # @postcopy-requests: The number of page requests received from the destination -# (since 2.7) +# (since 2.7) # # @page-size: The number of bytes per page for the various page-based -# statistics (since 2.10) +# statistics (since 2.10) # # @multifd-bytes: The number of bytes sent through multifd (since 3.0) # # @pages-per-second: the number of memory pages transferred per second -# (Since 4.0) +# (Since 4.0) # # Since: 0.14.0 ## @@ -131,7 +131,7 @@ # @pre-switchover: Paused before device serialisation. (since 2.11) # # @device: During device serialisation when pause-before-switchover is enabled -# (since 2.11) +# (since 2.11) # # @wait-unplug: wait for device unplug request by guest OS to be completed. # (since 4.2) @@ -167,41 +167,41 @@ # status is 'active' or 'completed' (since 1.2) # # @total-time: total amount of milliseconds since migration started. -# If migration has ended, it returns the total migration -# time. (since 1.2) +# If migration has ended, it returns the total migration +# time. (since 1.2) # # @downtime: only present when migration finishes correctly -# total downtime in milliseconds for the guest. -# (since 1.3) +# total downtime in milliseconds for the guest. +# (since 1.3) # # @expected-downtime: only present while migration is active -# expected downtime in milliseconds for the guest in last walk -# of the dirty bitmap. (since 1.3) +# expected downtime in milliseconds for the guest in last walk +# of the dirty bitmap. (since 1.3) # # @setup-time: amount of setup time in milliseconds _before_ the -# iterations begin but _after_ the QMP command is issued. This is designed -# to provide an accounting of any activities (such as RDMA pinning) which -# may be expensive, but do not actually occur during the iterative -# migration rounds themselves. (since 1.6) +# iterations begin but _after_ the QMP command is issued. This is designed +# to provide an accounting of any activities (such as RDMA pinning) which +# may be expensive, but do not actually occur during the iterative +# migration rounds themselves. (since 1.6) # # @cpu-throttle-percentage: percentage of time guest cpus are being -# throttled during auto-converge. This is only present when auto-converge -# has started throttling guest cpus. (Since 2.7) +# throttled during auto-converge. This is only present when auto-converge +# has started throttling guest cpus. (Since 2.7) # # @error-desc: the human readable error description string, when # @status is 'failed'. Clients should not attempt to parse the # error strings. (Since 2.7) # # @postcopy-blocktime: total time when all vCPU were blocked during postcopy -# live migration. This is only present when the postcopy-blocktime -# migration capability is enabled. (Since 3.0) +# live migration. This is only present when the postcopy-blocktime +# migration capability is enabled. (Since 3.0) # # @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is -# only present when the postcopy-blocktime migration capability -# is enabled. (Since 3.0) +# only present when the postcopy-blocktime migration capability +# is enabled. (Since 3.0) # # @compression: migration compression statistics, only returned if compression -# feature is on and status is 'active' or 'completed' (Since 3.1) +# feature is on and status is 'active' or 'completed' (Since 3.1) # # @socket-address: Only used for tcp, to know what the real port is (Since 4.0) # @@ -355,54 +355,54 @@ # loads, by sending compressed difference of the pages # # @rdma-pin-all: Controls whether or not the entire VM memory footprint is -# mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage. -# Disabled by default. (since 2.0) +# mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage. +# Disabled by default. (since 2.0) # # @zero-blocks: During storage migration encode blocks of zeroes efficiently. This -# essentially saves 1MB of zeroes per block on the wire. Enabling requires -# source and target VM to support this feature. To enable it is sufficient -# to enable the capability on the source VM. The feature is disabled by -# default. (since 1.6) +# essentially saves 1MB of zeroes per block on the wire. Enabling requires +# source and target VM to support this feature. To enable it is sufficient +# to enable the capability on the source VM. The feature is disabled by +# default. (since 1.6) # # @compress: Use multiple compression threads to accelerate live migration. -# This feature can help to reduce the migration traffic, by sending -# compressed pages. Please note that if compress and xbzrle are both -# on, compress only takes effect in the ram bulk stage, after that, -# it will be disabled and only xbzrle takes effect, this can help to -# minimize migration traffic. The feature is disabled by default. -# (since 2.4 ) +# This feature can help to reduce the migration traffic, by sending +# compressed pages. Please note that if compress and xbzrle are both +# on, compress only takes effect in the ram bulk stage, after that, +# it will be disabled and only xbzrle takes effect, this can help to +# minimize migration traffic. The feature is disabled by default. +# (since 2.4 ) # # @events: generate events for each migration state change # (since 2.4 ) # # @auto-converge: If enabled, QEMU will automatically throttle down the guest -# to speed up convergence of RAM migration. (since 1.6) +# to speed up convergence of RAM migration. (since 1.6) # # @postcopy-ram: Start executing on the migration target before all of RAM has -# been migrated, pulling the remaining pages along as needed. The -# capacity must have the same setting on both source and target -# or migration will not even start. NOTE: If the migration fails during -# postcopy the VM will fail. (since 2.6) +# been migrated, pulling the remaining pages along as needed. The +# capacity must have the same setting on both source and target +# or migration will not even start. NOTE: If the migration fails during +# postcopy the VM will fail. (since 2.6) # # @x-colo: If enabled, migration will never end, and the state of the VM on the -# primary side will be migrated continuously to the VM on secondary -# side, this process is called COarse-Grain LOck Stepping (COLO) for -# Non-stop Service. (since 2.8) +# primary side will be migrated continuously to the VM on secondary +# side, this process is called COarse-Grain LOck Stepping (COLO) for +# Non-stop Service. (since 2.8) # # @release-ram: if enabled, qemu will free the migrated ram pages on the source -# during postcopy-ram migration. (since 2.9) +# during postcopy-ram migration. (since 2.9) # # @block: If enabled, QEMU will also migrate the contents of all block -# devices. Default is disabled. A possible alternative uses -# mirror jobs to a builtin NBD server on the destination, which -# offers more flexibility. -# (Since 2.10) +# devices. Default is disabled. A possible alternative uses +# mirror jobs to a builtin NBD server on the destination, which +# offers more flexibility. +# (Since 2.10) # # @return-path: If enabled, migration will use the return path even # for precopy. (since 2.10) # # @pause-before-switchover: Pause outgoing migration before serialising device -# state and before disabling block IO (since 2.11) +# state and before disabling block IO (since 2.11) # # @multifd: Use more than one fd for migration (since 4.0) # @@ -410,11 +410,11 @@ # (since 2.12) # # @postcopy-blocktime: Calculate downtime for postcopy live migration -# (since 3.0) +# (since 3.0) # # @late-block-activate: If enabled, the destination will not activate block -# devices (and thus take locks) immediately at the end of migration. -# (since 3.0) +# devices (and thus take locks) immediately at the end of migration. +# (since 3.0) # # @x-ignore-shared: If enabled, QEMU will not migrate shared memory (since 4.0) # @@ -494,24 +494,24 @@ # Migration parameters enumeration # # @announce-initial: Initial delay (in milliseconds) before sending the first -# announce (Since 4.0) +# announce (Since 4.0) # # @announce-max: Maximum delay (in milliseconds) between packets in the -# announcement (Since 4.0) +# announcement (Since 4.0) # # @announce-rounds: Number of self-announce packets sent after migration -# (Since 4.0) +# (Since 4.0) # # @announce-step: Increase in delay (in milliseconds) between subsequent -# packets in the announcement (Since 4.0) +# packets in the announcement (Since 4.0) # # @compress-level: Set the compression level to be used in live migration, -# the compression level is an integer between 0 and 9, where 0 means -# no compression, 1 means the best compression speed, and 9 means best -# compression ratio which will consume more CPU. +# the compression level is an integer between 0 and 9, where 0 means +# no compression, 1 means the best compression speed, and 9 means best +# compression ratio which will consume more CPU. # # @compress-threads: Set compression thread count to be used in live migration, -# the compression thread count is an integer between 1 and 255. +# the compression thread count is an integer between 1 and 255. # # @compress-wait-thread: Controls behavior when all compression threads are # currently busy. If true (default), wait for a free @@ -519,10 +519,10 @@ # send the page uncompressed. (Since 3.1) # # @decompress-threads: Set decompression thread count to be used in live -# migration, the decompression thread count is an integer between 1 -# and 255. Usually, decompression is at least 4 times as fast as -# compression, so set the decompress-threads to the number about 1/4 -# of compress-threads is adequate. +# migration, the decompression thread count is an integer between 1 +# and 255. Usually, decompression is at least 4 times as fast as +# compression, so set the decompress-threads to the number about 1/4 +# of compress-threads is adequate. # # @cpu-throttle-initial: Initial percentage of time guest cpus are throttled # when migration auto-converge is activated. The @@ -560,14 +560,14 @@ # downtime in milliseconds (Since 2.8) # # @x-checkpoint-delay: The delay time (in ms) between two COLO checkpoints in -# periodic mode. (Since 2.8) +# periodic mode. (Since 2.8) # # @block-incremental: Affects how much storage is migrated when the -# block migration capability is enabled. When false, the entire -# storage backing chain is migrated into a flattened image at -# the destination; when true, only the active qcow2 layer is -# migrated and the destination must already have access to the -# same backing chain as was used on the source. (since 2.10) +# block migration capability is enabled. When false, the entire +# storage backing chain is migrated into a flattened image at +# the destination; when true, only the active qcow2 layer is +# migrated and the destination must already have access to the +# same backing chain as was used on the source. (since 2.10) # # @multifd-channels: Number of channels used to migrate data in # parallel. This is the same number that the @@ -580,8 +580,8 @@ # (Since 2.11) # # @max-postcopy-bandwidth: Background transfer bandwidth during postcopy. -# Defaults to 0 (unlimited). In bytes per second. -# (Since 3.0) +# Defaults to 0 (unlimited). In bytes per second. +# (Since 3.0) # # @max-cpu-throttle: maximum cpu throttle percentage. # Defaults to 99. (Since 3.1) @@ -604,16 +604,16 @@ # @MigrateSetParameters: # # @announce-initial: Initial delay (in milliseconds) before sending the first -# announce (Since 4.0) +# announce (Since 4.0) # # @announce-max: Maximum delay (in milliseconds) between packets in the -# announcement (Since 4.0) +# announcement (Since 4.0) # # @announce-rounds: Number of self-announce packets sent after migration -# (Since 4.0) +# (Since 4.0) # # @announce-step: Increase in delay (in milliseconds) between subsequent -# packets in the announcement (Since 4.0) +# packets in the announcement (Since 4.0) # # @compress-level: compression level # @@ -665,11 +665,11 @@ # @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8) # # @block-incremental: Affects how much storage is migrated when the -# block migration capability is enabled. When false, the entire -# storage backing chain is migrated into a flattened image at -# the destination; when true, only the active qcow2 layer is -# migrated and the destination must already have access to the -# same backing chain as was used on the source. (since 2.10) +# block migration capability is enabled. When false, the entire +# storage backing chain is migrated into a flattened image at +# the destination; when true, only the active qcow2 layer is +# migrated and the destination must already have access to the +# same backing chain as was used on the source. (since 2.10) # # @multifd-channels: Number of channels used to migrate data in # parallel. This is the same number that the @@ -682,8 +682,8 @@ # (Since 2.11) # # @max-postcopy-bandwidth: Background transfer bandwidth during postcopy. -# Defaults to 0 (unlimited). In bytes per second. -# (Since 3.0) +# Defaults to 0 (unlimited). In bytes per second. +# (Since 3.0) # # @max-cpu-throttle: maximum cpu throttle percentage. # The default value is 99. (Since 3.1) @@ -737,16 +737,16 @@ # The optional members aren't actually optional. # # @announce-initial: Initial delay (in milliseconds) before sending the -# first announce (Since 4.0) +# first announce (Since 4.0) # # @announce-max: Maximum delay (in milliseconds) between packets in the -# announcement (Since 4.0) +# announcement (Since 4.0) # # @announce-rounds: Number of self-announce packets sent after migration -# (Since 4.0) +# (Since 4.0) # # @announce-step: Increase in delay (in milliseconds) between subsequent -# packets in the announcement (Since 4.0) +# packets in the announcement (Since 4.0) # # @compress-level: compression level # @@ -799,11 +799,11 @@ # @x-checkpoint-delay: the delay time between two COLO checkpoints. (Since 2.8) # # @block-incremental: Affects how much storage is migrated when the -# block migration capability is enabled. When false, the entire -# storage backing chain is migrated into a flattened image at -# the destination; when true, only the active qcow2 layer is -# migrated and the destination must already have access to the -# same backing chain as was used on the source. (since 2.10) +# block migration capability is enabled. When false, the entire +# storage backing chain is migrated into a flattened image at +# the destination; when true, only the active qcow2 layer is +# migrated and the destination must already have access to the +# same backing chain as was used on the source. (since 2.10) # # @multifd-channels: Number of channels used to migrate data in # parallel. This is the same number that the @@ -816,12 +816,12 @@ # (Since 2.11) # # @max-postcopy-bandwidth: Background transfer bandwidth during postcopy. -# Defaults to 0 (unlimited). In bytes per second. -# (Since 3.0) +# Defaults to 0 (unlimited). In bytes per second. +# (Since 3.0) # # @max-cpu-throttle: maximum cpu throttle percentage. # Defaults to 99. -# (Since 3.1) +# (Since 3.1) # # Since: 2.4 ## @@ -1047,8 +1047,8 @@ # The reason for a COLO exit. # # @none: failover has never happened. This state does not occur -# in the COLO_EXIT event, and is only visible in the result of -# query-colo-status. +# in the COLO_EXIT event, and is only visible in the result of +# query-colo-status. # # @request: COLO exit is due to an external request. # @@ -1281,11 +1281,11 @@ # of the VM are not saved by this command. # # @filename: the file to save the state of the devices to as binary -# data. See xen-save-devices-state.txt for a description of the binary -# format. +# data. See xen-save-devices-state.txt for a description of the binary +# format. # # @live: Optional argument to ask QEMU to treat this command as part of a live -# migration. Default to true. (since 2.11) +# migration. Default to true. (since 2.11) # # Returns: Nothing on success # diff --git a/qapi/misc-target.json b/qapi/misc-target.json index a00fd821ebc..dee3b459301 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -230,14 +230,14 @@ # QEMU/KVM software version, but also decided by the hardware that # the program is running upon. # -# @version: version of GIC to be described. Currently, only 2 and 3 -# are supported. +# @version: version of GIC to be described. Currently, only 2 and 3 +# are supported. # # @emulated: whether current QEMU/hardware supports emulated GIC # device in user space. # -# @kernel: whether current QEMU/hardware supports hardware -# accelerated GIC device in kernel. +# @kernel: whether current QEMU/hardware supports hardware +# accelerated GIC device in kernel. # # Since: 2.6 ## diff --git a/qapi/misc.json b/qapi/misc.json index 33b94e35896..626a342b008 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -14,11 +14,11 @@ # # Arguments: # -# @enable: An optional list of QMPCapability values to enable. The -# client must not enable any capability that is not -# mentioned in the QMP greeting message. If the field is not -# provided, it means no QMP capabilities will be enabled. -# (since 2.12) +# @enable: An optional list of QMPCapability values to enable. The +# client must not enable any capability that is not +# mentioned in the QMP greeting message. If the field is not +# provided, it means no QMP capabilities will be enabled. +# (since 2.12) # # Example: # @@ -27,11 +27,11 @@ # <- { "return": {} } # # Notes: This command is valid exactly when first connecting: it must be -# issued before any other command will be accepted, and will fail once the -# monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt) +# issued before any other command will be accepted, and will fail once the +# monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt) # -# The QMP client needs to explicitly enable QMP capabilities, otherwise -# all the QMP capabilities will be turned off by default. +# The QMP client needs to explicitly enable QMP capabilities, otherwise +# all the QMP capabilities will be turned off by default. # # Since: 0.13 # @@ -46,8 +46,8 @@ # Enumeration of capabilities to be advertised during initial client # connection, used for agreeing on particular QMP extension behaviors. # -# @oob: QMP ability to support out-of-band requests. -# (Please refer to qmp-spec.txt for more information on OOB) +# @oob: QMP ability to support out-of-band requests. +# (Please refer to qmp-spec.txt for more information on OOB) # # Since: 2.12 # @@ -60,11 +60,11 @@ # # A three-part version number. # -# @major: The major version number. +# @major: The major version number. # -# @minor: The minor version number. +# @minor: The minor version number. # -# @micro: The micro version number. +# @micro: The micro version number. # # Since: 2.4 ## @@ -77,16 +77,16 @@ # # A description of QEMU's version. # -# @qemu: The version of QEMU. By current convention, a micro -# version of 50 signifies a development branch. A micro version -# greater than or equal to 90 signifies a release candidate for -# the next minor version. A micro version of less than 50 -# signifies a stable release. +# @qemu: The version of QEMU. By current convention, a micro +# version of 50 signifies a development branch. A micro version +# greater than or equal to 90 signifies a release candidate for +# the next minor version. A micro version of less than 50 +# signifies a stable release. # -# @package: QEMU will always set this field to an empty string. Downstream -# versions of QEMU should set this to a non-empty string. The -# exact format depends on the downstream however it highly -# recommended that a unique name is used. +# @package: QEMU will always set this field to an empty string. Downstream +# versions of QEMU should set this to a non-empty string. The +# exact format depends on the downstream however it highly +# recommended that a unique name is used. # # Since: 0.14.0 ## @@ -98,7 +98,7 @@ # # Returns the current version of QEMU. # -# Returns: A @VersionInfo object describing the current version of QEMU. +# Returns: A @VersionInfo object describing the current version of QEMU. # # Since: 0.14.0 # @@ -321,7 +321,7 @@ # Since: 1.2.0 # # Note: This command is deprecated, because its output doesn't reflect -# compile-time configuration. Use query-qmp-schema instead. +# compile-time configuration. Use query-qmp-schema instead. # # Example: # @@ -375,8 +375,8 @@ # Returns a list of information about each iothread. # # Note: this list excludes the QEMU main loop thread, which is not declared -# using the -object iothread command-line option. It is always the main thread -# of the process. +# using the -object iothread command-line option. It is always the main thread +# of the process. # # Returns: a list of @IOThreadInfo for each iothread # @@ -624,9 +624,9 @@ # Return information about the PCI bus topology of the guest. # # Returns: a list of @PciInfo for each PCI bus. Each bus is -# represented by a json-object, which has a key with a json-array of -# all PCI devices attached to it. Each device is represented by a -# json-object. +# represented by a json-object, which has a key with a json-array of +# all PCI devices attached to it. Each device is represented by a +# json-object. # # Since: 0.14.0 # @@ -788,10 +788,10 @@ # # Since: 0.14.0 # -# Notes: This function will succeed even if the guest is already in the stopped -# state. In "inmigrate" state, it will ensure that the guest -# remains paused once migration finishes, as if the -S option was -# passed on the command line. +# Notes: This function will succeed even if the guest is already in the stopped +# state. In "inmigrate" state, it will ensure that the guest +# remains paused once migration finishes, as if the -S option was +# passed on the command line. # # Example: # @@ -847,7 +847,7 @@ # @filename: the file to save the memory to as binary data # # @cpu-index: the index of the virtual CPU to use for translating the -# virtual address (defaults to CPU 0) +# virtual address (defaults to CPU 0) # # Returns: Nothing on success # @@ -905,11 +905,11 @@ # # Returns: If successful, nothing # -# Notes: This command will succeed if the guest is currently running. It -# will also succeed if the guest is in the "inmigrate" state; in -# this case, the effect of the command is to make sure the guest -# starts once migration finishes, removing the effect of the -S -# command line option if it was passed. +# Notes: This command will succeed if the guest is currently running. It +# will also succeed if the guest is in the "inmigrate" state; in +# this case, the effect of the command is to make sure the guest +# starts once migration finishes, removing the effect of the -S +# command line option if it was passed. # # Example: # @@ -955,7 +955,7 @@ # Returns: nothing. # # Note: prior to 4.0, this command does nothing in case the guest -# isn't suspended. +# isn't suspended. # # Example: # @@ -1069,18 +1069,18 @@ # change password command. Otherwise, this specifies a new server URI # address to listen to for VNC connections. # -# @arg: If @device is a block device, then this is an optional format to open -# the device with. -# If @device is 'vnc' and @target is 'password', this is the new VNC -# password to set. See change-vnc-password for additional notes. +# @arg: If @device is a block device, then this is an optional format to open +# the device with. +# 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 # -# Notes: This interface is deprecated, and it is strongly recommended that you -# avoid using it. For changing block devices, use -# blockdev-change-medium; for changing VNC parameters, use -# change-vnc-password. +# Notes: This interface is deprecated, and it is strongly recommended that you +# avoid using it. For changing block devices, use +# blockdev-change-medium; for changing VNC parameters, use +# change-vnc-password. # # Since: 0.14.0 # @@ -1719,8 +1719,8 @@ # of the VM are not loaded by this command. # # @filename: the file to load the state of the devices from as binary -# data. See xen-save-devices-state.txt for a description of the binary -# format. +# data. See xen-save-devices-state.txt for a description of the binary +# format. # # Since: 2.7 # diff --git a/qapi/net.json b/qapi/net.json index 335295be506..109eff71cd4 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -47,9 +47,9 @@ # Additional arguments depend on the type. # # TODO: This command effectively bypasses QAPI completely due to its -# "additional arguments" business. It shouldn't have been added to -# the schema in this form. It should be qapified properly, or -# replaced by a properly qapified command. +# "additional arguments" business. It shouldn't have been added to +# the schema in this form. It should be qapified properly, or +# replaced by a properly qapified command. # # Since: 0.14.0 # @@ -213,7 +213,7 @@ # @fd: file descriptor of an already opened tap # # @fds: multiple file descriptors of already opened multiqueue capable -# tap +# tap # # @script: script to initialize the interface # @@ -232,14 +232,14 @@ # @vhostfd: file descriptor of an already opened vhost net device # # @vhostfds: file descriptors of multiple already opened vhost net -# devices +# devices # # @vhostforce: vhost on for non-MSIX virtio guests # # @queues: number of queues to be created for multiqueue capable tap # # @poll-us: maximum number of microseconds that could -# be spent on busy polling for tap (since 2.7) +# be spent on busy polling for tap (since 2.7) # # Since: 1.2 ## @@ -691,7 +691,7 @@ # Parameters for self-announce timers # # @initial: Initial delay (in ms) before sending the first GARP/RARP -# announcement +# announcement # # @max: Maximum delay (in ms) between GARP/RARP announcement packets # @@ -700,11 +700,11 @@ # @step: Delay increase (in ms) after each self-announcement attempt # # @interfaces: An optional list of interface names, which restricts the -# announcement to the listed interfaces. (Since 4.1) +# announcement to the listed interfaces. (Since 4.1) # # @id: A name to be used to identify an instance of announce-timers -# and to allow it to modified later. Not for use as -# part of the migration parameters. (Since 4.1) +# and to allow it to modified later. Not for use as +# part of the migration parameters. (Since 4.1) # # Since: 4.0 ## diff --git a/qapi/qdev.json b/qapi/qdev.json index c6d05032f4a..f4ed9735c43 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -19,8 +19,8 @@ # Returns: a list of ObjectPropertyInfo describing a devices properties # # Note: objects can create properties at runtime, for example to describe -# links between different devices and/or objects. These properties -# are not included in the output of this command. +# links between different devices and/or objects. These properties +# are not included in the output of this command. # # Since: 1.2 ## @@ -58,9 +58,9 @@ # <- { "return": {} } # # TODO: This command effectively bypasses QAPI completely due to its -# "additional arguments" business. It shouldn't have been added to -# the schema in this form. It should be qapified properly, or -# replaced by a properly qapified command. +# "additional arguments" business. It shouldn't have been added to +# the schema in this form. It should be qapified properly, or +# replaced by a properly qapified command. # # Since: 0.13 ## diff --git a/qapi/qom.json b/qapi/qom.json index 1e3c2ad5556..ecc60c4401c 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -189,8 +189,8 @@ # @typename: the type name of an object # # Note: objects can create properties at runtime, for example to describe -# links between different devices and/or objects. These properties -# are not included in the output of this command. +# links between different devices and/or objects. These properties +# are not included in the output of this command. # # Returns: a list of ObjectPropertyInfo describing object properties # diff --git a/qapi/rocker.json b/qapi/rocker.json index 3587661161d..52597db491a 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -140,7 +140,7 @@ # @ip-dst: IP header destination address # # Note: optional members may or may not appear in the flow key -# depending if they're relevant to the flow key. +# depending if they're relevant to the flow key. # # Since: 2.4 ## @@ -170,7 +170,7 @@ # @ip-tos: IP header TOS field # # Note: optional members may or may not appear in the flow mask -# depending if they're relevant to the flow mask. +# depending if they're relevant to the flow mask. # # Since: 2.4 ## @@ -197,7 +197,7 @@ # @out-pport: physical output port # # Note: optional members may or may not appear in the flow action -# depending if they're relevant to the flow action. +# depending if they're relevant to the flow action. # # Since: 2.4 ## @@ -235,7 +235,7 @@ # @name: switch name # # @tbl-id: flow table ID. If tbl-id is not specified, returns -# flow information for all tables. +# flow information for all tables. # # Returns: rocker OF-DPA flow information # @@ -291,7 +291,7 @@ # @ttl-check: perform TTL check # # Note: optional members may or may not appear in the group depending -# if they're relevant to the group type. +# if they're relevant to the group type. # # Since: 2.4 ## @@ -311,7 +311,7 @@ # @name: switch name # # @type: group type. If type is not specified, returns -# group information for all group types. +# group information for all group types. # # Returns: rocker OF-DPA group information # diff --git a/qapi/run-state.json b/qapi/run-state.json index b83a436a3e6..2e229077400 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -15,16 +15,16 @@ # @finish-migrate: guest is paused to finish the migration process # # @inmigrate: guest is paused waiting for an incoming migration. Note -# that this state does not tell whether the machine will start at the -# end of the migration. This depends on the command-line -S option and -# any invocation of 'stop' or 'cont' that has happened since QEMU was -# started. +# that this state does not tell whether the machine will start at the +# end of the migration. This depends on the command-line -S option and +# any invocation of 'stop' or 'cont' that has happened since QEMU was +# started. # # @internal-error: An internal error that prevents further guest execution -# has occurred +# has occurred # # @io-error: the last IOP has failed and the device is configured to pause -# on I/O errors +# on I/O errors # # @paused: guest has been paused via the 'stop' command # @@ -85,8 +85,8 @@ # @guest-panic: Guest panicked, and command line turns that into a shutdown # # @subsystem-reset: Partial guest reset that does not trigger QMP events and -# ignores --no-reboot. This is useful for sanitizing -# hypercalls on s390 that are used during kexec/kdump/boot +# ignores --no-reboot. This is useful for sanitizing +# hypercalls on s390 that are used during kexec/kdump/boot # ## { 'enum': 'ShutdownCause', @@ -140,13 +140,13 @@ # about to exit. # # @guest: If true, the shutdown was triggered by a guest request (such as -# a guest-initiated ACPI shutdown request or other hardware-specific action) -# rather than a host request (such as sending qemu a SIGINT). (since 2.10) +# a guest-initiated ACPI shutdown request or other hardware-specific action) +# rather than a host request (such as sending qemu a SIGINT). (since 2.10) # # @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since 4.0) # # Note: If the command-line option "-no-shutdown" has been specified, qemu will -# not exit, and a STOP event will eventually follow the SHUTDOWN event +# not exit, and a STOP event will eventually follow the SHUTDOWN event # # Since: 0.12.0 # @@ -180,9 +180,9 @@ # Emitted when the virtual machine is reset # # @guest: If true, the reset was triggered by a guest request (such as -# a guest-initiated ACPI reboot request or other hardware-specific action) -# rather than a host request (such as the QMP command system_reset). -# (since 2.10) +# a guest-initiated ACPI reboot request or other hardware-specific action) +# rather than a host request (such as the QMP command system_reset). +# (since 2.10) # # @reason: The @ShutdownCause of the RESET. (since 4.0) # @@ -283,7 +283,7 @@ # @action: action that has been taken # # Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is -# followed respectively by the RESET, SHUTDOWN, or STOP events +# followed respectively by the RESET, SHUTDOWN, or STOP events # # Note: This event is rate-limited. # @@ -441,12 +441,12 @@ # @disabled-wait: the CPU has entered a disabled wait state # # @extint-loop: clock comparator or cpu timer interrupt with new PSW enabled -# for external interrupts +# for external interrupts # # @pgmint-loop: program interrupt with BAD new PSW # # @opint-loop: operation exception interrupt with invalid code at the program -# interrupt new PSW +# interrupt new PSW # # Since: 2.12 ## diff --git a/qapi/sockets.json b/qapi/sockets.json index 32375f3a361..ea933ed4b2b 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -89,7 +89,7 @@ # @port: port # # Note: string types are used to allow for possible future hostname or -# service resolution support. +# service resolution support. # # Since: 2.8 ## @@ -104,9 +104,9 @@ # Captures the address of a socket, which could also be a named file descriptor # # Note: This type is deprecated in favor of SocketAddress. The -# difference between SocketAddressLegacy and SocketAddress is that the -# latter is a flat union rather than a simple union. Flat is nicer -# because it avoids nesting on the wire, i.e. that form has fewer {}. +# difference between SocketAddressLegacy and SocketAddress is that the +# latter is a flat union rather than a simple union. Flat is nicer +# because it avoids nesting on the wire, i.e. that form has fewer {}. # # Since: 1.3 diff --git a/qapi/trace.json b/qapi/trace.json index 799b254a186..4955e5a7503 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -52,14 +52,14 @@ # # Returns: a list of @TraceEventInfo for the matching events # -# An event is returned if: -# - its name matches the @name pattern, and -# - if @vcpu is given, the event has the "vcpu" property. +# An event is returned if: +# - its name matches the @name pattern, and +# - if @vcpu is given, the event has the "vcpu" property. # -# Therefore, if @vcpu is given, the operation will only match per-vCPU events, -# returning their state on the specified vCPU. Special case: if @name is an -# exact match, @vcpu is given and the event does not have the "vcpu" property, -# an error is returned. +# Therefore, if @vcpu is given, the operation will only match per-vCPU events, +# returning their state on the specified vCPU. Special case: if @name is an +# exact match, @vcpu is given and the event does not have the "vcpu" property, +# an error is returned. # # Since: 2.2 # diff --git a/qapi/transaction.json b/qapi/transaction.json index 0590dbcd1ae..04301f1be79 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -132,8 +132,8 @@ # Errors depend on the operations of the transaction # # Note: The transaction aborts on the first failure. Therefore, there will be -# information on only one failed operation returned in an error condition, and -# subsequent actions will not have been attempted. +# information on only one failed operation returned in an error condition, and +# subsequent actions will not have been attempted. # # Since: 1.1 # diff --git a/qapi/ui.json b/qapi/ui.json index e04525d8b44..aced267a1e4 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -18,10 +18,10 @@ # @password: the new password # # @connected: how to handle existing clients when changing the -# password. If nothing is specified, defaults to `keep' -# `fail' to fail the command if clients are connected -# `disconnect' to disconnect existing clients -# `keep' to maintain existing clients +# password. If nothing is specified, defaults to `keep' +# `fail' to fail the command if clients are connected +# `disconnect' to disconnect existing clients +# `keep' to maintain existing clients # # Returns: Nothing on success # If Spice is not enabled, DeviceNotFound @@ -591,12 +591,12 @@ # # Change the VNC server password. # -# @password: the new password to use with VNC authentication +# @password: the new password to use with VNC authentication # # Since: 1.1 # -# Notes: An empty password in this command will set the password to the empty -# string. Existing clients are unaffected by executing this command. +# Notes: An empty password in this command will set the password to the empty +# string. Existing clients are unaffected by executing this command. ## { 'command': 'change-vnc-password', 'data': { 'password': 'str' }, @@ -612,7 +612,7 @@ # @client: client information # # Note: This event is emitted before any authentication takes place, thus -# the authentication ID is not provided +# the authentication ID is not provided # # Since: 0.13.0 # @@ -915,9 +915,9 @@ # # Pointer motion input event. # -# @axis: Which axis is referenced by @value. -# @value: Pointer position. For absolute coordinates the -# valid range is 0 -> 0x7ffff +# @axis: Which axis is referenced by @value. +# @value: Pointer position. For absolute coordinates the +# valid range is 0 -> 0x7ffff # # Since: 2.0 ## @@ -931,10 +931,10 @@ # Input event union. # # @type: the input type, one of: -# - 'key': Input event of Keyboard -# - 'btn': Input event of pointer buttons -# - 'rel': Input event of relative pointer motion -# - 'abs': Input event of absolute pointer motion +# - 'key': Input event of Keyboard +# - 'btn': Input event of pointer buttons +# - 'rel': Input event of relative pointer motion +# - 'abs': Input event of absolute pointer motion # # Since: 2.0 ## @@ -970,9 +970,9 @@ # Since: 2.6 # # Note: The consoles are visible in the qom tree, under -# /backend/console[$index]. They have a device link and head property, -# so it is possible to map which console belongs to which device and -# display. +# /backend/console[$index]. They have a device link and head property, +# so it is possible to map which console belongs to which device and +# display. # # Example: # From patchwork Thu Feb 6 17:30:21 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183112 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1838764ile; Thu, 6 Feb 2020 09:39:05 -0800 (PST) X-Google-Smtp-Source: APXvYqz/urPIKUysdlQfja8lwSox9/y3WlOUdagZSyjVY4nyFgeSrXGsOySv7lQ4Ydo4iELh36Gp X-Received: by 2002:ac8:554b:: with SMTP id o11mr3685523qtr.36.1581010745602; Thu, 06 Feb 2020 09:39:05 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010745; cv=none; d=google.com; s=arc-20160816; b=cxkgMjU0MHQ6L373NxugIqeLIouhuDw/ChKUmia/4U+ZQx4eH4On3A/li8vP6h8bS1 IRU1dgA5BsroJWo5zadv1nmsS7nWXNsJ/mV0GH3nqS6XuowXuyZTszKpwdNCiH9tJT75 L6V9epxj/KyhWuu0KFtS6xK0ZJ473Re0QI8mK3rH6mzgYOXnAT5+9s7FePrwl+BZGS6S R59YCklvixcWy82ARJy0eS3F/e56xlOqSK7jVSsSP39xHgho5x3J8ajxj+zd6w+Xo7qR 5I0g0x/sHK4F9whkTYPoMjG+WFhBgciarniVtV77v2pOdEY78ZIohT6PCYoQYqr0HE86 UVVA== 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=w5pl3TzQvaQVnyMYNeKi2uN7fk7InvWwzklZYoBOlQs=; b=s2nhGnQRl2lgz9RrXy5g0oY7oqV/BXUkmuuS6Wa++FeL9J6Gy1opfmO2CXWYTK5fwc EPOAboQE+5D74BZyGqSwpZIwU7Rf2UTVMbxdcoa9e5xYEVQ75Z8DUpKDRTcwRvMkdNhY LqCDHvYPSSlKh/EjUP7d+JwujeZuUbETlHEwQKzpWqRC4SSLls4H1ZvJ4qfLJHsSdeIQ YTl9DpMNyk3S6PpTnCL+qryFWxQvVTaHd1ky/ZjTHJQol4FDJopolOzsq1rRPrPWCtMU eST7jP9SMyXuIXzR3JkmcgsTO84BAB1ZUiBo3ugHfWA8kZj3hHQicFwZGc1HXecSHt6T QETQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="qCQE/I5L"; 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 dc4si1714495qvb.164.2020.02.06.09.39.05 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:39:05 -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="qCQE/I5L"; 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]:43490 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl7J-0001kk-2e for patch@linaro.org; Thu, 06 Feb 2020 12:39:05 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43411) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzi-0006fP-Mr for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:22 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzh-0005Vr-JD for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:14 -0500 Received: from mail-wr1-x432.google.com ([2a00:1450:4864:20::432]:42906) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzh-0005O9-Cg for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:13 -0500 Received: by mail-wr1-x432.google.com with SMTP id k11so8179824wrd.9 for ; Thu, 06 Feb 2020 09:31:12 -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=w5pl3TzQvaQVnyMYNeKi2uN7fk7InvWwzklZYoBOlQs=; b=qCQE/I5LhFJZLl3wTpxiQ4MIIL60lARoR1glCBE7G8fp/atAaTrEWixCOvehMbY5RI Gk7znuUqw9p4ACtsR6enTWBiIXa2PpB7WNIyyON6kyFiixK8jnIpmFyPBINh7HGA/ga5 Ts7NDhjhn5U1uhr3Sh6LvL9KeYlXGfQL8hon9CbRAai6vGfA0tifoPZoi7WlCWzxNjzE Os7Y5I7gt80qX53sCGWgbAKuJdS87qgwWFtru+IesWPPt6dlIUCepZc/NUkpiFz6rPH+ OIla3Eo486wyZKtk1CmKul2HLdAsnXblkX+y+ukRaSHm8fAQWhp/AnXRQ6FZSds/Xo1S OcNA== 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=w5pl3TzQvaQVnyMYNeKi2uN7fk7InvWwzklZYoBOlQs=; b=pybBgYdmHOUNdyLbyi2oEWOOknYJh670jM/SHSozfuuPiuwBWJ4yq7wLbuIChCJNC/ c71B2VYTaHRb/hBM+RYHVu3Z8WDAKRYShMkBKd+ItTGlj9FlhUlVlk6HNx1OFa3PgKBA ArcGsfeUF1r168Ycdym8qUKhZijXFmOiz15IP3+1KFm5kLd3QHrV6H1XuqGKgkjPhrj7 nTFzbn781pYG9Cv9YUXmyIBKlYadEzg9obyzDraFwU69qHjuxNfKlFKQEMIWPq9AF1hw sRzwh9SJwxkuV9s8Wgtj1Sc/radc6A7vjvcusK9lw6Of/S0rRcIAC+Tcc7jAtjUqZj7p UDZQ== X-Gm-Message-State: APjAAAWiXwHReR1ubBbAc2yUnOmZALpKzAsSDmINNnRcfQaIGjiZ4zXn FNEN6KCNHuYMK7zQzjqNllSv+fUwGOc= X-Received: by 2002:a5d:488c:: with SMTP id g12mr4970537wrq.67.1581010270862; Thu, 06 Feb 2020 09:31:10 -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.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:09 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 10/29] qapi: Remove hardcoded tabs Date: Thu, 6 Feb 2020 17:30:21 +0000 Message-Id: <20200206173040.17337-11-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::432 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" There are some stray hardcoded tabs in some of our json files; remove them. Signed-off-by: Peter Maydell --- Most of the hardcoded tabs got removed in passing in fixing the indent in lines that they were in, but these are not part of doc comments. --- qapi/block-core.json | 4 ++-- qapi/migration.json | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) -- 2.20.1 Reviewed-by: Markus Armbruster diff --git a/qapi/block-core.json b/qapi/block-core.json index 006a0bf7a7c..6cc8a4f73e0 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -2938,8 +2938,8 @@ '*pr-manager': 'str', '*locking': 'OnOffAuto', '*aio': 'BlockdevAioOptions', - '*drop-cache': {'type': 'bool', - 'if': 'defined(CONFIG_LINUX)'}, + '*drop-cache': {'type': 'bool', + 'if': 'defined(CONFIG_LINUX)'}, '*x-check-cache-dropped': 'bool' }, 'features': [ { 'name': 'dynamic-auto-read-only', 'if': 'defined(CONFIG_POSIX)' } ] } diff --git a/qapi/migration.json b/qapi/migration.json index aa160e9e42d..11033b7a8e6 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -98,7 +98,7 @@ ## { 'struct': 'CompressionStats', 'data': {'pages': 'int', 'busy': 'int', 'busy-rate': 'number', - 'compressed-size': 'int', 'compression-rate': 'number' } } + 'compressed-size': 'int', 'compression-rate': 'number' } } ## # @MigrationStatus: @@ -713,7 +713,7 @@ '*multifd-channels': 'int', '*xbzrle-cache-size': 'size', '*max-postcopy-bandwidth': 'size', - '*max-cpu-throttle': 'int' } } + '*max-cpu-throttle': 'int' } } ## # @migrate-set-parameters: @@ -845,7 +845,7 @@ '*block-incremental': 'bool' , '*multifd-channels': 'uint8', '*xbzrle-cache-size': 'size', - '*max-postcopy-bandwidth': 'size', + '*max-postcopy-bandwidth': 'size', '*max-cpu-throttle':'uint8'} } ## From patchwork Thu Feb 6 17:30:22 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183115 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1840767ile; Thu, 6 Feb 2020 09:41:07 -0800 (PST) X-Google-Smtp-Source: APXvYqwv5S4iWwonIE/x1+7d8q9zM0eNbU3rVKuu/1yRlKmPrfDnJ58fqXIQgQf3U0HoPTjgUrV5 X-Received: by 2002:a05:620a:1650:: with SMTP id c16mr3644728qko.346.1581010867112; Thu, 06 Feb 2020 09:41:07 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010867; cv=none; d=google.com; s=arc-20160816; b=reQ0i7c0dGk2O+rcXixhj+I+6TGQaI1C/BBip1eFCivF4qPS3X/I0rgNYO/TcmTJsz YYqMBPuZc4Thf16XoaT/EwXb0dZexTSiJZmK4fekXtN0ZD8UlmqxLfm3r0OftYf7jm2V kUYHy6gyq6dAGeLgjdAysNfSTTGkTGxNj4+lQc9juZo7fLykeWbYfjCwtcCQSqOuB2NF SN86hhRn7g9oEKUTplDhLSt4jGJwPBi9fdUSzZ/M87qrXW6XBlvwFmTH9nsUx9hMyjYn 459aKChIo86bXw6rkkquYtCpCNK4tJx7oXpMzvN9pnTYf1iGqOtlGsmbk6L2VwBlfOfo RIpw== 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=5mUsQje4Vxn3HIOn4m+YirZWxx0e2UfwIWtWTCNnLRg=; b=iAAv88UoX8/05tVKlMT4RRzzpli+USdZ1Fvzeei1rt8Vn1LXvJvsZKd0ZNSXR9HKvz qo3Olff1DUoCaXtgbAwJVqWU9gaO/FMPUk4gb+T+UmQ/xV3/KnXjkNWrLLMmLX7Mj7gb L0yWMCM9+gGJRiHmAsAZGndBCF3pmQIHxBy9TSi9DKEoUuGmhpsOe0zCT7Ex+J4tgfo8 pK2NI3ThDzwuu7JFDU+vL0/xBmyMB26MG8g8qdt+HW5aHEW5UMWP2m2HxFi8kkRbj1nX C3oELjnbbC8WxIamVMyj1EKyqVmOmrYCK7eMi+Zf+ZCZBT32OdwsVQ/EvzyEQ15Z6Fia br1A== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=rG28sFKt; 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 p5si1923906qkg.349.2020.02.06.09.41.07 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:41:07 -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=rG28sFKt; 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]:43548 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl9G-0005LZ-K4 for patch@linaro.org; Thu, 06 Feb 2020 12:41:06 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43426) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzo-0006fZ-4a for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:22 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzl-0005gr-9z for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:18 -0500 Received: from mail-wm1-x32a.google.com ([2a00:1450:4864:20::32a]:38357) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzl-0005d1-2O for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:17 -0500 Received: by mail-wm1-x32a.google.com with SMTP id a9so991717wmj.3 for ; Thu, 06 Feb 2020 09:31: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=5mUsQje4Vxn3HIOn4m+YirZWxx0e2UfwIWtWTCNnLRg=; b=rG28sFKteKvDW4C56gkPydRex38f6gwl7bRyHnqhUSQwUPImCALIN5j+ya7sRPfBdu SkCGgUmNtfWSgvfJngqJ6cQShrXQxzcPU0OztWTctjFILlszYgdbtW0exLXg2BqmBhdw RrKGIWKWGzd7uWIecdua1gRcClg99GmCgvyzgNZeoTLoSRrgmMEIB7+tADSRzMlkF50H biBWSqkOlziwl1cySXALBnNZtfl+wgtQGiJyhYFWe2u+hYzNM0tOun2YlkcP7pFibIFR WnE3vFVUG0Gg733Os3OWSFvFYWWUT+yKgZieQol/K6AyjvKyMDs2RFKWDlxeFbFI1zi3 D+Kg== 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=5mUsQje4Vxn3HIOn4m+YirZWxx0e2UfwIWtWTCNnLRg=; b=HRNOJo7ObggtSXkwdTmudvoRObtIrFU2aDj445TI4WiD8x7rpT75Zkgal2a2mWOt6f z50CC8LXk11s5YFHhZ+VWC9WvY0xTMjPMN+zGjwczBAId156z0tGpx/SCkZyAkRR4Afc Psg8y8Z7xglPuP8bwgEeQJGVTnyg9H3Y5lNBWxgnlZXkK4OMz+xJ2bHl4g6o1O1ByvPd KEfAhRyZHNK1mlAyUB9lvaMwwVuC5ARSb3wZo54AWtMvfU8lIk1X7DpmaCW8HgkGSIib QgStVhn5eaP7WL1fNynMMU6mAjz3qtyYXGMcyUgbXNsNNcvJAuPHWYSkE3TPbTnqeqZN 1T8A== X-Gm-Message-State: APjAAAVtvjGHbT1bSVm/oe5du0QPRspcquytijhiArI9MJKXvsz2TvWZ GLyUs+wxw35nZjp+eRr7gWNHeP4KlXo= X-Received: by 2002:a7b:c152:: with SMTP id z18mr5662343wmi.70.1581010275290; Thu, 06 Feb 2020 09:31:15 -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.10 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:11 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 11/29] qapi/ui.json: Put input-send-event body text in the right place Date: Thu, 6 Feb 2020 17:30:22 +0000 Message-Id: <20200206173040.17337-12-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::32a 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" In the doc comment for input-send-event, there is a multi-line chunk of text ("The @device...take precedence") which is intended to be the main body text describing the event. However it has been placed after the arguments and Returns: section, which means that the parser actually thinks that this text is part of the "Returns" section text. Move the body text up to the top so that the parser correctly classifies it as body. Signed-off-by: Peter Maydell --- qapi/ui.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) -- 2.20.1 Reviewed-by: Markus Armbruster diff --git a/qapi/ui.json b/qapi/ui.json index aced267a1e4..94a07318f55 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -949,13 +949,6 @@ # # Send input event(s) to guest. # -# @device: display device to send event(s) to. -# @head: head to send event(s) to, in case the -# display device supports multiple scanouts. -# @events: List of InputEvent union. -# -# Returns: Nothing on success. -# # The @device and @head parameters can be used to send the input event # to specific input devices in case (a) multiple input devices of the # same kind are added to the virtual machine and (b) you have @@ -967,6 +960,13 @@ # are admissible, but devices with input routing config take # precedence. # +# @device: display device to send event(s) to. +# @head: head to send event(s) to, in case the +# display device supports multiple scanouts. +# @events: List of InputEvent union. +# +# Returns: Nothing on success. +# # Since: 2.6 # # Note: The consoles are visible in the qom tree, under From patchwork Thu Feb 6 17:30:23 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183109 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1836649ile; Thu, 6 Feb 2020 09:37:10 -0800 (PST) X-Google-Smtp-Source: APXvYqzKOIK4xD6f8DMCLQJDUMnWc9/iDK6wE9SfOYR67y6DZvhXNkwpXi01kiyOvahbrHbGNCxD X-Received: by 2002:aed:2643:: with SMTP id z61mr3728084qtc.49.1581010630719; Thu, 06 Feb 2020 09:37:10 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010630; cv=none; d=google.com; s=arc-20160816; b=j2p/s+MkbtcLlvpRZfkSBHCUrOrIzyqwq40eimDRkRdJ5E9OlVsD2Pa6VqnDIrvgZp MMF07Q/uctn4XEPg5GzsBw8EQ0/G1JjKPSl0DCpDwoUoJ0pfa2ZWyOqy+kOlwwrQEstB oRI2e1SgcRFwZ8e6MK1eOzMORSI8QZ5BfKlQ/B/iZvxv0e0DxcvG/RgIjpEWZWxNqGHh tW5oZpLcxp0vK0Icm6GzLTJkbvcS18eNzAISmXHaRQCufh6pwlqUKU+pNb/jAnRtLv8M MSuNwWtz2elCANR+u6Jcp9DUlQVWgkp4MrR0kALVY+ZPyciBt47bFN7juRvxVaYc3pqV 0BuA== 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=ny3WK8pMdlgBlAoYUdqL7k5E1SZb/jHOFqlIQGucr5M=; b=Liu/iNxCwMOxTYbA1eavk9OtQjeeOMRWQ1z3nCM3H165JBPNU+XM3uK0rTtXMwQ2d+ gyc+0XDr+PcvQxbJwqo6eo3Iz2PlgwhQ66K6DOcFIo5Eb7JSVpHytERwq9cg9DxQQXwC tSeE0eFXUMAZhDhCr4esuwu4pwPy86NQ7wwYI1KOc5HWd6Ttp+YcsYuAkeOTzPO1Ezda NlTUNjRQf3E2JLwEbs5GpLfZJUsjC0UzRIntrHHFlGf8F6KsNhW84GoszNX+enywathu /XcY74ivFAk7wWEqW0y5tEvWv7OOXiDZlcASeWgx/hKo+0H9tRFb2TiHWvyrxLXQEcdt Lepg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=Y6xUIs5h; 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 s16si1813890qkg.237.2020.02.06.09.37.10 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:37:10 -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=Y6xUIs5h; 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]:43424 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl5S-0006ER-7Q for patch@linaro.org; Thu, 06 Feb 2020 12:37:10 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43458) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzq-0006hH-Rz for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:24 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzp-0005ug-KB for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:22 -0500 Received: from mail-wr1-x429.google.com ([2a00:1450:4864:20::429]:37839) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzp-0005mn-Cd for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:21 -0500 Received: by mail-wr1-x429.google.com with SMTP id w15so8200394wru.4 for ; Thu, 06 Feb 2020 09:31:21 -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=ny3WK8pMdlgBlAoYUdqL7k5E1SZb/jHOFqlIQGucr5M=; b=Y6xUIs5hWVoM0LMDBumGmw7SFmqozh4Bbo6rVPQmqjYeJWOpG75nQww3he5bpG3yyn IDRsEz7dn6SVqidsaUU2x2yhlc3tleCepXRiGf4BpUp6/QJwTD5q/U3/4GTFWI4mv+N1 x6a7Qe6//NcHM/r2CxO0xD8MfUuV4UOOUUjNWQVUHl49F3ilWjD6JdAtZkNbjT0L5fpL dfDUCgBcUFaAJZQdaMdPMd3ZMoGKMGuIFeUdG7ULHDtf1xCi4BB4jaQwLpdkQVU8Ocze iqxEDrVD97QNelejlK/WeBgFs8VLDIJeDfsrVwIxWp3PXOq1RcrVbXDWooMSsInXit8L 77kA== 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=ny3WK8pMdlgBlAoYUdqL7k5E1SZb/jHOFqlIQGucr5M=; b=oU/mAFZCF77Od/kx5cObIrLQh1qfSoPBxSQsiEoXLZn5N2mqj9ih71liLK1MyrJvs/ Ssnedngk8HdiuHNvhvsheyME/ocnlvySlTCGoqYTPgv4zgdDNoYrw1oOFvk8dj4mrK/z 5wt3w7WmZBAO5bZKu41aS4hMVp7ZG/UYd7brSBoLaN2Nji9NDQVNnRkL0dPFSm7kWOAz Dd2XiPGkiUFwVpKJScHONtNSGowML0U5GmDrtlAAM6vbgQ5F6HJKtwJiWhlsYGxVEN+S 9zghjO5fvQfZ4NIEXoTcyQ5BNpiHMBYPHa04+AMNzERzVQepKKRy7RMBQxM1pr/xS7h/ W09w== X-Gm-Message-State: APjAAAWegsZOH3uEu2+u4ibTxxGWbOpflhKLuRKp4+WZg18swPjUfWrF 9/oumVa1u6Y2QZQOs+z6gaSeYpsApaM= X-Received: by 2002:adf:f0ca:: with SMTP id x10mr5036186wro.423.1581010277659; Thu, 06 Feb 2020 09:31:17 -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.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:16 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 12/29] qapi: Explicitly put "foo: dropped in n.n" notes into Notes section Date: Thu, 6 Feb 2020 17:30:23 +0000 Message-Id: <20200206173040.17337-13-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::429 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 handful of QAPI doc comments include lines like "ppcemb: dropped in 3.1". The doc comment parser will just put these into whatever the preceding section was; sometimes that's "Notes", and sometimes it's some random other section, as with "NetClientDriver" where the "'dump': dropped in 2.12" line ends up in the "Since:" section. Put all of these explicitly into Notes: sections (either preexisting or new), with the right indentation, and standardising on quoting of the symbol with ''. In the case of QKeyCode, the generated docs were actively misformatted: ac_bookmarks since 2.10 altgr, altgr_r: dropped in 2.10 Signed-off-by: Peter Maydell --- qapi/machine.json | 2 +- qapi/net.json | 6 +++--- qapi/ui.json | 3 ++- 3 files changed, 6 insertions(+), 5 deletions(-) -- 2.20.1 diff --git a/qapi/machine.json b/qapi/machine.json index 704b2b0fe31..51ffa96be98 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -20,7 +20,7 @@ # prefix to produce the corresponding QEMU executable name. This # is true even for "qemu-system-x86_64". # -# ppcemb: dropped in 3.1 +# 'ppcemb': dropped in 3.1 # # Since: 3.0 ## diff --git a/qapi/net.json b/qapi/net.json index 109eff71cd4..8fbcbc611b9 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -447,7 +447,7 @@ # # Since: 2.7 # -# 'dump': dropped in 2.12 +# Notes: 'dump': dropped in 2.12 ## { 'enum': 'NetClientDriver', 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde', @@ -464,7 +464,7 @@ # # Since: 1.2 # -# 'l2tpv3' - since 2.1 +# Notes: 'l2tpv3' - since 2.1 ## { 'union': 'Netdev', 'base': { 'id': 'str', 'type': 'NetClientDriver' }, @@ -494,7 +494,7 @@ # # Since: 1.2 # -# 'vlan': dropped in 3.0 +# Notes: 'vlan': dropped in 3.0 ## { 'struct': 'NetLegacy', 'data': { diff --git a/qapi/ui.json b/qapi/ui.json index 94a07318f55..6da52b81143 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -776,7 +776,6 @@ # @ac_forward: since 2.10 # @ac_refresh: since 2.10 # @ac_bookmarks: since 2.10 -# altgr, altgr_r: dropped in 2.10 # # @muhenkan: since 2.12 # @katakanahiragana: since 2.12 @@ -790,6 +789,8 @@ # # Since: 1.3.0 # +# Notes: - 'altgr': dropped in 2.10 +# - 'altgr_r': dropped in 2.10 ## { 'enum': 'QKeyCode', 'data': [ 'unmapped', From patchwork Thu Feb 6 17:30:24 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183119 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1842463ile; Thu, 6 Feb 2020 09:42:45 -0800 (PST) X-Google-Smtp-Source: APXvYqw7ogQoEe7F6qr+L873lzXbd+fExNwbtQrwCl/2uAOV5vBvhGSlT4wsxFiIqmkUZhO4J+/B X-Received: by 2002:ac8:134b:: with SMTP id f11mr3751176qtj.336.1581010965067; Thu, 06 Feb 2020 09:42:45 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010965; cv=none; d=google.com; s=arc-20160816; b=R4YS0SpiYel0Yp4pDh7JyP0CyjcUjiZS+SolVbCihqqhUGZBiFfwqcg0bFOEO9ek2s yGA9yOi92EiX8cFeNPN5hLPrFqEC8NS6BiiYuq8E/khjp3XXJScQ4GAzK02uJlqYW6ps OimEc2fXK/S8iztGRNm6RRuFblnoVrfVcbXlq26YQGDqao0y1Hv8w/1PutJ+oZfZwfHY JDA7iufqgAIoa/qgMzBy0iCw8Pkgg8SXYPv+MP+Y+x4lImrJ3UVFVHUFJ7WSE9mVwgMP lxWV00KNzZvxFFaFhWuwZ0liC9FuGnhVEg310U70VKxltowCj3PUSpQOVTSdXhm+DeIJ 2Z4w== 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=m5b9v0wuyKNqpWeOyE8xHUhMyipBnsQwnLNyYq9bu2Y=; b=UQN2cTnsqm9BIinmUbtkQRf9ojOFDLMj///hH8T081iJiuiGQdfXyrGL4BTsGvo2yb y41wrqd8MXXKPEYxH4bkkD/XB9YLmELYLCY107a1N7fEwWQsL/4+iPQkBnPB/69uN2Hb BJhiAafWjH4VUp8X0kt6dULgSu/5+P/AEfUpb/mQNBSf5YzCwF6aNmC0xa3B8J/qItvn JeEV14NtXy/uXkThAmuOJ2J83YliD2w9gqsSHdtxF+8yf6igWRa5ReJ6fY31r/ur4Cf9 6MRSy5cQ5Tlt943KHJlcH7bwt+Ko8MLVZoKQ5mrEoZtODN8t8Q/P01rl5Ot5TAe1I7xt PQ0g== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=NHlsM+6G; 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 d2si1853420qkk.57.2020.02.06.09.42.44 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:42:45 -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=NHlsM+6G; 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]:43602 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlAq-0000FD-Fk for patch@linaro.org; Thu, 06 Feb 2020 12:42:44 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43455) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzq-0006gn-LL for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:23 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzp-0005u0-DG for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:22 -0500 Received: from mail-wr1-x443.google.com ([2a00:1450:4864:20::443]:36304) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzp-0005pG-1s for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:21 -0500 Received: by mail-wr1-x443.google.com with SMTP id z3so8228132wru.3 for ; Thu, 06 Feb 2020 09:31:20 -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=m5b9v0wuyKNqpWeOyE8xHUhMyipBnsQwnLNyYq9bu2Y=; b=NHlsM+6GKSfqkkIZs/4+vH/wpV1UgzEoUMaEzfX+Xn82TVAneYAqk/tP8MbED6IOb5 fU1zA2qJQO2a3npsfqeYM8x/xmGwxRMHgdT7QPDo6/zhCQ4p9jGVy/G/7Hs2IIXAKIlQ TNtpcnsrs+Yl/NQh8RIatMNxt42iG2b8P42gBmla5x4zYfnjwJpDq76xkglDtnXtyBtw Bp8qHYFm0QE3QQcmoyQ9uJd0Xu7g65reuHRDqMEhlGqskGeOHf3ay/CKUuvtVZOreSEk AVgIsB8BQpo3KfEqKaktziMLXAmI1hpFLeJNz6/26hjcMuQJVOPHtdnvTddFjZfSsGCa XUJQ== 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=m5b9v0wuyKNqpWeOyE8xHUhMyipBnsQwnLNyYq9bu2Y=; b=hkeu7OfpgULivdqRaElw96L2S+NV5AiI3F8ecB3MZLomhK7nl5bMqZiRET/41I0Bd3 8iRWT5gsQKKkTbQ6Crxua+iG9bHdEQRcb0SZHeJNKqtZVH94DAVxxvhklXEeupzBE4SA WqkRPK3zqd4KpDdqOwdVxvLal7aJF5jzsSOJHGUgmvEmewmXZH9pf2c7zCOqGTXNVODS zDGwl29JKyJqvImzfNJ+YMWkAN+4NahaRzSS6sxh0m1DRjIO0fvhh1qi63f238SqZ6Fi Hfu5RuaNIhYeoU1gFRk78ZvEqC0g47PvcdCHbLdB05ethOGdF3j0grt0ZLhDf7m+y9j6 CWhQ== X-Gm-Message-State: APjAAAVQd8b9JN3dc687HYVtviMJmRZz8YIi3LHXhZXJRf5u/qIF0JVi b8wg1yASqJOgI8dxLBjbQouXEWzENOU= X-Received: by 2002:adf:f10a:: with SMTP id r10mr4940464wro.202.1581010279331; Thu, 06 Feb 2020 09:31:19 -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.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:18 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 13/29] qapi/ui.json: Avoid `...' texinfo style quoting Date: Thu, 6 Feb 2020 17:30:24 +0000 Message-Id: <20200206173040.17337-14-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::443 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" Avoid texinfo style quoting with `...', because rST treats it as a syntax error. Use '...' instead, as we do in other doc comments. This looks OK in texinfo, and rST formats it as paired-quotation-marks. Signed-off-by: Peter Maydell --- qapi/ui.json | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) -- 2.20.1 Reviewed-by: Markus Armbruster diff --git a/qapi/ui.json b/qapi/ui.json index 6da52b81143..92d409c32c8 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -12,16 +12,16 @@ # # Sets the password of a remote display session. # -# @protocol: `vnc' to modify the VNC server password -# `spice' to modify the Spice server password +# @protocol: 'vnc' to modify the VNC server password +# 'spice' to modify the Spice server password # # @password: the new password # # @connected: how to handle existing clients when changing the -# password. If nothing is specified, defaults to `keep' -# `fail' to fail the command if clients are connected -# `disconnect' to disconnect existing clients -# `keep' to maintain existing clients +# password. If nothing is specified, defaults to 'keep' +# 'fail' to fail the command if clients are connected +# 'disconnect' to disconnect existing clients +# 'keep' to maintain existing clients # # Returns: Nothing on success # If Spice is not enabled, DeviceNotFound @@ -43,16 +43,16 @@ # # Expire the password of a remote display server. # -# @protocol: the name of the remote display protocol `vnc' or `spice' +# @protocol: the name of the remote display protocol 'vnc' or 'spice' # # @time: when to expire the password. -# `now' to expire the password immediately -# `never' to cancel password expiration -# `+INT' where INT is the number of seconds from now (integer) -# `INT' where INT is the absolute time in seconds +# 'now' to expire the password immediately +# 'never' to cancel password expiration +# '+INT' where INT is the number of seconds from now (integer) +# 'INT' where INT is the absolute time in seconds # # Returns: Nothing on success -# If @protocol is `spice' and Spice is not active, DeviceNotFound +# If @protocol is 'spice' and Spice is not active, DeviceNotFound # # Since: 0.14.0 # From patchwork Thu Feb 6 17:30:25 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183114 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1840506ile; Thu, 6 Feb 2020 09:40:50 -0800 (PST) X-Google-Smtp-Source: APXvYqyVV/ZYOrRbSEABM4d2OUxdYzGl/GTNqExBHLoJSthnFnLcDIoQK1xkAaeGxv0c3mmAHIkg X-Received: by 2002:a37:8e03:: with SMTP id q3mr3465267qkd.395.1581010850885; Thu, 06 Feb 2020 09:40:50 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010850; cv=none; d=google.com; s=arc-20160816; b=s9oobxxToYi+6OBzqo8wynZJE5xhvi5fAyiiO3oYZuhEI51DqU04UAH5gptOEYdCpd pK2D72/ko8WrW6WopmWSBNXrMOhyiDRlEV40iDcfZzXqdfnMkmINyWV3bcHRs0VFegwc 0WJUiRtONBl87EFdqZhnxUEg65yo1K9uQS/fcqMo/hfg51cqbVq7ShxOrOyTYBoL05V4 +lVDsB0qK9ZnAgVfhD3E8MFxjnRyYNrXS1quxgWhdInp+WpugyXzvHTJ1Y3jMpWTms6B 4b1qWZCUcoXj/6yoAfRAG3vXdq5g0HKlolH2yFaPHzMlJwT9Hxa1lRSzDYeOGzwKYy6f 2EvA== 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=nZ0b4zym0no5ijQS0lkSAYODxVV1330DBhgaT3Ed+mE=; b=AVsGRr6H+UwvMKNVUo06xPKAC6qRIVJSQOz/DETZaJWk8a6r/RK/vb1RLFh83TYz3f fnTpmILWpg4ehSeSqOh9FQpCP0DRMWGENd7L7czTE7xC/+YM1yCoDG+ODGBIxnS73Wsp oEyc6wScwjjvDgZ1pkGMbLu5IstDNYNW8+Mk+B9NPhYYHVb7/3NfH6UgwJ1+WPBCD2J2 +bO4Lr5aU3w4pAB2hvDfEczS5qT8AiCmtc69YqW/wlpLAvBPnyOhj7q0XGkZQbnEdzjp 55mcHofcBmhBFER0wDpIdXffHVbgi6eIu+rW3uO5G0Wca3hUy+IcyhhDJENPw6IqNUof jHBQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=yPAveYaI; 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 f15si57234qte.338.2020.02.06.09.40.50 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:40:50 -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=yPAveYaI; 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]:43536 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl90-0004pR-D9 for patch@linaro.org; Thu, 06 Feb 2020 12:40:50 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43484) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzt-0006jq-7Y for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:27 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzr-00061X-2s for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:25 -0500 Received: from mail-wm1-x335.google.com ([2a00:1450:4864:20::335]:53741) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzq-0005xJ-PZ for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:22 -0500 Received: by mail-wm1-x335.google.com with SMTP id s10so881402wmh.3 for ; Thu, 06 Feb 2020 09:31:22 -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=nZ0b4zym0no5ijQS0lkSAYODxVV1330DBhgaT3Ed+mE=; b=yPAveYaIYMNLRnQpXSNl/bGS8E56iiM2YhzA8Z5NsKLJeqJ/HfHIehlH/vPvDZLWKl rdAL6xqwT6jLL55+lLLQ+VLtj0p1MY/npaDikF39r3K2l9grGcrnNk2+z7+Lu6YKDw60 EZCfqnbf4E2VuKit0sPGolIeOk8sup36zMV5Cl3OUHAvQywMh6A8+TLLounTafE8aKDb rQR5Ttf/1a/WbMOy8C9rKVYQFAaNWeyJvnZmplH2aOomX9LK+PrDFKGmDkTA7/CzthDA 8pbFPODs+J0Ye4j4n3NdpDmYDBQvZiOVuWgpgjuiPQd4GpFCeLSpDI76cV1mbEW99Oh4 4w/A== 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=nZ0b4zym0no5ijQS0lkSAYODxVV1330DBhgaT3Ed+mE=; b=IywD4JY8Iiq/T44YULaUT5u+ojULDLqVepz9us07FP3eLHp40e8gjh5kXsoaSQRyZT pGkaCicCLnM1NXqY5Dd9N545nI/f/v9VV2+fzccmpOzrrBqUfdjLLyBBY421op6pjFi5 F6Yko/voSHQdB5lwPSjoOGW9gbGZhEmfX1Ig0lYTLCPeIywYXp369OklEqUSS1Te5EAp abA01+g4uVmofbtFm6mrFfHFENz6jrJ696P52DLGV0UHEPXQMzESUweabjET2YCD9mJY MF3tL7JbGbQr25LFDtcnnO6Yih+7tsiTjIHc4MMOBpqcFnp6Ly4TaLKrPZImrtsorgcD buQg== X-Gm-Message-State: APjAAAXFiSRgPu9KmbCpjcAvuVskEDx+wGJKErvc++Q10TNKSetllPOz 8n+7ekKx8fyl1FqQPZcZoaDiGotTx9s= X-Received: by 2002:a05:600c:2207:: with SMTP id z7mr5784425wml.138.1581010281046; Thu, 06 Feb 2020 09:31:21 -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.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:20 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 14/29] qapi/block-core.json: Use explicit bulleted lists Date: Thu, 6 Feb 2020 17:30:25 +0000 Message-Id: <20200206173040.17337-15-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::335 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. Signed-off-by: Peter Maydell --- qapi/block-core.json | 108 +++++++++++++++++++++---------------------- 1 file changed, 54 insertions(+), 54 deletions(-) -- 2.20.1 Reviewed-by: Markus Armbruster diff --git a/qapi/block-core.json b/qapi/block-core.json index 6cc8a4f73e0..9e878e39336 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1326,8 +1326,8 @@ # # @size: new image size in bytes # -# 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 # # Since: 0.14.0 # @@ -1510,8 +1510,8 @@ # # For the arguments, see the documentation of BlockdevSnapshotSync. # -# 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 # # Since: 0.14.0 # @@ -1586,9 +1586,8 @@ # when specifying the string or the image chain may # not be able to be reopened again. # -# Returns: Nothing on success -# -# If "device" does not exist or cannot be determined, DeviceNotFound +# Returns: - Nothing on success +# - If "device" does not exist or cannot be determined, DeviceNotFound # # Since: 2.1 ## @@ -1674,9 +1673,9 @@ # list without user intervention. # Defaults to true. (Since 3.1) # -# Returns: Nothing on success -# If @device does not exist, DeviceNotFound -# Any other error returns a GenericError. +# Returns: - Nothing on success +# - If @device does not exist, DeviceNotFound +# - Any other error returns a GenericError. # # Since: 1.3 # @@ -1704,8 +1703,8 @@ # The operation can be stopped before it has completed using the # block-job-cancel command. # -# Returns: nothing on success -# If @device is not a valid block device, GenericError +# Returns: - nothing on success +# - If @device is not a valid block device, GenericError # # Since: 1.6 # @@ -1730,8 +1729,8 @@ # The operation can be stopped before it has completed using the # block-job-cancel command. # -# 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 # # Since: 2.3 # @@ -1925,8 +1924,8 @@ # format of the mirror image, default is to probe if mode='existing', # else the format of the source. # -# Returns: nothing on success -# If @device is not a valid block device, GenericError +# Returns: - nothing on success +# - If @device is not a valid block device, GenericError # # Since: 1.3 # @@ -2097,9 +2096,9 @@ # # Create a dirty bitmap with a name on the node, and start tracking the writes. # -# Returns: nothing on success -# If @node is not a valid block device or node, DeviceNotFound -# If @name is already taken, GenericError with an explanation +# Returns: - nothing on success +# - If @node is not a valid block device or node, DeviceNotFound +# - If @name is already taken, GenericError with an explanation # # Since: 2.4 # @@ -2120,10 +2119,10 @@ # with block-dirty-bitmap-add. If the bitmap is persistent, remove it from its # storage too. # -# Returns: nothing on success -# If @node is not a valid block device or node, DeviceNotFound -# If @name is not found, GenericError with an explanation -# if @name is frozen by an operation, GenericError +# Returns: - nothing on success +# - If @node is not a valid block device or node, DeviceNotFound +# - If @name is not found, GenericError with an explanation +# - if @name is frozen by an operation, GenericError # # Since: 2.4 # @@ -2144,9 +2143,9 @@ # backup from this point in time forward will only backup clusters # modified after this clear operation. # -# Returns: nothing on success -# If @node is not a valid block device, DeviceNotFound -# If @name is not found, GenericError with an explanation +# Returns: - nothing on success +# - If @node is not a valid block device, DeviceNotFound +# - If @name is not found, GenericError with an explanation # # Since: 2.4 # @@ -2165,9 +2164,9 @@ # # Enables a dirty bitmap so that it will begin tracking disk changes. # -# Returns: nothing on success -# If @node is not a valid block device, DeviceNotFound -# If @name is not found, GenericError with an explanation +# Returns: - nothing on success +# - If @node is not a valid block device, DeviceNotFound +# - If @name is not found, GenericError with an explanation # # Since: 4.0 # @@ -2186,9 +2185,9 @@ # # Disables a dirty bitmap so that it will stop tracking disk changes. # -# Returns: nothing on success -# If @node is not a valid block device, DeviceNotFound -# If @name is not found, GenericError with an explanation +# Returns: - nothing on success +# - If @node is not a valid block device, DeviceNotFound +# - If @name is not found, GenericError with an explanation # # Since: 4.0 # @@ -2215,11 +2214,11 @@ # of the source bitmaps. This can be used to achieve backup checkpoints, or in # simpler usages, to copy bitmaps. # -# Returns: nothing on success -# If @node is not a valid block device, DeviceNotFound -# If any bitmap in @bitmaps or @target is not found, GenericError -# If any of the bitmaps have different sizes or granularities, -# GenericError +# Returns: - nothing on success +# - If @node is not a valid block device, DeviceNotFound +# - If any bitmap in @bitmaps or @target is not found, GenericError +# - If any of the bitmaps have different sizes or granularities, +# GenericError # # Since: 4.0 # @@ -2251,10 +2250,10 @@ # # Get bitmap SHA256. # -# Returns: BlockDirtyBitmapSha256 on success -# If @node is not a valid block device, DeviceNotFound -# If @name is not found or if hashing has failed, GenericError with an -# explanation +# Returns: - BlockDirtyBitmapSha256 on success +# - If @node is not a valid block device, DeviceNotFound +# - If @name is not found or if hashing has failed, GenericError with an +# explanation # # Since: 2.10 ## @@ -2371,8 +2370,8 @@ # the device will be removed from its group and the rest of its # members will not be affected. The 'group' parameter is ignored. # -# 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 # # Since: 1.1 # @@ -2622,7 +2621,8 @@ # list without user intervention. # Defaults to true. (Since 3.1) # -# Returns: Nothing on success. If @device does not exist, DeviceNotFound. +# Returns: - Nothing on success. +# - If @device does not exist, DeviceNotFound. # # Since: 1.1 # @@ -2656,8 +2656,8 @@ # @speed: the maximum speed, in bytes per second, or 0 for unlimited. # Defaults to 0. # -# Returns: Nothing on success -# If no background operation is active on this device, DeviceNotActive +# Returns: - Nothing on success +# - If no background operation is active on this device, DeviceNotActive # # Since: 1.1 ## @@ -2696,8 +2696,8 @@ # abandon the job immediately (even if it is paused) instead of waiting # for the destination to complete its final synchronization (since 1.3) # -# Returns: Nothing on success -# If no background operation is active on this device, DeviceNotActive +# Returns: - Nothing on success +# - If no background operation is active on this device, DeviceNotActive # # Since: 1.1 ## @@ -2720,8 +2720,8 @@ # the name of the parameter), but since QEMU 2.7 it can have # other values. # -# Returns: Nothing on success -# If no background operation is active on this device, DeviceNotActive +# Returns: - Nothing on success +# - If no background operation is active on this device, DeviceNotActive # # Since: 1.3 ## @@ -2742,8 +2742,8 @@ # the name of the parameter), but since QEMU 2.7 it can have # other values. # -# Returns: Nothing on success -# If no background operation is active on this device, DeviceNotActive +# Returns: - Nothing on success +# - If no background operation is active on this device, DeviceNotActive # # Since: 1.3 ## @@ -2770,8 +2770,8 @@ # the name of the parameter), but since QEMU 2.7 it can have # other values. # -# Returns: Nothing on success -# If no background operation is active on this device, DeviceNotActive +# Returns: - Nothing on success +# - If no background operation is active on this device, DeviceNotActive # # Since: 1.3 ## From patchwork Thu Feb 6 17:30:26 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183118 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1842306ile; Thu, 6 Feb 2020 09:42:35 -0800 (PST) X-Google-Smtp-Source: APXvYqy7MBY+E1jtSb6nU/1DluTpR4/0qDoaWGqTnAqTa205Oxv7xFMusBjVl1YLXusq9PHxu9tq X-Received: by 2002:ac8:6759:: with SMTP id n25mr3798414qtp.226.1581010955351; Thu, 06 Feb 2020 09:42:35 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010955; cv=none; d=google.com; s=arc-20160816; b=y+gj7w7dRO7uZLRclLpMKRvhFccEdbtXjPBPVEwLIaScJGvI6wMasISyMLNjjOf+dO Gz8+AjqrI1OsJY7z0lxw7/Y/4ZdlrsKTUA+AJwZUU6V8jkfWUPFIKKv8HtZ88Ah7XYPJ I787I9ZgF5YPI0IX/ldSapQtSIF9hxC5381NldpM+9Ukxvmlw4gsvpCkRO56A2htFBOB GJuGoQ+dJ7/n4/6vaoOfAJYiK6BUOmQ79BXHfAW5DW5uh09PX5sHqnUo3jQjpfKcEv7c LTaIlV4c+Kpm8JI+eYhzvhlvU7+AEUGt91reClJ65nKRunZyj1IPs0hP6hV/GfG0i+fP HzPA== 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=GvBOG5pDxbUJVtePJMB2qE/bWoG9oTyZ0L26Rr3bxAo=; b=bUSqb8ectBbmahHP7biXXxlSsecDSby97h4Htqwxd5W3OUdB5Ceyc+nh1w3Su2ZjXP YisrqQp/Nwd9ZwKGXRmz49PVgnSxpg0HncGWLemzdRANCru5BqGZgKvHXCEA8PiymwvT GX21K7MVAxkGgrM25f6RFSTh2UyZ0VClGoVZX19k6JvxzZkG5++kFypAz6dADv6Y5yBY lsw0RbelpVr3t4Om0ZUv+YegeSlKX1UWzgcz+4W/u3dSK3mmOHT9C2BYBBck1CVROeV2 6IxtsuBA8V2q+WelIcDTrsil/8//5Pt8M3qlR6mIE+h7mFw1J2QMxdGbVR0xWRwRYs11 euiQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="tV33zF9/"; 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 r187si1798042qkb.359.2020.02.06.09.42.35 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:42:35 -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="tV33zF9/"; 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]:43590 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlAg-0008JL-RJ for patch@linaro.org; Thu, 06 Feb 2020 12:42:34 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43529) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izkzz-0006lQ-I6 for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:35 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izkzv-0006IJ-1V for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:30 -0500 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]:39670) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzt-00064u-5P for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:26 -0500 Received: by mail-wr1-x442.google.com with SMTP id y11so8207609wrt.6 for ; Thu, 06 Feb 2020 09:31:24 -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=GvBOG5pDxbUJVtePJMB2qE/bWoG9oTyZ0L26Rr3bxAo=; b=tV33zF9/Gr6SLw1w+P1Ch8ja8VKEeNslcRmhwOXEgmKQCewKKxBwFpGjvJd3PtLPdg hUdWYPeKM6vhkUpINmHj2X4iz7xKjCAZHerqPxETYOg25niyeBJnKpMvr7b2Gs63jPmk UfOsaL1LMfy/pWm3MmM1kn62sAJaxv8WRyrWu1NsL0ryaEOArSZ2ktt9pmdw9ePu+PTc uwNklCyZwlKBRlheR7CXjKJtPsd0SsBdX6d1j7nvVxdMUSFVQKQtfrjLHuPgIj9bopn3 6tY4o5TsaF4VujoSCxzmTWaOdgifjejHowYl/WLV5ImbAVDVuud3VPCpZ/5EvPPzOM77 Zz2g== 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=GvBOG5pDxbUJVtePJMB2qE/bWoG9oTyZ0L26Rr3bxAo=; b=fjVnO31RJQeRYV6UrGuTqmzK97ICesXyWekkmJVA2/mg7h01AMBrA4haX/uGzeTpWj +OVIHMtM+fiIDCQePpNMWCARD6PYyBpBqhpraTrDOWiGLlho3G6PskqTXJl0JVUb0cH2 PSQfhXshtyn9MRKPPzWmrAGiACb58Ah5swxOECJ7eunVkV6Xwf8nydTS/Amd+ShmfeVV oxB9MFjpBphpz0mlTNdUwdLyaBs/0P/7H20HhsytYCa1GBx1k2SxwlAAPBgst+K7DD/B JCXAamNr1WPpL+m7/JERdRaToO2YK6O5Q0JfjKmiC7utLCPGoVTqq+yCP7eewvY8gMWu T/3g== X-Gm-Message-State: APjAAAUe218QJY5F6N8YTKsUEAdVVGWXxlOg+O6z9V8YoLHdBx59qWTp v7qVIfgvH4jP7vfMc14Mv2CcMSB6h2Q= X-Received: by 2002:adf:fd43:: with SMTP id h3mr4820080wrs.169.1581010283004; Thu, 06 Feb 2020 09:31:23 -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.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:22 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 15/29] qapi/ui.json: Use explicit bulleted lists Date: Thu, 6 Feb 2020 17:30:26 +0000 Message-Id: <20200206173040.17337-16-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::442 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. Signed-off-by: Peter Maydell --- qapi/ui.json | 63 +++++++++++++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 30 deletions(-) -- 2.20.1 diff --git a/qapi/ui.json b/qapi/ui.json index 92d409c32c8..f527bbdc26e 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -12,8 +12,8 @@ # # Sets the password of a remote display session. # -# @protocol: 'vnc' to modify the VNC server password -# 'spice' to modify the Spice server password +# @protocol: - 'vnc' to modify the VNC server password +# - 'spice' to modify the Spice server password # # @password: the new password # @@ -23,8 +23,8 @@ # 'disconnect' to disconnect existing clients # 'keep' to maintain existing clients # -# Returns: Nothing on success -# If Spice is not enabled, DeviceNotFound +# Returns: - Nothing on success +# - If Spice is not enabled, DeviceNotFound # # Since: 0.14.0 # @@ -46,13 +46,14 @@ # @protocol: the name of the remote display protocol 'vnc' or 'spice' # # @time: when to expire the password. -# 'now' to expire the password immediately -# 'never' to cancel password expiration -# '+INT' where INT is the number of seconds from now (integer) -# 'INT' where INT is the absolute time in seconds # -# Returns: Nothing on success -# If @protocol is 'spice' and Spice is not active, DeviceNotFound +# - 'now' to expire the password immediately +# - 'never' to cancel password expiration +# - '+INT' where INT is the number of seconds from now (integer) +# - 'INT' where INT is the absolute time in seconds +# +# Returns: - Nothing on success +# - If @protocol is 'spice' and Spice is not active, DeviceNotFound # # Since: 0.14.0 # @@ -201,9 +202,10 @@ # @tls-port: The SPICE server's TLS port number. # # @auth: the current authentication type used by the server -# 'none' if no authentication is being used -# 'spice' uses SASL or direct TLS authentication, depending on command -# line options +# +# - 'none' if no authentication is being used +# - 'spice' uses SASL or direct TLS authentication, depending on command +# line options # # @mouse-mode: The mode in which the mouse cursor is displayed currently. Can # be determined by the client or the server, or unknown if spice @@ -433,27 +435,28 @@ # @host: The hostname the VNC server is bound to. This depends on # the name resolution on the host and may be an IP address. # -# @family: 'ipv6' if the host is listening for IPv6 connections -# 'ipv4' if the host is listening for IPv4 connections -# 'unix' if the host is listening on a unix domain socket -# 'unknown' otherwise +# @family: - 'ipv6' if the host is listening for IPv6 connections +# - 'ipv4' if the host is listening for IPv4 connections +# - 'unix' if the host is listening on a unix domain socket +# - 'unknown' otherwise # # @service: The service name of the server's port. This may depends # on the host system's service database so symbolic names should not # be relied on. # # @auth: the current authentication type used by the server -# 'none' if no authentication is being used -# 'vnc' if VNC authentication is being used -# 'vencrypt+plain' if VEncrypt is used with plain text authentication -# 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication -# 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication -# 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth -# 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth -# 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth -# 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth -# 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth -# 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth +# +# - 'none' if no authentication is being used +# - 'vnc' if VNC authentication is being used +# - 'vencrypt+plain' if VEncrypt is used with plain text authentication +# - 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication +# - 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication +# - 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth +# - 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth +# - 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth +# - 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth +# - 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth +# - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth # # @clients: a list of @VncClientInfo of all currently connected clients # @@ -841,8 +844,8 @@ # @hold-time: time to delay key up events, milliseconds. Defaults # to 100 # -# Returns: Nothing on success -# If key is unknown or redundant, InvalidParameter +# Returns: - Nothing on success +# - If key is unknown or redundant, InvalidParameter # # Since: 1.3.0 # 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 ## From patchwork Thu Feb 6 17:30:28 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183117 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1841195ile; Thu, 6 Feb 2020 09:41:30 -0800 (PST) X-Google-Smtp-Source: APXvYqx/TwPoe5gIkPBl2fr0oPaN2pTU4OBd6g5Y3tAEA3WJlCbCHkpkBMybIhRKQQU24Pk2qIfJ X-Received: by 2002:ae9:e206:: with SMTP id c6mr3661940qkc.105.1581010890083; Thu, 06 Feb 2020 09:41:30 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010890; cv=none; d=google.com; s=arc-20160816; b=TSvv+pM8+POZF+edm55UPDo5ciFQjiSLM0iQ9m38n0eNsTD747bDV65GWAN2pyFHoA D5J+dTtSRFn2h6MUGR8/ubBwgIqY/9EBAunFD9tHWOzjLALLCSw8YKVI2Ji+VA0Rel7u Ct5M0zAU8o1fJRGvjMthSmMgtHeU0iWeCNX60MaUdWJVW9eqvU3nm67aPpev0Zrn7Kr7 NpngZMyEV0oOYNsiUMdTQ4Bq5FsMfgXy1AxCaGcra+LmAFmrxO4nhOGylgpXIUuMirji MsS6wV8gjFbRUXcQHf7T4++C48JX9ORsGXd9vEGu+r7PsjZewOeBoyprLqYXwK6V73i0 m2OQ== 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=8Q3qcfVtQBbM2YwOrLV7NuxogQrx/IXYuo0cjcWYW7M=; b=lujU5uQVIDiiHXD1hgS0B4ti5dlC0ByuI3D61I6Vof++Ta5F8k4o4ykJv4AQcVnmmU chTqykltuxxb/VzcNGHpVVdwfS6SIIZmhnBBOi0QrSwSKS1hjxZKjkX64IE2ZX2uPsLU mhKDSrVxF5mRdBL8JEvtkS9NRYnqJ2D9RQe7k6vOlfBx+24HhYnngrj1Kd/v1phGD9iT eupUN9w2zGh9B3x7RLo4FI3eaV8kKzrcHx+eiEYnGyMb4s73VZErOfvEgkvp2lIecv9T Ex21taXwsfrk6gY33Yu/Q9jKb8ve69fyUzj2iKOwGtfG8BJCbx6bOBo8hn3P8fWEbG7N 1/Fg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="Hc/R2JNs"; 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 1si1955654qkc.260.2020.02.06.09.41.30 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:41:30 -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="Hc/R2JNs"; 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]:43556 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl9d-0005nY-I1 for patch@linaro.org; Thu, 06 Feb 2020 12:41:29 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43572) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl05-0006o9-C4 for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:39 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl01-0006cV-L5 for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:37 -0500 Received: from mail-wr1-x42f.google.com ([2a00:1450:4864:20::42f]:33091) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izkzy-0006GT-Qa for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:31 -0500 Received: by mail-wr1-x42f.google.com with SMTP id u6so8240253wrt.0 for ; Thu, 06 Feb 2020 09:31:27 -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=8Q3qcfVtQBbM2YwOrLV7NuxogQrx/IXYuo0cjcWYW7M=; b=Hc/R2JNsdYlv7+ZPYvbd3MSd4KU3dDiu0mQTAw/VnmRWvO88hwjmWMUj+dagJ5TCRi vXpc3rmg7+h/MRr0cPcZiHcnMwUrp7K7QEtkDYTo4OjiHgsz43jgo/ZKQanSxNxG0Byn V2Sjn7iUKAkoZOP8CDGBWkWVc4thOO0dz780/d79IU2W+b8L95XtDLxQ5BtedGbs3TyP 4MxeEzFQE1o61HQN9vpBfcHuZ8uup4X7MWwL3i0G7ha9cb86ZBCf33ipftIoy3MKvj8W KTyVXqYNQgF0DWMT+0Ukq97t9iwDMwon+sMaG0vir5LYMcXQMckyaaE7Yz8hnZHMnrEc pWNQ== 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=8Q3qcfVtQBbM2YwOrLV7NuxogQrx/IXYuo0cjcWYW7M=; b=RiB3blWlZz54t4Tb0ohqV1VbjeeS+BgeXU1tHqOWd5bE3pFXO9U9TOlmm+UJQQJt89 IiRZPmjKk40LuSyzaXItc71swheXdC/ZdUN3bXcfd2Kis1oUv40rbF1FP31fh0Q7P4/a tkQ4hX3AGKEOOrp/m6LPu5a4FOh+0FFmMbqfj2d0/TTITZjoHRycNoAcf2o+BGNqJR6n cldrXqapICr2uxqPDPK3AfBoqfvdIH16a3e+7hC4k6Cmxa4x6lrrwox98RzQosHZVuCe /TJ8TsL3Q0MIv+BzCNur0WtKgyCzUR0Edbo3ax0fCSElyd8/9czQwW5F9TIZdqPiW+kz xZAA== X-Gm-Message-State: APjAAAWRmIkEqVOB5mVZsc9DqIzdkwDYDHM9pWvyOf6NSA0f/zJOEB+P vUn9Y5So2Oq2WH1h1Zf+asLWv38HWGY= X-Received: by 2002:a5d:5752:: with SMTP id q18mr5049287wrw.277.1581010285881; Thu, 06 Feb 2020 09:31:25 -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.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:25 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 17/29] qapi: Add blank lines before bulleted lists Date: Thu, 6 Feb 2020 17:30:28 +0000 Message-Id: <20200206173040.17337-18-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::42f 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" rST insists on a blank line before and after a bulleted list, but our texinfo doc generator did not. Add some extra blank lines in the doc comments so they're acceptable rST input. Signed-off-by: Peter Maydell --- qapi/block-core.json | 1 + qapi/char.json | 2 ++ qapi/trace.json | 1 + qapi/ui.json | 1 + 4 files changed, 5 insertions(+) -- 2.20.1 Reviewed-by: Philippe Mathieu-Daudé diff --git a/qapi/block-core.json b/qapi/block-core.json index 9e878e39336..092cd8f13d9 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -4757,6 +4757,7 @@ # # Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in # which no such event will be generated, these include: +# # - if the guest has locked the tray, @force is false and the guest does not # respond to the eject request # - if the BlockBackend denoted by @device does not have a guest device attached diff --git a/qapi/char.json b/qapi/char.json index 8a9f1e75097..6907b2bfdba 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -133,6 +133,7 @@ # @data: data to write # # @format: data encoding (default 'utf8'). +# # - base64: data must be base64 encoded text. Its binary # decoding gets written. # - utf8: data's UTF-8 encoding is written @@ -167,6 +168,7 @@ # @size: how many bytes to read at most # # @format: data encoding (default 'utf8'). +# # - base64: the data read is returned in base64 encoding. # - utf8: the data read is interpreted as UTF-8. # Bug: can screw up when the buffer contains invalid UTF-8 diff --git a/qapi/trace.json b/qapi/trace.json index 4955e5a7503..47c68f04da7 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -53,6 +53,7 @@ # Returns: a list of @TraceEventInfo for the matching events # # An event is returned if: +# # - its name matches the @name pattern, and # - if @vcpu is given, the event has the "vcpu" property. # diff --git a/qapi/ui.json b/qapi/ui.json index f527bbdc26e..b368401fd1d 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -935,6 +935,7 @@ # Input event union. # # @type: the input type, one of: +# # - 'key': Input event of Keyboard # - 'btn': Input event of pointer buttons # - 'rel': Input event of relative pointer motion From patchwork Thu Feb 6 17:30:29 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183123 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1842698ile; Thu, 6 Feb 2020 09:42:57 -0800 (PST) X-Google-Smtp-Source: APXvYqyaO+TxWQ9/n5tkX22BLEKEIAkYvXGMEzM8R1gdiPPlYmjjPWGVFLIRxeLlQIlDX55eWTUS X-Received: by 2002:a0c:fa4b:: with SMTP id k11mr3297349qvo.55.1581010977520; Thu, 06 Feb 2020 09:42:57 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010977; cv=none; d=google.com; s=arc-20160816; b=bSuVggA+bHCoSknqHU30G6wPfQ+tRJT2ur3HTZ5FmeRMXlZ2oJr/kmY8Yl7qGbYfeY +SZQR/Qync7DmcS0ZM5mANySAT4XzkJNaB0miAOk5EVbR+CBlgvfWOIXy3GMKMFyrLZ8 RcEkwur0AYSl2cGnzY4cEm5+4+3SVuZPqISDqJM11Nda+7fzEyo7zY3HpF7GUVF3E3/O G0gw/h4lEMBQzpq6Bro1gXrh3NYrK62noO37shnellEk0bbSv7F9LQxlmocYeQwTdTO9 FOGAGrIBW7qjpn87a0sN54cQJGjGREVkprht9+LwKio1NzSO1PSog/KbquZihbllS6Yk JLJQ== 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=/klYbU+bqniRP71Sh9fNzl1GvlwCTSWPu2kdq/jHKgU=; b=TjV33iVzhc1NEQ1LZnpp9dkLT/XUoQuVQys6HtzgXqXv4A4wBb6tqW4c7EkFh8OoWM QtHK4v4qQww9JDeaNFkHRPR2Daq8sRlQsFjc9Xd0uGUvclipr65PO4YM+7R50TxbDZ6g pPzsOkk4SKmo6fvHy0LUOUCjGAX17cpO0Fw2TItEfy6E0pB942SvQsLxqoRmVPNxU1/G /i7htd4Lk+QVyqwSU+FKR16iqpapqLmxjyxtUwDo4n6NijfhD5lE7/qVocdvg+BUjKF1 sH7jT48PgQsKPddACH0u15GOs9+C3Vo3I+Q9gryhmWWWOw1dKS+RUMsyIHmCb9zgpZDM Lpng== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=iH4cPz1h; 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 p43si75773qte.122.2020.02.06.09.42.57 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:42:57 -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=iH4cPz1h; 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]:43606 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlB3-0000O9-0Y for patch@linaro.org; Thu, 06 Feb 2020 12:42:57 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43595) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl06-0006oZ-5W for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:39 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl03-0006g3-EU for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:38 -0500 Received: from mail-wm1-x32f.google.com ([2a00:1450:4864:20::32f]:37717) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izl01-0006OA-KV for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:35 -0500 Received: by mail-wm1-x32f.google.com with SMTP id f129so997547wmf.2 for ; Thu, 06 Feb 2020 09:31:31 -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=/klYbU+bqniRP71Sh9fNzl1GvlwCTSWPu2kdq/jHKgU=; b=iH4cPz1hfm8vkCp9iBLT6jQFV5md2N/TDCJz/BmjO8Qt+XCeemB4iSagE4yAiyYgAv v+XAfAJNvfxiIEbn47UL57kGhJMy/WBAZf01QXtPyH2sugVCvij6BU00/wH99jgk7Bvt 03tEXWnOTRltbk70EurgeIhDhrte/nOKiLNtqaeVaJo2W6zBEaceHwqBHfH8Q0rN8QEU /jQsVSak+QD5K9623FGpOJ3YEDWHE6d0vQFHuxmZquzMFzc1qArXHo5tUbxGn5BBtFdq t8Vwu5DvXaU+iGmRaOPI4PrBXquFFu6THk4ZvVdB1KLWi5k3C6bbZKXsL2es8sqJ3IC9 HdIQ== 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=/klYbU+bqniRP71Sh9fNzl1GvlwCTSWPu2kdq/jHKgU=; b=ehHVR1Bt72Sx8vz3M8TZL2zP+8B67uwndywG+FKRfPsU/8AfYzfVVnO/zvGP2m5V4U Vx9MRpEHI8DhUFKaiBXG68kJl/8ptIOqnJmhBjomCKOQru0apY5v2c0/APVXBG8XUJTA fzMYh9gZq5wnf78TEjRXAkiizkjUwwgFJzf3JsyuS76ZikuLBNx9F2mg4tzOK4NndU14 329Q7kiGKvdcdkboPVRaXOVGYkAMJftt9Q+5OYY0TqRXWoLwD9H01UcTRk4JI8a7/cbx 7yy5CHLgS8CHKH/lj4UAInKBNkohYZQe8H/4AjYZH68us5gB0nYR9x8Y0hJ/ftlGqUNg eldA== X-Gm-Message-State: APjAAAVwcGWyyvT+4RTSIyaSqWT4MikIjqjr51sq+J/kfu6aD8WT9jm7 NwO6+KVFfDcDvfz1NwNOwP1DjjSBLjs= X-Received: by 2002:a1c:a947:: with SMTP id s68mr5805949wme.61.1581010287744; Thu, 06 Feb 2020 09:31:27 -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.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:26 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 18/29] qapi/migration.json: Replace _this_ with *this* Date: Thu, 6 Feb 2020 17:30:29 +0000 Message-Id: <20200206173040.17337-19-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::32f 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" The MigrationInfo::setup-time documentation is the only place where we use _this_ inline markup to mean italics. rST doesn't recognize that markup and emits literal underscores. Switch to *this* instead; for the texinfo output this will be bold, and for rST it will go back to being italics. Signed-off-by: Peter Maydell --- qapi/migration.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) -- 2.20.1 Reviewed-by: Markus Armbruster diff --git a/qapi/migration.json b/qapi/migration.json index 11033b7a8e6..52f34299698 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -178,8 +178,8 @@ # expected downtime in milliseconds for the guest in last walk # of the dirty bitmap. (since 1.3) # -# @setup-time: amount of setup time in milliseconds _before_ the -# iterations begin but _after_ the QMP command is issued. This is designed +# @setup-time: amount of setup time in milliseconds *before* the +# iterations begin but *after* the QMP command is issued. This is designed # to provide an accounting of any activities (such as RDMA pinning) which # may be expensive, but do not actually occur during the iterative # migration rounds themselves. (since 1.6) From patchwork Thu Feb 6 17:30:30 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183122 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1842669ile; Thu, 6 Feb 2020 09:42:55 -0800 (PST) X-Google-Smtp-Source: APXvYqxjd7/ZFRLqNamZbc56S3lW9EDa5sOnJvsIGPXJf6SkDLmtn4A36QqotlxlnaE6QMzbJxU+ X-Received: by 2002:a05:6214:190e:: with SMTP id er14mr3402011qvb.28.1581010975446; Thu, 06 Feb 2020 09:42:55 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010975; cv=none; d=google.com; s=arc-20160816; b=VqfDqkVlxQrm9yfYADw29ZwYzYJP7fvTyL3fCZb3+eWSh0t6OuQd2HT4K7RkkYw72e CspSoIvMdmQbBdVy1kiDE7jwIyvSl3EtIe/9ehvPzVO21KfsiFiAVv6nu4Ey7PLkgBKG md11GrQgj0qa47CiQVGFb6DEJ4AUPsvNxxZRztKeVR6EX5kfjA1cBi3M/dV2v0orH+JP bZJHRGPp5m916D6PFVyz4wiz1Q9kE5R4auO/Vpoh7kdcdGz3q6imYE0ouW5AX3Cbl7uD rDLAGg9p7dw73BNURT2tqdsZ//tfDBoRFdO06356xBK/KAXV13vEaHWeGWErcHAFZz5B 0plg== 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=VDdAOmTYkuJE/cPjChu5louQLFg3bC6As6n85BhOPHbGPJUG9bpWcnOdarkgv09WVw umDP6YXj+pt2/e7LB3Fa3DcNbzpoNTJZ4h15POdDoR8MLK5J0/ZAsqkznYcOo4TOSF06 KHI5/Toccd1aB8bWRA7dJ3wcHdMqkc2kjP3RcydDoxfcEn30T8SiXC81ZaQDP8eMWN0z BZMzhx+2JxmQ+3O0/ejX4cK6sHXp0t14GkVIyx0lKy4KXsHpNKizR1vRGYS0K1FKiOU/ DqmySi3p6wtcPp60jAPqQLooqZ3MlcBk38HrbwtXnB6pqPxMJDFAXfEnwG8fkZqMW7fG v82w== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=Bk170GMu; 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 d15si1960514qka.168.2020.02.06.09.42.55 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:42:55 -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=Bk170GMu; 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]:43610 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlB0-0000h1-Vz for patch@linaro.org; Thu, 06 Feb 2020 12:42:55 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43620) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl07-0006om-7H for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:40 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl05-0006oQ-Ap for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:39 -0500 Received: from mail-wm1-x32f.google.com ([2a00:1450:4864:20::32f]:54500) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izl03-0006Ok-DN for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:35 -0500 Received: by mail-wm1-x32f.google.com with SMTP id g1so875613wmh.4 for ; Thu, 06 Feb 2020 09:31:31 -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=Bk170GMuSYlv35NSWPLEMgRLEvUmRHa6JdLzzOElNDAAejvOmCeDkhUL3Esh0UzSpM +hgy/ymKb+PYUSeKkg0fZOxb28yYrtTLK4ecDj33BqLDWN4CGmPVFuZqu+h5wgSXkkNw fkDWmS+1EvYh2JjwBWs93hPB5mVn7GCVqUr5O56CToxytiNZgNUZbGD7kg5TZG2bLKHf 71USd3Arx71gKHjv0xow8PpP5n8tpmuIiP2dXd2/S0LxWK73rm+xVwitG8U4jcx4gnqC 1ttbWqHCCs6grO6sw09n9CV/sVSAXuNQZJblD60dWaj/HstvGv6kbgifzgi6zVocUN81 9yBw== 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=rU5OXLazu7Y6CTAZtq+Bx1j76BAAGV8C4ImGxzVRizSKB5S93ID7/MtNxReJEu5NQa nBCdZnj8StJSZIFMqfCrvgW9Ykjm3qDOpC2jRkdlieGMriJg5jm4prs95nQk+blm9u1L eApFP+i6t4ZNLlF3l8L66fozzTwWOFMgfKIREFXYLpW/DNVtWy5cYOXpeFQYxSDhkPCz 0qhjQkJKkCuUOu5qlWYboLN0ZQY5NW2JYAV1civy2xBSQmROLkNiLk/1LZU3ABg09Mbf Fgtv7JOcmm/zxhW8u5HQUB2TrYV2SID1n2bPA2KZbpS4GnfyC1ziCGfja21HU6/VniFM HMlA== X-Gm-Message-State: APjAAAUlvRcdjMT0LnQmZDxxqRlKMhVHqMmgMoDLlBV0yu7IJwaMF/jy 4RKp/pM41b1yA07UCEnS1YpNo2PbgBE= X-Received: by 2002:a7b:cbcf:: with SMTP id n15mr5693077wmi.21.1581010289242; Thu, 06 Feb 2020 09:31:29 -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.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:28 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 19/29] qapi/qapi-schema.json: Put headers in their own doc-comment blocks Date: Thu, 6 Feb 2020 17:30:30 +0000 Message-Id: <20200206173040.17337-20-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::32f 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" 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 --- qapi/qapi-schema.json | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) -- 2.20.1 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. From patchwork Thu Feb 6 17:30:31 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183126 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1846733ile; Thu, 6 Feb 2020 09:46:52 -0800 (PST) X-Google-Smtp-Source: APXvYqyjnXY/43eNvoUWlGZNglXciHuMMXTEVPRG4BW+13ICiwotphGyrU1Agb3RtUyEEx9IWNyj X-Received: by 2002:a37:a915:: with SMTP id s21mr3562712qke.112.1581011212804; Thu, 06 Feb 2020 09:46:52 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581011212; cv=none; d=google.com; s=arc-20160816; b=dUK5NUT4s2xJfhGa9qlfkHlFMAYHCYbs8GhgSLZXoIimYEOuuv8i/Vf6i9ZFB2TmJW MVOzLDrQ9coR+tgBpngj7R+v62uSSrqYN1SDUFHiw7Djp6NEov//l8QMH8CCKUhjN1Rj UAz+ybwUx+dbk/gHLy+olTZRhU51tSf3Y9JOy5ET6l89lKVSNjDZulw7IEpoeKm6a7wu 1YBaN4eXclW0ob9EvNr//5i7gnI3DatMtipDaxo9mGPLu+KC2Q3b+jQRQODQPNlJw7tL UUxYKE0M96Pkeo4FelNiQGk6dywPygAsdxIDPUeeAyCV/BtpeKTPNfTQXc4wkCitBhVx tLog== 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=l4qwnnNC9N66e0pcxFV0qqg5LdHM/vrVq/qnQK+MWZg=; b=kfiu5DBEChq3EYrVeoKHtWElLRQYN+Ik4G1O7lf3J4ODi1M8xwfHfNUG5rSpXXWFo6 S984p+cZ7WYnAYP9FbNf+ACPwMvMWShLxAXlu0Aai5DO1bOGe+53ExTpcsMWjji1ZIJZ xFARhYf9P+MdKOGEWCitLSsWHLgaxHspKjn+RRudnPAp4yKAx2A9zNqMPGOZDBHoWKC4 BYeOLYpabLgA7Zz8+7m4xP7oh/dZt+uycQPm4GG20yo3QxKMs26Klw0XGNayeeGJdMDy t5dIc3Q1vrEZsiUurhKTv5EpufZBN6o3uertbWPsGR1cZY2Yop1RBHY3qXh+ZUR9sqXl 3Quw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=nUwyO0VS; 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 20si2080214qkv.152.2020.02.06.09.46.52 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:46:52 -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=nUwyO0VS; 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]:43706 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlEq-0007aP-BM for patch@linaro.org; Thu, 06 Feb 2020 12:46:52 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43601) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl06-0006oa-Bt for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:39 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl05-0006oP-Bo for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:38 -0500 Received: from mail-wm1-x341.google.com ([2a00:1450:4864:20::341]:50842) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izl03-0006Rl-DW for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:35 -0500 Received: by mail-wm1-x341.google.com with SMTP id a5so908314wmb.0 for ; Thu, 06 Feb 2020 09:31:31 -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=l4qwnnNC9N66e0pcxFV0qqg5LdHM/vrVq/qnQK+MWZg=; b=nUwyO0VSxMPmn82rGODiQTG7gI6JE3jJJ5Y2EWw0Z2e+XMdE9/iTKdhZM05J5EkWJS C6GbcrUlfIpShV46fGms0C487ETRrr0iwNhRyHzHAcwkxP9WTa+iCNigKjTFIdCCGLV3 YBxpkTJtVSoV+FwHS4eaVVbRJcD+d7Uf7YGT0CONqCB/ia/SXXjIPwkiWhDtiDKECDxc y1h4+wlbVcclxY3FhPCLgGi/EiSLZkO+sA9Ke6w1xPSaveOSnJaC1uO6GBySuYbHNR+V gIfH5rIiGD9uDYPOYVxHD60cAyPsvQX1Srn2xJEeGGoqNueSk3EtsoSUjpr0puf8MOvH dFvA== 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=l4qwnnNC9N66e0pcxFV0qqg5LdHM/vrVq/qnQK+MWZg=; b=iKQT3fZh7mV12FsdgEYAo6DXKWROnezMfr1wEghowmCmitM7E69N1atBCdVIWgJRmQ +1pqoB5jpoiMo+LIf8Q8jihowMk3WDAWii+G2IyWKs8uYajmHpWsF8MyD7JaprwhHDbb apkf4LoOC1ZEXgrOcYIf5AwrvlBfWYJQsv0zKpZi/XGT1wSjRP65q8LhVGdN3YMvyx/k 74WaV2RiW8+MN1P5FG/sD9BGZ9gxall5JFCZWvymsbMiOx2gqa2RlatbPn/Luhn99L+6 pOxWGXucpWGYgrE093xiLLIjuc8PCKlI5nQc3ZP3lJ/CwnnsJe1jt1RDW++66WxBQ9d7 fLNA== X-Gm-Message-State: APjAAAXLV1y+6oAnsgvZWCSAHKrKDg6Dkv1aW0/WhPz7PAbCQzLtHHJ7 YeUL9hyLK70V7ZJ24xF0atPO6y4L8uI= X-Received: by 2002:a1c:e007:: with SMTP id x7mr5589690wmg.3.1581010290350; Thu, 06 Feb 2020 09:31:30 -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.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:29 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 20/29] qapi/machine.json: Escape a literal '*' in doc comment Date: Thu, 6 Feb 2020 17:30:31 +0000 Message-Id: <20200206173040.17337-21-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::341 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" For rST, '*' is a kind of inline markup (for emphasis), so "*-softmmu" is a syntax error because of the missing closing '*'. Escape the '*' with a '\'. The texinfo document generator will leave the '\' in the output, which is not ideal, but that generator is going to go away in a subsequent commit. Signed-off-by: Peter Maydell --- qapi/machine.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) -- 2.20.1 diff --git a/qapi/machine.json b/qapi/machine.json index 51ffa96be98..a83a7b56b14 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -12,7 +12,7 @@ # # The comprehensive enumeration of QEMU system emulation ("softmmu") # targets. Run "./configure --help" in the project root directory, and -# look for the *-softmmu targets near the "--target-list" option. The +# look for the \*-softmmu targets near the "--target-list" option. The # individual target constants are not documented here, for the time # being. # From patchwork Thu Feb 6 17:30:32 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183116 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1840855ile; Thu, 6 Feb 2020 09:41:11 -0800 (PST) X-Google-Smtp-Source: APXvYqw5DXQn6HCq6ksKihjLGY6YUKwa/V9WtSfCtfeVy3zVwZJ2ow1L1HlXyMnsKOMSiDkwWD4f X-Received: by 2002:aed:2ae7:: with SMTP id t94mr3662389qtd.130.1581010871154; Thu, 06 Feb 2020 09:41:11 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010871; cv=none; d=google.com; s=arc-20160816; b=nPl2zyd+sCw1FacKWki5CR7gSdkp6RbQDjtYRtdMqGacyh16sp7xCMUn2GmqEyyZxB 1jkGkcK1cr9m44jSYt7T3Y/0XrfkwK9PXqdvgfUKN6zEbEQka3sCnNkBhCxyOorz+Ovn edK3oHIBbiIR19mDD47+OfuK1KIEUrD9TxeFxh4wu8Xr2K+3tLqB2NS8Jj4KgO4oAZg+ R9lG07TnTRUVT1vZTLH56ga6iVn/QMh77nSGpTZ+SoWGmLG+sgSUZ6QI9iDNkjTYvWBN jwfxt3+DrfSNNAF0T4GxQi3zAXoSINA0kTd9siv+wLIiM3ugKM3xltkH5D7rQ9AWPQbc ogzA== 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=m1bLOghX51x85KpGQ8LubXbMWazawtflU6lC5+ETOt0=; b=ItDB3vZnWjokjOd0pbAEmpxDzA7SRCWBba3zQSoj92/4GgxzaugJZCIsAqjBQCSgEE AjknfheOweE6x8+VsmmfcmmlZiY8PEGj6zf8y270XBsx/wtyRaLboDiWi9jsxIbdEfYT YGK95xVbnbPGjnduyF7+SD5HHjo93m9fMMZ1ltjJ4osAESaMujSirDSvazyrOIRjhQbl PpyQM2hqbX0qeJnt6dEMN0nYk8H76gpXRYBziXuGwohqA2RMQ2xjwNDzresMhH24TAhu 7OHYQP+FoaBiHi+tjqy4f2DuM+TYd9KOtYL150gClj6fUxmtVJywuOVAAlIpXI45JB/0 MqRQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=wQT2Bzz9; 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 b16si1891145qkj.46.2020.02.06.09.41.11 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:41:11 -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=wQT2Bzz9; 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]:43540 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl9K-0004uG-NB for patch@linaro.org; Thu, 06 Feb 2020 12:41:10 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43621) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl07-0006on-7k for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:40 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl05-0006oH-AT for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:39 -0500 Received: from mail-wm1-x32c.google.com ([2a00:1450:4864:20::32c]:35044) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izl03-0006Yw-Cp for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:35 -0500 Received: by mail-wm1-x32c.google.com with SMTP id b17so1013331wmb.0 for ; Thu, 06 Feb 2020 09:31:33 -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=m1bLOghX51x85KpGQ8LubXbMWazawtflU6lC5+ETOt0=; b=wQT2Bzz9jNy8iLOdroBgTf7SntlkB0ipMeBC6LwtXQO+3zjL7QRL971LsiynI8r6/l SBgcAXuTGmeCFDEXufv6A3rO/eIQ4Lj/eFrts8IVCYa6qiEwj1rP2H4uha8Dk16nx9x+ uMJk1xaOpd0D5JcHLorTYHtPRE5q+OZ6OSvyKGYrPXngpbEipNk97ZvMZKwfb3iW7ybQ dAEIUpr9/Yt9PaJwnWjLrVAcSCIsmdnr/QOmDoOAB9YSXS2+JTAZ7m8SxnsrvTxM00EQ AVtUK35x83yjxfmx9c6oo5nVnJ+YOShXsSc4uRR4mu+6bhpWO6lgKexV0YK358f/Vr9E pzxg== 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=m1bLOghX51x85KpGQ8LubXbMWazawtflU6lC5+ETOt0=; b=SKzXFsawdu1SzVvTZ4t69ySxiPvUE/eJCvxGH9f3pc8iCGpCqDtndphu0VRe+mbsek 2M2Q66dTQXFMl682/ZGndcI11QrMkOcYiPQPn8yLn/J1GMgc8Is516v7KndnvYorJCWU TPQx+kw9HnHXIsCPQ1HPbv3bnnzqajnvzKAH46UOn7R0vTnu3S9WGqha222y6b5F99Iy o/pgbGfZjex/LT0UWeTQ6yn999YJD3J/9zE4wE0O/AGPvwC02aCxb4lV3r+jb3CRvIgd b+vnl6jkFTH3TybIl1OtzxwKr7+7Im1FsUfkOHWexEbquYz45kzTQh8KlIDtgrjdqqul hs9w== X-Gm-Message-State: APjAAAWK4lRgJCqCSBER4KK/uA+A+swLIiNUmay1W709SkHE/KyeqLIg 6J2T/f1sB3nRF/LTjgOlM1KwzN1kM3E= X-Received: by 2002:a7b:c4c3:: with SMTP id g3mr5576802wmk.131.1581010291851; Thu, 06 Feb 2020 09:31:31 -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.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:31 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 21/29] scripts/qapi: Move doc-comment whitespace stripping to doc.py Date: Thu, 6 Feb 2020 17:30:32 +0000 Message-Id: <20200206173040.17337-22-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::32c 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" As we accumulate lines from doc comments when parsing the JSON, the QAPIDoc class generally strips leading and trailing whitespace using line.strip() when it calls _append_freeform(). This is fine for texinfo, but for rST leading whitespace is significant. We'd like to move to having the text in doc comments be rST format rather than a custom syntax, so move the removal of leading whitespace from the QAPIDoc class to the texinfo-specific processing code in texi_format() in qapi/doc.py. (Trailing whitespace will always be stripped by the rstrip() in Section::append regardless.) In a followup commit we will make the whitespace in the lines of doc comment sections more consistently follow the input source. There is no change to the generated .texi files before and after this commit. Signed-off-by: Peter Maydell --- scripts/qapi/doc.py | 1 + scripts/qapi/parser.py | 12 ++++-------- 2 files changed, 5 insertions(+), 8 deletions(-) -- 2.20.1 diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py index 6f1c17f71f7..96346c9b14f 100644 --- a/scripts/qapi/doc.py +++ b/scripts/qapi/doc.py @@ -80,6 +80,7 @@ def texi_format(doc): inlist = '' lastempty = False for line in doc.split('\n'): + line = line.strip() empty = line == '' # FIXME: Doing this in a single if / elif chain is diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 342792e4103..2196ec5de1e 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -422,10 +422,10 @@ class QAPIDoc(object): self._append_line = self._append_various_line self._append_various_line(line) else: - self._append_freeform(line.strip()) + self._append_freeform(line) else: # This is a free-form documentation block - self._append_freeform(line.strip()) + self._append_freeform(line) def _append_args_line(self, line): """ @@ -458,7 +458,7 @@ class QAPIDoc(object): self._append_various_line(line) return - self._append_freeform(line.strip()) + self._append_freeform(line) def _append_features_line(self, line): name = line.split(' ', 1)[0] @@ -477,7 +477,7 @@ class QAPIDoc(object): self._append_various_line(line) return - self._append_freeform(line.strip()) + self._append_freeform(line) def _append_various_line(self, line): """ @@ -500,10 +500,6 @@ class QAPIDoc(object): line = line[len(name)+1:] self._start_section(name[:-1]) - if (not self._section.name or - not self._section.name.startswith('Example')): - line = line.strip() - self._append_freeform(line) def _start_symbol_section(self, symbols_dict, name): From patchwork Thu Feb 6 17:30:33 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183128 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1847710ile; Thu, 6 Feb 2020 09:47:52 -0800 (PST) X-Google-Smtp-Source: APXvYqyLCGOYlJMJCSCjEsRFmkZ6PnBE82MWLXULltL1u/wji5tKGgRAqiHWpVpgYlvGk+rILw8b X-Received: by 2002:a37:6706:: with SMTP id b6mr3425426qkc.461.1581011272000; Thu, 06 Feb 2020 09:47:52 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581011271; cv=none; d=google.com; s=arc-20160816; b=zw/morUac4aFDzmAjFKRdUQQ0ap7EP7N7Ww1s6YBlpJromTvlU/1kFzTQB+ycUQ6gV GNKxoSXTySNCmvOE2nYU8iwlD8tWFuKoXe0jM8h81ymFiVmWzz8msftTcElhpN91/WIy Dsn3F3gDsTPcQyxx35lziW+/6Qlr2+8uxwbbFhWFuFgorOxBFYf60F+6mpdPQbbSUxI6 tETZcfUu7Uh8QE3U5bu53al6t91OW5jsv1Xxo3fu03ZcwT037doqh9unrhtnupdnpgjd vIg1RTu7i1WKNhRm4doJUW492zlYkyN1YAmazPFNuEPiPQz3dVluerHckBAyR34LR28e B56w== 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=uG5NDXEGg3myTzZttWMRSQ2riVD+Wnq5tJN9+Gr0JO8=; b=mY7f8TmjliZ9HZcA4zsSmPcfgdjR15W2j4Dr1r49Fftxb4BOkUhedawgR4vdQ9rcNj +unzY4jPNxROBc+3vHH9FUSRqrXwH5mkEuWUkkS5bKJJE0ivtXlA2YWfi9JyHiVyFnRq a/WAx/NwItWcOMFpqAX/HpHCHEgH/EofLi2Wh9sZTMhrMJKbfFYbCX2bCmMqw0pHGM00 FMsw/MkdzSbaIngeCYaAFT21UJw6HkA1sb6xHYg3wHNjLGsIl70U+f0o6EuneUl3erTy 8D2xxgCD8qk+ZYDs7MgPb+7o6yLVcVY2z03s1fJimg15FZ/cxGNHmFAhsHjo8M0CZ5zc 270Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=HPnRFdK9; 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 a68si1937186qke.236.2020.02.06.09.47.51 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:47:51 -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=HPnRFdK9; 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]:43736 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlFn-0000vP-EO for patch@linaro.org; Thu, 06 Feb 2020 12:47:51 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43652) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl08-0006u1-Vq for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:44 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl05-0006oh-CO for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:40 -0500 Received: from mail-wm1-x32a.google.com ([2a00:1450:4864:20::32a]:51969) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izl03-0006dz-KT for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:37 -0500 Received: by mail-wm1-x32a.google.com with SMTP id t23so902361wmi.1 for ; Thu, 06 Feb 2020 09:31:35 -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=uG5NDXEGg3myTzZttWMRSQ2riVD+Wnq5tJN9+Gr0JO8=; b=HPnRFdK9v97HwNjA4B3poqNfGABq1ap6SUXDpGg+vWCinCBZx3FB+bIgbSv/eES2z/ Uj7wq41REfVF9ffgmNoWTSM45J8C2BOSBwVkrqi0ncL9YTSTW2e3MYIESuqkfQCuS0g3 x39OITu1A2G5DXcU9hJuLXgJRloksM6TaVJp4VlHAYTVyh7G9gcERt1JW4LfrfM2QKOQ 5VsCmeFjBoBsuff62JBZyc7ZXklgFMA6ZmbUMUXFnK8Q/PAgrIan7ia+VUI3Qv87tLi/ qybnbf5Jfd3KpamawVzyAbYZEN4a01RqhjhQsQnL+eAZax6QnLMj5ROKM38dxxTnNHyi IKlw== 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=uG5NDXEGg3myTzZttWMRSQ2riVD+Wnq5tJN9+Gr0JO8=; b=ad12Pzm8hSXYTgO+USD1mKD+kwSvRJh1Rug8VGye/WCcg6m8MgwTj+dv4xex+wPObh E6Q3B85PKn92p7WiQAhFYcyDUdIcaHt2UlKIfGOuk4yCmx8MAhpzLTiAljNGk79xwarO vvFWaFEZWxWIA1NaEjhtmc4lLKalgn6EbRrsYnXRDknhqJHP2ZkDMNMCFvY1SyYQeGhv ONnmvsUkeYtidW4UzJOnejkdGezRw8kqxpgCKlnoNl2nLqQAyYAN3qoV9Tlf46C2RrDQ FapujLX3xpfH2MCXEnq2anPYPrtmDUxsNWdnmgf850FN+6VB1lTrs+AaV6qgfsOLm31t ZhaQ== X-Gm-Message-State: APjAAAUzhbkPwBnsnmoATt3iWyqWTNj9AQ1n3G+Bp0/sgafeYuToTXKB sKyZZyt0jsZoHnCg3AhrxWxiRQtmYz8= X-Received: by 2002:a1c:113:: with SMTP id 19mr5930397wmb.95.1581010293124; Thu, 06 Feb 2020 09:31:33 -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.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:32 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 22/29] scripts/qapi/parser.py: improve doc comment indent handling Date: Thu, 6 Feb 2020 17:30:33 +0000 Message-Id: <20200206173040.17337-23-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::32a 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" Make the handling of indentation in doc comments more sophisticated, so that when we see a section like: Notes: some text some more text indented line 3 we save it for the doc-comment processing code as: some text some more text indented line 3 and when we see a section with the heading on its own line: Notes: some text some more text indented text we also accept that and save it in the same form. The exception is that we always retain indentation as-is for Examples sections, because these are literal text. If we detect that the comment document text is not indented as much as we expect it to be, we throw a parse error. (We don't complain about over-indented sections, because for rST this can be legitimate markup.) Signed-off-by: Peter Maydell --- scripts/qapi/parser.py | 82 +++++++++++++++++++++++++++++++++--------- 1 file changed, 65 insertions(+), 17 deletions(-) -- 2.20.1 diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 2196ec5de1e..66f802641c9 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -313,18 +313,32 @@ class QAPIDoc(object): """ class Section(object): - def __init__(self, name=None): + def __init__(self, parser, name=None, indent=0): + # parser, for error messages about indentation + self._parser = parser # optional section name (argument/member or section name) self.name = name # the list of lines for this section self.text = '' + # the expected indent level of the text of this section + self._indent = indent def append(self, line): + # Strip leading spaces corresponding to the expected indent level + # Blank lines are always OK. + if line: + spacecount = len(line) - len(line.lstrip(" ")) + if spacecount > self._indent: + spacecount = self._indent + if spacecount < self._indent: + raise QAPIParseError(self._parser, "unexpected de-indent") + line = line[spacecount:] + self.text += line.rstrip() + '\n' class ArgSection(Section): - def __init__(self, name): - QAPIDoc.Section.__init__(self, name) + def __init__(self, parser, name, indent=0): + QAPIDoc.Section.__init__(self, parser, name, indent) self.member = None def connect(self, member): @@ -338,7 +352,7 @@ class QAPIDoc(object): self._parser = parser self.info = info self.symbol = None - self.body = QAPIDoc.Section() + self.body = QAPIDoc.Section(parser) # dict mapping parameter name to ArgSection self.args = OrderedDict() self.features = OrderedDict() @@ -443,7 +457,18 @@ class QAPIDoc(object): if name.startswith('@') and name.endswith(':'): line = line[len(name)+1:] - self._start_args_section(name[1:-1]) + if not line or line.isspace(): + # Line was just the "@arg:" header; following lines + # are not indented + indent = 0 + line = '' + else: + # Line is "@arg: first line of description"; following + # lines should be indented by len(name) + 1, and we + # pad out this first line so it is handled the same way + indent = len(name) + 1 + line = ' ' * indent + line + self._start_args_section(name[1:-1], indent) elif self._is_section_tag(name): self._append_line = self._append_various_line self._append_various_line(line) @@ -465,7 +490,17 @@ class QAPIDoc(object): if name.startswith('@') and name.endswith(':'): line = line[len(name)+1:] - self._start_features_section(name[1:-1]) + if not line or line.isspace(): + # Line is just the "@name:" header, no ident for following lines + indent = 0 + line = '' + else: + # Line is "@arg: first line of description"; following + # lines should be indented by len(name) + 3, and we + # pad out this first line so it is handled the same way + indent = len(name) + 1 + line = ' ' * indent + line + self._start_features_section(name[1:-1], indent) elif self._is_section_tag(name): self._append_line = self._append_various_line self._append_various_line(line) @@ -498,11 +533,23 @@ class QAPIDoc(object): % (name, self.sections[0].name)) elif self._is_section_tag(name): line = line[len(name)+1:] - self._start_section(name[:-1]) + if not line or line.isspace(): + # Line is just "SectionName:", no indent for following lines + indent = 0 + line = '' + elif name.startswith("Example"): + # The "Examples" section is literal-text, so preserve + # all the indentation as-is + indent = 0 + else: + # Line is "SectionName: some text", indent required + indent = len(name) + 1 + line = ' ' * indent + line + self._start_section(name[:-1], indent) self._append_freeform(line) - def _start_symbol_section(self, symbols_dict, name): + def _start_symbol_section(self, symbols_dict, name, indent): # FIXME invalid names other than the empty string aren't flagged if not name: raise QAPIParseError(self._parser, "invalid parameter name") @@ -511,21 +558,21 @@ class QAPIDoc(object): "'%s' parameter name duplicated" % name) assert not self.sections self._end_section() - self._section = QAPIDoc.ArgSection(name) + self._section = QAPIDoc.ArgSection(self._parser, name, indent) symbols_dict[name] = self._section - def _start_args_section(self, name): - self._start_symbol_section(self.args, name) + def _start_args_section(self, name, indent): + self._start_symbol_section(self.args, name, indent) - def _start_features_section(self, name): - self._start_symbol_section(self.features, name) + def _start_features_section(self, name, indent): + self._start_symbol_section(self.features, name, indent) - def _start_section(self, name=None): + def _start_section(self, name=None, indent=0): if name in ('Returns', 'Since') and self.has_section(name): raise QAPIParseError(self._parser, "duplicated '%s' section" % name) self._end_section() - self._section = QAPIDoc.Section(name) + self._section = QAPIDoc.Section(self._parser, name, indent) self.sections.append(self._section) def _end_section(self): @@ -548,7 +595,7 @@ class QAPIDoc(object): def connect_member(self, member): if member.name not in self.args: # Undocumented TODO outlaw - self.args[member.name] = QAPIDoc.ArgSection(member.name) + self.args[member.name] = QAPIDoc.ArgSection(self._parser, member.name) self.args[member.name].connect(member) def connect_feature(self, feature): @@ -556,7 +603,8 @@ class QAPIDoc(object): raise QAPISemError(feature.info, "feature '%s' lacks documentation" % feature.name) - self.features[feature.name] = QAPIDoc.ArgSection(feature.name) + self.features[feature.name] = QAPIDoc.ArgSection(self._parser, + feature.name) self.features[feature.name].connect(feature) def check_expr(self, expr): From patchwork Thu Feb 6 17:30:34 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183127 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1847326ile; Thu, 6 Feb 2020 09:47:26 -0800 (PST) X-Google-Smtp-Source: APXvYqxym1lHomTr0wQvTPr5oWOoT6Cp3JGd7RM/LDhUcIQG+a58LZlq9iJ58E6QDgECOxwAqfo5 X-Received: by 2002:ae9:f009:: with SMTP id l9mr3607437qkg.259.1581011246636; Thu, 06 Feb 2020 09:47:26 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581011246; cv=none; d=google.com; s=arc-20160816; b=lwx68RegM34drBOccLJ3gk0FV79QFeFM0Fv4PCG0M544VthG3yGiEy3moJx8IsPFHJ cnkW6zM3fUF1zn5ZRE+SiC+9qcHTTWTUo/8MWSwL2X+D49QkAxw0KEWPPSZ5N9jqXqS7 eEtBz8u5WGiT/I89CzhgM1j8VJod7enHkW9NhP2/whyjmtgqPHPZoefckk4GagjwaH/u x7BTSaLOJVkqYJzvE9goiNVGY+GzJ6MPNcBI+FSyCKqZhYu5yYg9axYHlaPS+ktMEYld OYyDEfqjCzc39Gaum5MCBy0X8c5YoOI9qF7TVrqiHR9aPjEu7DP5YxwbFvnxYnC8gRtd /aVw== 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=PBxUchVQuOVHJ+BCuW8Cnkqai5pZqzlD7t2HWTGi4ik=; b=lw21B3NfHGNFABi1lRxKJAvamZShAoEa+hY1iwlS0GmUXH5EMt/iTUoXlkG7jPunR4 U0ktrBxlX5w/NeM+2V2JmE7YaTOjrvi0Tn3/qE8gO99TJ3PSjXyPxLxXggCZp96/+CVD M9mg270Pc+oqfrZxmzJY26ik25fg+qYxaTv4mC2vl7gnEqKVoeQeBwGVdB+zncYiB3NL HnEZu5WZwamOJygXID22lNh3uslPAlOPIWgnYD9ZyuW4PFKG3FXjv2qMpFj5pWsHTyIL HcVbg5J4OUAEN7b3S8K14o3zLovqSTbvOE7LDKEGb/5vtUgVZ8cz3TvKWXO++ext7PkV vn3w== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=dTjoYOrV; 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 j25si71717qtp.306.2020.02.06.09.47.26 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:47:26 -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=dTjoYOrV; 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]:43726 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlFO-0008VV-2C for patch@linaro.org; Thu, 06 Feb 2020 12:47:26 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43655) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl09-0006ua-5u for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:44 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl05-0006q2-KU for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:41 -0500 Received: from mail-wr1-x429.google.com ([2a00:1450:4864:20::429]:35626) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izl05-0006hk-9O for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:37 -0500 Received: by mail-wr1-x429.google.com with SMTP id w12so8230359wrt.2 for ; Thu, 06 Feb 2020 09:31:36 -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=PBxUchVQuOVHJ+BCuW8Cnkqai5pZqzlD7t2HWTGi4ik=; b=dTjoYOrVuSyfNXNaPmsFgP7MjfaFEyz8Ee2nU21T75/Ft94IezPmXh80/M2izSYTki A+JtN0YLUN8QJCTRxEkGtNVRsy/CBtjRHEknPd1+adSHTpr7zhEl53pRjuLG2r5XMhTa 7JZBTMU/XNoHRGtTVisYqwepfhc6q1ZicdwTP/zTe60LFx2KSwt2+cvFEG9Z0j4WEDml C6XzW1abVyVxtuRrSaarvqgJkbj4X8V6tpLvRIYj/UJRPQLQcgFt7LipB6+7Zg1hXdOs CIDV+KpAphK6PsOM3sQJrrkE61b99KPtQe4K0lOucbfZT3V4+uNshiIO7VJP2f2DjdGW c7zA== 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=PBxUchVQuOVHJ+BCuW8Cnkqai5pZqzlD7t2HWTGi4ik=; b=mw5Mj2/QOPGaAq8TLVIJjBL4XjAujlW6YvLQ4pT2qx8ym7zRS+NL4Pwh13BQ8NNSXP RszqlyOJp+2tOvKSQD70XqMqLRIq7f9yqp25cECCU+d8EniOAH2HzhtEbX5ovCQYPVIe SxaXBQJ5kl38WIh354BFM2iQfQpHjzyKH14oi52psXaueSk1IJpAENx/umTkQNs5lnZ5 2o221ikrqfL/VuFYHXSQ15tT4soWa8RSfEgZxw+E98cdnoYbCXoO5OVf2hc736KcDuWr sHiJlyj8b8FeKNyZCBgYC2F3sHJZrleFPBIkNCXadz7PUjM18rcJajTmWpBp9haFToko 3iDA== X-Gm-Message-State: APjAAAWudExI5RkHnqvxt8uYn+NYv9/VgD/Y+7QeUnjPfIKJUwRuoIbh Pkn5L4H63t4EkhrY5xOUC36yAcmg+iU= X-Received: by 2002:adf:fd43:: with SMTP id h3mr4820847wrs.169.1581010294549; Thu, 06 Feb 2020 09:31:34 -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.33 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:34 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 23/29] docs/sphinx: Add new qapi-doc Sphinx extension Date: Thu, 6 Feb 2020 17:30:34 +0000 Message-Id: <20200206173040.17337-24-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::429 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" Some of our documentation is auto-generated from documentation comments in the JSON schema. For Sphinx, rather than creating a file to include, the most natural way to handle this is to have a small custom Sphinx extension which processes the JSON file and inserts documentation into the rST file being processed. This is the same approach that kerneldoc and hxtool use. Signed-off-by: Peter Maydell --- MAINTAINERS | 1 + docs/conf.py | 6 +- docs/sphinx/qapidoc.py | 504 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 510 insertions(+), 1 deletion(-) create mode 100644 docs/sphinx/qapidoc.py -- 2.20.1 diff --git a/MAINTAINERS b/MAINTAINERS index e72b5e5f696..e32eaf89318 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2786,3 +2786,4 @@ M: Peter Maydell S: Maintained F: docs/conf.py F: docs/*/conf.py +F: docs/sphinx/ diff --git a/docs/conf.py b/docs/conf.py index 7588bf192ee..1ada0b8f427 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,7 +51,10 @@ except NameError: # add these directories to sys.path here. If the directory is relative to the # documentation root, use an absolute path starting from qemu_docdir. # +# Our extensions are in docs/sphinx; the qapidoc extension requires +# the QAPI modules from scripts/. sys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) +sys.path.insert(0, os.path.join(qemu_docdir, "../scripts")) # -- General configuration ------------------------------------------------ @@ -64,7 +67,7 @@ needs_sphinx = '1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'qmp_lexer', 'hxtool'] +extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'qapidoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -232,3 +235,4 @@ texinfo_documents = [ kerneldoc_bin = os.path.join(qemu_docdir, '../scripts/kernel-doc') kerneldoc_srctree = os.path.join(qemu_docdir, '..') hxtool_srctree = os.path.join(qemu_docdir, '..') +qapidoc_srctree = os.path.join(qemu_docdir, '..') diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py new file mode 100644 index 00000000000..d0dd6e93d4c --- /dev/null +++ b/docs/sphinx/qapidoc.py @@ -0,0 +1,504 @@ +# coding=utf-8 +# +# QEMU qapidoc QAPI file parsing extension +# +# Copyright (c) 2020 Linaro +# +# This work is licensed under the terms of the GNU GPLv2 or later. +# See the COPYING file in the top-level directory. +"""qapidoc is a Sphinx extension that implements the qapi-doc directive""" + +# The purpose of this extension is to read the documentation comments +# in QAPI JSON schema files, and insert them all into the current document. +# The conf.py file must set the qapidoc_srctree config value to +# the root of the QEMU source tree. +# Each qapi-doc:: directive takes one argument which is the +# path of the .json file to process, relative to the source tree. + +import os +import re + +from docutils import nodes +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from sphinx.errors import ExtensionError +from sphinx.util.nodes import nested_parse_with_titles +import sphinx +from qapi.gen import QAPISchemaVisitor +from qapi.schema import QAPIError, QAPISchema + +# Sphinx up to 1.6 uses AutodocReporter; 1.7 and later +# use switch_source_input. Check borrowed from kerneldoc.py. +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + + +__version__ = '1.0' + +# Function borrowed from pydash, which is under the MIT license +def intersperse(iterable, separator): + """Like join, but for arbitrary iterables, notably arrays""" + iterable = iter(iterable) + yield next(iterable) + for item in iterable: + yield separator + yield item + +class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): + """A QAPI schema visitor which generates docutils/Sphinx nodes + + This class builds up a tree of docutils/Sphinx nodes corresponding + to documentation for the various QAPI objects. To use it, first create + a QAPISchemaGenRSTVisitor object, and call its visit_begin() method. + Then you can call one of the two methods 'freeform' (to add documentation + for a freeform documentation chunk) or 'symbol' (to add documentation + for a QAPI symbol). These will cause the visitor to build up the + tree of document nodes. Once you've added all the documentation + via 'freeform' and 'symbol' method calls, you can call 'get_document_nodes' + to get the final list of document nodes (in a form suitable for returning + from a Sphinx directive's 'run' method). + """ + def __init__(self, sphinx_directive): + self._cur_doc = None + self._sphinx_directive = sphinx_directive + self._top_node = nodes.section() + self._active_headings = [self._top_node] + + def _serror(self, msg): + """Raise an exception giving a user-friendly syntax error message""" + file = self._cur_doc.info.fname + line = self._cur_doc.info.line + raise ExtensionError('%s line %d: syntax error: %s' % (file, line, msg)) + + def _make_dlitem(self, term, defn): + """Return a dlitem node with the specified term and definition. + + term should be a list of Text and literal nodes. + defn should be one of: + - a string, which will be handed to _parse_text_into_node + - a list of Text and literal nodes, which will be put into + a paragraph node + """ + dlitem = nodes.definition_list_item() + dlterm = nodes.term('', '', *term) + dlitem += dlterm + if defn: + dldef = nodes.definition() + if isinstance(defn, list): + dldef += nodes.paragraph('', '', *defn) + else: + self._parse_text_into_node(defn, dldef) + dlitem += dldef + return dlitem + + def _make_section(self, title): + """Return a section node with optional title""" + section = nodes.section(ids=[self._sphinx_directive.new_serialno()]) + if title: + section += nodes.title(title, title) + return section + + def _nodes_for_ifcond(self, ifcond, with_if=True): + """Return list of Text, literal nodes for the ifcond + + Return a list which gives text like ' (If: cond1, cond2, cond3)', where + the conditions are in literal-text and the commas are not. + If with_if is False, we don't return the "(If: " and ")". + """ + condlist = intersperse([nodes.literal('', c) for c in ifcond], + nodes.Text(', ')) + if not with_if: + return condlist + + nodelist = [nodes.Text(' ('), nodes.strong('', 'If: ')] + nodelist.extend(condlist) + nodelist.append(nodes.Text(')')) + return nodelist + + def _nodes_for_one_member(self, member): + """Return list of Text, literal nodes for this member + + Return a list of doctree nodes which give text like + 'name: type (optional) (If: ...)' suitable for use as the + 'term' part of a definition list item. + """ + term = [nodes.literal('', member.name)] + if member.type.doc_type(): + term.append(nodes.Text(': ')) + term.append(nodes.literal('', member.type.doc_type())) + if member.optional: + term.append(nodes.Text(' (optional)')) + if member.ifcond: + term.extend(self._nodes_for_ifcond(member.ifcond)) + return term + + def _nodes_for_variant_when(self, variants, variant): + """Return list of Text, literal nodes for variant 'when' clause + + Return a list of doctree nodes which give text like + 'when tagname is variant (If: ...)' suitable for use in + the 'variants' part of a definition list. + """ + term = [nodes.Text(' when '), + nodes.literal('', variants.tag_member.name), + nodes.Text(' is '), + nodes.literal('', '"%s"' % variant.name)] + if variant.ifcond: + term.extend(self._nodes_for_ifcond(variant.ifcond)) + return term + + def _nodes_for_members(self, doc, what, base=None, variants=None): + """Return doctree nodes for the table of members""" + dlnode = nodes.definition_list() + for section in doc.args.values(): + term = self._nodes_for_one_member(section.member) + # TODO drop fallbacks when undocumented members are outlawed + if section.text: + defn = section.text + elif (variants and variants.tag_member == section.member + and not section.member.type.doc_type()): + values = section.member.type.member_names() + defn = [nodes.Text('One of ')] + defn.extend(intersperse([nodes.literal('', v) for v in values], + nodes.Text(', '))) + else: + defn = [nodes.Text('Not documented')] + + dlnode += self._make_dlitem(term, defn) + + if base: + dlnode += self._make_dlitem([nodes.Text('The members of '), + nodes.literal('', base.doc_type())], + None) + + if variants: + for v in variants.variants: + if v.type.is_implicit(): + assert not v.type.base and not v.type.variants + for m in v.type.local_members: + term = self._nodes_for_one_member(m) + term.extend(self._nodes_for_variant_when(variants, v)) + dlnode += self._make_dlitem(term, None) + else: + term = [nodes.Text('The members of '), + nodes.literal('', v.type.doc_type())] + term.extend(self._nodes_for_variant_when(variants, v)) + dlnode += self._make_dlitem(term, None) + + if not dlnode.children: + return None + + section = self._make_section(what) + section += dlnode + return section + + def _nodes_for_enum_values(self, doc, what): + """Return doctree nodes for the table of enum values""" + seen_item = False + dlnode = nodes.definition_list() + for section in doc.args.values(): + termtext = [nodes.literal('', section.member.name)] + if section.member.ifcond: + termtext.extend(self._nodes_for_ifcond(section.member.ifcond)) + # TODO drop fallbacks when undocumented members are outlawed + if section.text: + defn = section.text + else: + defn = [nodes.Text('Not documented')] + + dlnode += self._make_dlitem(termtext, defn) + seen_item = True + + if not seen_item: + return None + + section = self._make_section(what) + section += dlnode + return section + + def _nodes_for_arguments(self, doc, boxed_arg_type): + """Return doctree nodes for the arguments section""" + if boxed_arg_type: + assert not doc.args + section = self._make_section('Arguments') + dlnode = nodes.definition_list() + dlnode += self._make_dlitem( + [nodes.Text('The members of '), + nodes.literal('', boxed_arg_type.name)], + None) + section += dlnode + return section + + return self._nodes_for_members(doc, 'Arguments') + + def _nodes_for_features(self, doc): + """Return doctree nodes for the table of features""" + seen_item = False + dlnode = nodes.definition_list() + for section in doc.features.values(): + dlnode += self._make_dlitem([nodes.literal('', section.name)], + section.text) + seen_item = True + + if not seen_item: + return None + + section = self._make_section('Features') + section += dlnode + return section + + def _nodes_for_example(self, exampletext): + """Return doctree nodes for a code example snippet""" + return nodes.literal_block(exampletext, exampletext) + + def _nodes_for_sections(self, doc, ifcond): + """Return doctree nodes for additional sections following arguments""" + nodelist = [] + for section in doc.sections: + snode = self._make_section(section.name) + if section.name and section.name.startswith('Example'): + snode += self._nodes_for_example(section.text) + else: + self._parse_text_into_node(section.text, snode) + nodelist.append(snode) + if ifcond: + snode = self._make_section('If') + snode += self._nodes_for_ifcond(ifcond, with_if=False) + nodelist.append(snode) + if not nodelist: + return None + return nodelist + + def _add_doc(self, typ, sections): + """Add documentation for a command/object/enum... + + We assume we're documenting the thing defined in self._cur_doc. + typ is the type of thing being added ("Command", "Object", etc) + + sections is a list of nodes for sections to add to the definition. + """ + + doc = self._cur_doc + snode = nodes.section(ids=[self._sphinx_directive.new_serialno()]) + snode += nodes.title('', '', *[nodes.literal(doc.symbol, doc.symbol), + nodes.Text(' (' + typ + ')')]) + self._parse_text_into_node(doc.body.text, snode) + for s in sections: + if s is not None: + snode += s + self._add_node_to_current_heading(snode) + + def visit_enum_type(self, name, info, ifcond, members, prefix): + doc = self._cur_doc + self._add_doc('Enum', + [self._nodes_for_enum_values(doc, 'Values'), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_object_type(self, name, info, ifcond, base, members, variants, + features): + doc = self._cur_doc + if base and base.is_implicit(): + base = None + self._add_doc('Object', + [self._nodes_for_members(doc, 'Members', base, variants), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_alternate_type(self, name, info, ifcond, variants): + doc = self._cur_doc + self._add_doc('Alternate', + [self._nodes_for_members(doc, 'Members'), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_command(self, name, info, ifcond, arg_type, ret_type, gen, + success_response, boxed, allow_oob, allow_preconfig, + features): + doc = self._cur_doc + self._add_doc('Command', + [self._nodes_for_arguments(doc, + arg_type if boxed else None), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_event(self, name, info, ifcond, arg_type, boxed): + doc = self._cur_doc + self._add_doc('Event', + [self._nodes_for_arguments(doc, + arg_type if boxed else None), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def symbol(self, doc, entity): + """Add documentation for one symbol to the document tree + + This is the main entry point which causes us to add documentation + nodes for a symbol (which could be a 'command', 'object', 'event', + etc). We do this by calling 'visit' on the schema entity, which + will then call back into one of our visit_* methods, depending + on what kind of thing this symbol is. + """ + self._cur_doc = doc + entity.visit(self) + self._cur_doc = None + + def _start_new_heading(self, heading, level): + """Start a new heading at the specified heading level + + Create a new section whose title is 'heading' and which is placed + in the docutils node tree as a child of the most recent level-1 + heading. Subsequent document sections (commands, freeform doc chunks, + etc) will be placed as children of this new heading section. + """ + if len(self._active_headings) < level: + self._serror('Level %d subheading found outside a level %d heading' + % (level, level - 1)) + snode = self._make_section(heading) + self._active_headings[level - 1] += snode + self._active_headings = self._active_headings[:level] + self._active_headings.append(snode) + + def _add_node_to_current_heading(self, node): + """Add the node to whatever the current active heading is""" + self._active_headings[-1] += node + + def freeform(self, doc): + """Add a piece of 'freeform' documentation to the document tree + + A 'freeform' document chunk doesn't relate to any particular + symbol (for instance, it could be an introduction). + + As a special case, if the freeform document is a single line + of the form '= Heading text' it is treated as a section or subsection + heading, with the heading level indicated by the number of '=' signs. + """ + + # QAPIDoc documentation says free-form documentation blocks + # must have only a body section, nothing else. + assert not doc.sections + assert not doc.args + assert not doc.features + self._cur_doc = doc + + if re.match(r'=+ ', doc.body.text): + # Section or subsection heading: must be the only thing in the block + (heading, _, rest) = doc.body.text.partition('\n') + if rest != '': + raise ExtensionError('%s line %s: section or subsection heading' + ' must be in its own doc comment block' + % (doc.info.fname, doc.info.line)) + (leader, _, heading) = heading.partition(' ') + self._start_new_heading(heading, len(leader)) + return + + node = self._make_section(None) + self._parse_text_into_node(doc.body.text, node) + self._add_node_to_current_heading(node) + self._cur_doc = None + + def _parse_text_into_node(self, doctext, node): + """Parse a chunk of QAPI-doc-format text into the node + + The doc comment can contain most inline rST markup, including + bulleted and enumerated lists. + As an extra permitted piece of markup, @var will be turned + into ``var``. + """ + + # Handle the "@var means ``var`` case + doctext = re.sub(r'@([\w-]+)', r'``\1``', doctext) + + rstlist = ViewList() + for line in doctext.splitlines(): + # The reported line number will always be that of the start line + # of the doc comment, rather than the actual location of the error. + # Being more precise would require overhaul of the QAPIDoc class + # to track lines more exactly within all the sub-parts of the doc + # comment, as well as counting lines here. + rstlist.append(line, self._cur_doc.info.fname, + self._cur_doc.info.line) + self._sphinx_directive.do_parse(rstlist, node) + + def get_document_nodes(self): + """Return the list of docutils nodes which make up the document""" + return self._top_node.children + +class QAPIDocDirective(Directive): + """Extract documentation from the specified QAPI .json file""" + required_argument = 1 + optional_arguments = 1 + option_spec = { + 'qapifile': directives.unchanged_required + } + has_content = False + + def new_serialno(self): + """Return a unique new ID string suitable for use as a node's ID""" + env = self.state.document.settings.env + return 'qapidoc-%d' % env.new_serialno('qapidoc') + + def run(self): + env = self.state.document.settings.env + qapifile = env.config.qapidoc_srctree + '/' + self.arguments[0] + + # Tell sphinx of the dependency + env.note_dependency(os.path.abspath(qapifile)) + + try: + schema = QAPISchema(qapifile) + except QAPIError as err: + # Launder QAPI parse errors into Sphinx extension errors + # so they are displayed nicely to the user + raise ExtensionError(str(err)) + + vis = QAPISchemaGenRSTVisitor(self) + vis.visit_begin(schema) + for doc in schema.docs: + if doc.symbol: + vis.symbol(doc, schema.lookup_entity(doc.symbol)) + else: + vis.freeform(doc) + + return vis.get_document_nodes() + + def do_parse(self, rstlist, node): + """Parse rST source lines and add them to the specified node + + Take the list of rST source lines rstlist, parse them as + rST, and add the resulting docutils nodes as children of node. + The nodes are parsed in a way that allows them to include + subheadings (titles) without confusing the rendering of + anything else. + """ + # This is from kerneldoc.py -- it works around an API change in + # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use + # sphinx.util.nodes.nested_parse_with_titles() rather than the + # plain self.state.nested_parse(), and so we can drop the saving + # of title_styles and section_level that kerneldoc.py does, + # because nested_parse_with_titles() does that for us. + if Use_SSI: + with switch_source_input(self.state, rstlist): + nested_parse_with_titles(self.state, rstlist, node) + else: + save = self.state.memo.reporter + self.state.memo.reporter = AutodocReporter(rstlist, + self.state.memo.reporter) + try: + nested_parse_with_titles(self.state, rstlist, node) + finally: + self.state.memo.reporter = save + +def setup(app): + """ Register qapi-doc directive with Sphinx""" + app.add_config_value('qapidoc_srctree', None, 'env') + app.add_directive('qapi-doc', QAPIDocDirective) + + return dict( + version=__version__, + parallel_read_safe=True, + parallel_write_safe=True + ) From patchwork Thu Feb 6 17:30:35 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183120 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1842507ile; Thu, 6 Feb 2020 09:42:47 -0800 (PST) X-Google-Smtp-Source: APXvYqxCEYV8ul/7F0P8R6yEo0u8952EkOhrnaSoaVKKBKWswpt34iLVDm+P/tCf5ax6BEQHJTkU X-Received: by 2002:a0c:fe10:: with SMTP id x16mr3345130qvr.188.1581010967370; Thu, 06 Feb 2020 09:42:47 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581010967; cv=none; d=google.com; s=arc-20160816; b=mtmpneaXMwMur2VCT9LYti1dlh0CFt6KOxqhuQM8mb2exqwt2/hVtQ5+GCyfkWmIln f1+aESZX7Rv6INmj3epiaoma8ZJhWSANj+gHycg3spaQzObOPu0gS/QSPvxuUjiQ5RoG fKh7X7UnAh+Os7eUY4hAsxN6qgfGj4OJ397ChqY2Ri7CYV7l/J1dc1OK5KZrMcNmty8F 8RVluvsB95UBF+kwI6IzHC8nkvwl9quYXc+FuRKinNvW+RyoAQP9H00rSeQYXVfPGjdD XqdLQQujXmOd6M+KeR/bm8RPTkKcOqC70hUDt1w7KluuZ7yKXXZrbEayWiMqav6s7hXk hacA== 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=jlNxGTGy98aYa+WWuQg/GQC6QdDQPDH1UcmycQV5nYo=; b=K6csp+9zKnBPv/2u3xoIjhPiHlFlFO0O2r+24RJzblGPEVvQcSpyZQyGJc6c5oVykS TjDRlfNihEPKI28IlehHo8XeB9CUXWhb+zI8G3r2q3USU0E0kysc0T0GuaFF5YO+3R1O t0Wsp44Pl7bWgTdBrbvucOfKrDdrptvEA92S915qlENHo3f+YMCQofADu/VokjbquBkA +/FsdrGz4+2IDyk4DuwboUTaRUiTQUAX8BQPN4q5DNx6XXawlTE6gs0EDfXSoYr+8CB1 vCnRISBvkgCQVrpUbEfoZVAd6lYbXg/1jEpStV1VrbeAGhouj1oi9iKLmcYx9a1FhYJN Px3Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=RlRFgFfy; 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 y7si1862442qvr.214.2020.02.06.09.42.47 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:42:47 -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=RlRFgFfy; 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]:43594 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlAs-0008Nq-RM for patch@linaro.org; Thu, 06 Feb 2020 12:42:46 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43650) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl08-0006tp-Tb for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:43 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl05-0006rX-Vg for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:40 -0500 Received: from mail-wr1-x430.google.com ([2a00:1450:4864:20::430]:40792) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izl05-0006mb-Ln for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:37 -0500 Received: by mail-wr1-x430.google.com with SMTP id t3so8192177wru.7 for ; Thu, 06 Feb 2020 09:31:37 -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=jlNxGTGy98aYa+WWuQg/GQC6QdDQPDH1UcmycQV5nYo=; b=RlRFgFfy0wknayqP+eHAmnAZNzx5z61KwqT3nchMnUXA5tx3Q01Pjz/wyeOjtDIhW/ h2wQrc7o7qOdNZKWIGCZ7QS/n6cow53sQqJoGLYhojwHcpaP086i1vX5CaIeUOWG+YQv 8RubxPIXtgw6r4ogWRdszxMFD4GcidBRPMWUJV+/s3zOskf4WqrjCCsu4kAikGhnD3fp pCKSQuwKgSvueCiQLsHUr7VXtR1/3zBJ1rC7JcgqB22uo4cXZAPtkHcp/dAUnb8LBZgV oiHhs6uHI9idKazreVz4AfrOtSNwLmzxOKn0td4nz2fFsCIxkhvUDZkNxrPt6/Q62haa wl/Q== 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=jlNxGTGy98aYa+WWuQg/GQC6QdDQPDH1UcmycQV5nYo=; b=NrHAvyF4muugK8RFHSoJE89C5FjpLKVtNNvQC50EKGrqysnbFL3mzROpJ6hun2GELh 6MO3gcbPj40ICpLHJKn5TZiUGDlrVjQYb72iNtijza/y0bJUIbEDy4Ob9AbNjI4lTnAy a/aeP6Tpl81sSRTzKPLMB+HQ+yFWOzjDdfLak2ZDVa++/4S4a/o3XO8ZHUO5GwFfFXy+ VHT4wTaYib1WBps1VJFJJCwkePbbyrSPlJJr9pXjX9nEvFLKfd1UQg5XPyrVP6Ow4d+l llWO+U1Cn/kMboI0Z1t9pKfecdOB/cZ7LLzyos5Wbuo2OXJn9KbV5dghSOkJWawm8akH li2g== X-Gm-Message-State: APjAAAXbTVW0k6PL/875QdEgZ+KecIg8+TrfKTk+UP4cPt3PLoENF2ha 6Fafn4U3+fjthKS9Pi2f7IwF93DuBH8= X-Received: by 2002:a05:6000:11d0:: with SMTP id i16mr5078218wrx.188.1581010296009; Thu, 06 Feb 2020 09:31:36 -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.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:35 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 24/29] docs/interop: Convert qemu-ga-ref to rST Date: Thu, 6 Feb 2020 17:30:35 +0000 Message-Id: <20200206173040.17337-25-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::430 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" Convert qemu-ga-ref to rST format. This includes dropping the plain-text, pdf and info format outputs for this document; as with all our other Sphinx-based documentation, we provide HTML and manpage only. The qemu-ga-ref.rst is somewhat more stripped down than the .texi was, because we do not (currently) attempt to generate indexes for the commands, events and data types being documented. As the GA ref is now part of the Sphinx 'interop' manual, we can delete the direct link from index.html.in. Signed-off-by: Peter Maydell --- Makefile | 42 ++++++++---------- MAINTAINERS | 2 +- docs/index.html.in | 1 - docs/interop/conf.py | 2 + docs/interop/index.rst | 1 + docs/interop/qemu-ga-ref.rst | 4 ++ docs/interop/qemu-ga-ref.texi | 80 ----------------------------------- 7 files changed, 25 insertions(+), 107 deletions(-) create mode 100644 docs/interop/qemu-ga-ref.rst delete mode 100644 docs/interop/qemu-ga-ref.texi -- 2.20.1 diff --git a/Makefile b/Makefile index 274a24f7aa4..790e5b2c817 100644 --- a/Makefile +++ b/Makefile @@ -350,7 +350,7 @@ DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8 DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8 DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7 -DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7 +DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 DOCS+=docs/qemu-cpu-models.7 DOCS+=$(MANUAL_BUILDDIR)/index.html ifdef CONFIG_VIRTFS @@ -759,11 +759,11 @@ distclean: clean rm -f config.log rm -f linux-headers/asm rm -f docs/version.texi - rm -f docs/interop/qemu-ga-qapi.texi docs/interop/qemu-qmp-qapi.texi - rm -f docs/interop/qemu-qmp-ref.7 docs/interop/qemu-ga-ref.7 - rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt - rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf - rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html + rm -f docs/interop/qemu-qmp-qapi.texi + rm -f docs/interop/qemu-qmp-ref.7 + rm -f docs/interop/qemu-qmp-ref.txt + rm -f docs/interop/qemu-qmp-ref.pdf + rm -f docs/interop/qemu-qmp-ref.html rm -f docs/qemu-cpu-models.7 rm -rf .doctrees $(call clean-manual,devel) @@ -817,7 +817,7 @@ endif # and also any sphinx-built manpages. define install-manual = for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done -for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done +for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-qmp-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done endef # Note that we deliberately do not install the "devel" manual: it is @@ -852,9 +852,7 @@ ifdef CONFIG_TRACE_SYSTEMTAP endif ifneq (,$(findstring qemu-ga,$(TOOLS))) $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8" - $(INSTALL_DATA) docs/interop/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) docs/interop/qemu-ga-ref.txt "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) docs/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7" endif endif ifdef CONFIG_VIRTFS @@ -1041,7 +1039,7 @@ endef $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) $(call build-manual,devel,html) -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qemu-img-cmds.hx +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/qga/qapi-schema.json $(qapi-py) $(call build-manual,interop,html) $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) @@ -1051,8 +1049,10 @@ $(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system) $(call build-manual,system,html) $(call define-manpage-rule,interop,\ - qemu-ga.8 qemu-img.1 qemu-nbd.8 qemu-trace-stap.1 virtfs-proxy-helper.1,\ - $(SRC_PATH)/qemu-img-cmds.hx) + qemu-ga.8 qemu-ga-ref.7 \ + qemu-img.1 qemu-nbd.8 qemu-trace-stap.1 virtfs-proxy-helper.1,\ + $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/qga/qapi-schema.json \ + $(qapi-py)) $(call define-manpage-rule,system,qemu-block-drivers.7) @@ -1073,17 +1073,14 @@ qemu-monitor-info.texi: $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/scripts/hxt docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi @cp -p $< $@ -docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi - @cp -p $< $@ - qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi qemu.1: qemu-option-trace.texi docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi -html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs -info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info -pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf -txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt +html: qemu-doc.html docs/interop/qemu-qmp-ref.html sphinxdocs +info: qemu-doc.info docs/interop/qemu-qmp-ref.info +pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf +txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ qemu-options.texi \ @@ -1092,11 +1089,6 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ qemu-monitor-info.texi \ docs/qemu-cpu-models.texi docs/security.texi -docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \ - docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \ - docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7: \ - docs/interop/qemu-ga-ref.texi docs/interop/qemu-ga-qapi.texi - docs/interop/qemu-qmp-ref.dvi docs/interop/qemu-qmp-ref.html \ docs/interop/qemu-qmp-ref.info docs/interop/qemu-qmp-ref.pdf \ docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7: \ diff --git a/MAINTAINERS b/MAINTAINERS index e32eaf89318..e99fb4b0b0e 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2126,9 +2126,9 @@ M: Michael Roth S: Maintained F: qga/ F: docs/interop/qemu-ga.rst +F: docs/interop/qemu-ga-ref.rst F: scripts/qemu-guest-agent/ F: tests/test-qga.c -F: docs/interop/qemu-ga-ref.texi T: git https://github.com/mdroth/qemu.git qga QOM diff --git a/docs/index.html.in b/docs/index.html.in index 8512933d145..92a057101e6 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -9,7 +9,6 @@
  • User Documentation
  • QMP Reference Manual
    • -
  • Guest Agent Protocol Reference
  • System Emulation Management and Interoperability Guide
  • System Emulation Guest Hardware Specifications
  • System Emulation User's Guide
    • diff --git a/docs/interop/conf.py b/docs/interop/conf.py index b0f322207ca..21e1ac74282 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -19,6 +19,8 @@ html_theme_options['description'] = u'System Emulation Management and Interopera man_pages = [ ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent', ['Michael Roth '], 8), + ('qemu-ga-ref', 'qemu-ga-ref', u'QEMU Guest Agent Protocol Reference', + [], 7), ('qemu-img', 'qemu-img', u'QEMU disk image utility', ['Fabrice Bellard'], 1), ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server', diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 3b763b1eebe..3102eef4add 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -18,6 +18,7 @@ Contents: live-block-operations pr-helper qemu-ga + qemu-ga-ref qemu-img qemu-nbd qemu-trace-stap diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst new file mode 100644 index 00000000000..013eac0bb53 --- /dev/null +++ b/docs/interop/qemu-ga-ref.rst @@ -0,0 +1,4 @@ +QEMU Guest Agent Protocol Reference +=================================== + +.. qapi-doc:: qga/qapi-schema.json diff --git a/docs/interop/qemu-ga-ref.texi b/docs/interop/qemu-ga-ref.texi deleted file mode 100644 index ddb76ce1c2a..00000000000 --- a/docs/interop/qemu-ga-ref.texi +++ /dev/null @@ -1,80 +0,0 @@ -\input texinfo -@setfilename qemu-ga-ref.info - -@include version.texi - -@exampleindent 0 -@paragraphindent 0 - -@settitle QEMU Guest Agent Protocol Reference - -@iftex -@center @image{docs/qemu_logo} -@end iftex - -@copying -This is the QEMU Guest Agent Protocol reference manual. - -Copyright @copyright{} 2016 The QEMU Project developers - -@quotation -This manual is free documentation: you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation, either version 2 of the -License, or (at your option) any later version. - -This manual is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this manual. If not, see http://www.gnu.org/licenses/. -@end quotation -@end copying - -@dircategory QEMU -@direntry -* QEMU-GA-Ref: (qemu-ga-ref). QEMU Guest Agent Protocol Reference -@end direntry - -@titlepage -@title Guest Agent Protocol Reference Manual -@subtitle QEMU version @value{VERSION} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top QEMU Guest Agent protocol reference -@end ifnottex - -@menu -* API Reference:: -* Commands and Events Index:: -* Data Types Index:: -@end menu - -@node API Reference -@chapter API Reference - -@c for texi2pod: -@c man begin DESCRIPTION - -@include qemu-ga-qapi.texi - -@c man end - -@node Commands and Events Index -@unnumbered Commands and Events Index -@printindex fn - -@node Data Types Index -@unnumbered Data Types Index -@printindex tp - -@bye From patchwork Thu Feb 6 17:30:36 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183132 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1849535ile; Thu, 6 Feb 2020 09:49:44 -0800 (PST) X-Google-Smtp-Source: APXvYqz4xWHYf0WOUiwh6JYKVsLKMX8QpHQ9oGaHVKxDUxdDYkT5TqYZP6/Oolz3rE49MMUrSgi8 X-Received: by 2002:ac8:6618:: with SMTP id c24mr3671955qtp.327.1581011384125; Thu, 06 Feb 2020 09:49:44 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581011384; cv=none; d=google.com; s=arc-20160816; b=0p6vzW82ayg8xp5Gyl4U6n28TiLrgCKVueumo+BQWI8mCiupFECldF+08FZvazqu9n 8XKCWT+mu53IGUWze2nNcshjKAdmhOBdgUy/McsS9F3siU4pHUtJvnlaKTga6NgqOhf0 HToyKqdmVbqyHrI01XGMAEZMEYsCNSvhXSf8zSTqgj17KOf2rznEaBA1XW9nmd2F1vn2 d0iUfo2Erw2CmaU1un9q1xe5+br0C/NUi3p/7HB7UDpakOofRk0J+QMW68uDufJfDc2c /CwoyRFZHyaFQ/M8WhoeyX6LFWILrBbj0m01R6zct4SKyDR6Lc5zuLm6KmopJzwHufqS J7DQ== 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=ixvc6L0q2QlOhkl+8cnuUfHjWf1FDH70K9mOZrRaf84=; b=mabSuCKNnmE1rNNTIa0A5nTT8EwntDt1RLhAj+4lxIX/cTG6M7/u9fKkmcXCg11+ma zrF4b+hwLaUyT9Beqy9RXJwk+Hwa7CSehTP53SgdphUOBm0f/p1yEOufYVcef/L1gThi fobqCBhApncu3mEaFUdVrM//swf5qQs+POEwd/nJuu+p9nXjeSN+ojb6WRUnE6k0kFwq Wij/p9boR/RGSb0WcfIT7ZMTDodp6RqMNnbXCPek4u2tbthHlCvsWkDLNI4StTM4CS2B h7Xgp34mT0eVs7F8h0HFqUf/WG9psimmfwPCUi0LPspT2C3Wi6T2PELZoowZpEhsseCU niWw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=UjIptEDN; 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 u14si237qvn.40.2020.02.06.09.49.44 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:49:44 -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=UjIptEDN; 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]:43778 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlHb-0004Eq-JW for patch@linaro.org; Thu, 06 Feb 2020 12:49:43 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43686) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl0B-0006ye-0g for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:45 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl07-0006y6-GN for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:41 -0500 Received: from mail-wr1-x42d.google.com ([2a00:1450:4864:20::42d]:35630) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izl07-0006tT-5v for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:39 -0500 Received: by mail-wr1-x42d.google.com with SMTP id w12so8230527wrt.2 for ; Thu, 06 Feb 2020 09:31:38 -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=ixvc6L0q2QlOhkl+8cnuUfHjWf1FDH70K9mOZrRaf84=; b=UjIptEDNyX6txcgWnDajdndL4iFZ5SbExtDxx7je3tAjFCZSpFV3kO88xtcjtvfPA1 /aRolpEAZ9JzAcr3y4M9Gj82cAm3f0PuSX2I5YxBVxb1Dix3rTDegrXELXuaYrAim9j9 oVlg1EBKfr7S5AVr7LmI+UDiuRqA+iYdh0sCQCVxZmftRyu/y+npSH3s+GX4Ro52B1Yz 2xdCO7LabfbOdaNqjjIqM+6nU39MHwBjM4NhWTRnxCTBqT48B1cXUP9dBmidkvrlt3m8 q0K+czYKU2X48TIZO+AaxAuAtWhQieyjoHQnVoa3meT0WZWKRq7mOpTfXykbEyu5gOiJ Zhew== 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=ixvc6L0q2QlOhkl+8cnuUfHjWf1FDH70K9mOZrRaf84=; b=I7GWlIX9d4NYWS4zc/sLj/njRR/ZRxTM6QI28Reg4NOlvOZwLJWaBOLKDW5GKrJM0s /Z1xLCiKKU0Uv6uF9qubeIFEYIU4MQPjtRIonEVYB84zwLgKiOZ4bU8FIkVoXO1q1N6B A1J3zFWikFEu8YZWeINxE9VV9b5RBWHXRb3TavvkSLpQ7UPZwZYSiLReWhaIltv3j6gA eZT7dGuZ51dmhxcTX2sqf3thHlXzAktDk+IO4NMa63zZHiT4g0x9upqe7JmTVPHIjnAc JLpXouWylQvQGwr7jUcT6Ag0h8Q8LcBf9TlOMFb3gU/SLQFDbPzm0rBTA5+JBRYNBale zJtA== X-Gm-Message-State: APjAAAWp2Vj7QcuBG8PTrJZH3pZZK6GvOrnQv9bj9dk/MvN2kYi1IDpI wu0WgGA5y+0r05CxUH7fGfs7M5jy3mw= X-Received: by 2002:adf:f850:: with SMTP id d16mr4729690wrq.161.1581010297426; Thu, 06 Feb 2020 09:31:37 -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.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:36 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 25/29] docs/interop: Convert qemu-qmp-ref to rST Date: Thu, 6 Feb 2020 17:30:36 +0000 Message-Id: <20200206173040.17337-26-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::42d 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" Convert qemu-qmp-ref to rST format. This includes dropping the plain-text, pdf and info format outputs for this document; as with all our other Sphinx-based documentation, we provide HTML and manpage only. The qemu-qmp-ref.rst is somewhat more stripped down than the .texi was, because we do not (currently) attempt to generate indexes for the commands, events and data types being documented. Again, we drop the direct link from index.html.in now that the QMP ref is part of the interop manual. Signed-off-by: Peter Maydell --- Makefile | 37 +++++----------- docs/index.html.in | 1 - docs/interop/conf.py | 2 + docs/interop/index.rst | 1 + docs/interop/qemu-qmp-ref.rst | 4 ++ docs/interop/qemu-qmp-ref.texi | 80 ---------------------------------- 6 files changed, 17 insertions(+), 108 deletions(-) create mode 100644 docs/interop/qemu-qmp-ref.rst delete mode 100644 docs/interop/qemu-qmp-ref.texi -- 2.20.1 diff --git a/Makefile b/Makefile index 790e5b2c817..159ac78dd24 100644 --- a/Makefile +++ b/Makefile @@ -126,7 +126,6 @@ GENERATED_QAPI_FILES += qapi/qapi-events.h qapi/qapi-events.c GENERATED_QAPI_FILES += $(QAPI_MODULES:%=qapi/qapi-events-%.h) GENERATED_QAPI_FILES += $(QAPI_MODULES:%=qapi/qapi-events-%.c) GENERATED_QAPI_FILES += qapi/qapi-introspect.c qapi/qapi-introspect.h -GENERATED_QAPI_FILES += qapi/qapi-doc.texi generated-files-y += $(GENERATED_QAPI_FILES) @@ -349,8 +348,8 @@ DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-img.1 DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8 DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8 DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 -DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7 DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 +DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-qmp-ref.7 DOCS+=docs/qemu-cpu-models.7 DOCS+=$(MANUAL_BUILDDIR)/index.html ifdef CONFIG_VIRTFS @@ -612,8 +611,7 @@ $(SRC_PATH)/scripts/qapi-gen.py qga/qapi-generated/qga-qapi-types.c qga/qapi-generated/qga-qapi-types.h \ qga/qapi-generated/qga-qapi-visit.c qga/qapi-generated/qga-qapi-visit.h \ qga/qapi-generated/qga-qapi-commands.h qga/qapi-generated/qga-qapi-commands.c \ -qga/qapi-generated/qga-qapi-init-commands.h qga/qapi-generated/qga-qapi-init-commands.c \ -qga/qapi-generated/qga-qapi-doc.texi: \ +qga/qapi-generated/qga-qapi-init-commands.h qga/qapi-generated/qga-qapi-init-commands.c: \ qga/qapi-generated/qapi-gen-timestamp ; qga/qapi-generated/qapi-gen-timestamp: $(SRC_PATH)/qga/qapi-schema.json $(qapi-py) $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \ @@ -759,11 +757,6 @@ distclean: clean rm -f config.log rm -f linux-headers/asm rm -f docs/version.texi - rm -f docs/interop/qemu-qmp-qapi.texi - rm -f docs/interop/qemu-qmp-ref.7 - rm -f docs/interop/qemu-qmp-ref.txt - rm -f docs/interop/qemu-qmp-ref.pdf - rm -f docs/interop/qemu-qmp-ref.html rm -f docs/qemu-cpu-models.7 rm -rf .doctrees $(call clean-manual,devel) @@ -817,7 +810,7 @@ endif # and also any sphinx-built manpages. define install-manual = for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done -for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-qmp-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done +for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' -name '*.[0-9]'); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done endef # Note that we deliberately do not install the "devel" manual: it is @@ -833,13 +826,11 @@ install-doc: $(DOCS) install-sphinxdocs $(INSTALL_DATA) $(MANUAL_BUILDDIR)/index.html "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) docs/interop/qemu-qmp-ref.html "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) docs/interop/qemu-qmp-ref.txt "$(DESTDIR)$(qemu_docdir)" ifdef CONFIG_POSIX $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1" $(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1" $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7" - $(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7" $(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7" $(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7" ifeq ($(CONFIG_TOOLS),y) @@ -1039,7 +1030,7 @@ endef $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) $(call build-manual,devel,html) -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/qga/qapi-schema.json $(qapi-py) +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/qga/qapi-schema.json $(qapi-modules) $(qapi-py) $(call build-manual,interop,html) $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) @@ -1052,7 +1043,7 @@ $(call define-manpage-rule,interop,\ qemu-ga.8 qemu-ga-ref.7 \ qemu-img.1 qemu-nbd.8 qemu-trace-stap.1 virtfs-proxy-helper.1,\ $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/qga/qapi-schema.json \ - $(qapi-py)) + $(qapi-modules) $(qapi-py)) $(call define-manpage-rule,system,qemu-block-drivers.7) @@ -1070,17 +1061,14 @@ qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx $(SRC_PATH)/scripts/hxtool qemu-monitor-info.texi: $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/scripts/hxtool $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@") -docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi - @cp -p $< $@ - qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi qemu.1: qemu-option-trace.texi docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi -html: qemu-doc.html docs/interop/qemu-qmp-ref.html sphinxdocs -info: qemu-doc.info docs/interop/qemu-qmp-ref.info -pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf -txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt +html: qemu-doc.html sphinxdocs +info: qemu-doc.info +pdf: qemu-doc.pdf +txt: qemu-doc.txt qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ qemu-options.texi \ @@ -1089,11 +1077,6 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ qemu-monitor-info.texi \ docs/qemu-cpu-models.texi docs/security.texi -docs/interop/qemu-qmp-ref.dvi docs/interop/qemu-qmp-ref.html \ - docs/interop/qemu-qmp-ref.info docs/interop/qemu-qmp-ref.pdf \ - docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7: \ - docs/interop/qemu-qmp-ref.texi docs/interop/qemu-qmp-qapi.texi - $(filter %.1 %.7 %.8,$(DOCS)): scripts/texi2pod.pl # Reports/Analysis diff --git a/docs/index.html.in b/docs/index.html.in index 92a057101e6..ba7cd611d26 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -8,7 +8,6 @@

    QEMU @@VERSION@@ Documentation

    • User Documentation
      • -
    • QMP Reference Manual
    • System Emulation Management and Interoperability Guide
    • System Emulation Guest Hardware Specifications
    • System Emulation User's Guide
      • diff --git a/docs/interop/conf.py b/docs/interop/conf.py index 21e1ac74282..55bbae6053a 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -25,6 +25,8 @@ man_pages = [ ['Fabrice Bellard'], 1), ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server', ['Anthony Liguori '], 8), + ('qemu-qmp-ref', 'qemu-qmp-ref', u'QEMU QMP Reference Manual', + [], 7), ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool', [], 1), ('virtfs-proxy-helper', 'virtfs-proxy-helper', diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 3102eef4add..0997c1ac4ba 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -21,6 +21,7 @@ Contents: qemu-ga-ref qemu-img qemu-nbd + qemu-qmp-ref qemu-trace-stap vhost-user vhost-user-gpu diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst new file mode 100644 index 00000000000..e640903abaf --- /dev/null +++ b/docs/interop/qemu-qmp-ref.rst @@ -0,0 +1,4 @@ +QEMU QMP Reference Manual +========================= + +.. qapi-doc:: qapi/qapi-schema.json diff --git a/docs/interop/qemu-qmp-ref.texi b/docs/interop/qemu-qmp-ref.texi deleted file mode 100644 index bb25758bd02..00000000000 --- a/docs/interop/qemu-qmp-ref.texi +++ /dev/null @@ -1,80 +0,0 @@ -\input texinfo -@setfilename qemu-qmp-ref.info - -@include version.texi - -@exampleindent 0 -@paragraphindent 0 - -@settitle QEMU QMP Reference Manual - -@iftex -@center @image{docs/qemu_logo} -@end iftex - -@copying -This is the QEMU QMP reference manual. - -Copyright @copyright{} 2016 The QEMU Project developers - -@quotation -This manual is free documentation: you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation, either version 2 of the -License, or (at your option) any later version. - -This manual is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this manual. If not, see http://www.gnu.org/licenses/. -@end quotation -@end copying - -@dircategory QEMU -@direntry -* QEMU-QMP-Ref: (qemu-qmp-ref). QEMU QMP Reference Manual -@end direntry - -@titlepage -@title QMP Reference Manual -@subtitle QEMU version @value{VERSION} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top QEMU QMP reference -@end ifnottex - -@menu -* API Reference:: -* Commands and Events Index:: -* Data Types Index:: -@end menu - -@node API Reference -@chapter API Reference - -@c for texi2pod: -@c man begin DESCRIPTION - -@include qemu-qmp-qapi.texi - -@c man end - -@node Commands and Events Index -@unnumbered Commands and Events Index -@printindex fn - -@node Data Types Index -@unnumbered Data Types Index -@printindex tp - -@bye From patchwork Thu Feb 6 17:30:37 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183125 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1844407ile; Thu, 6 Feb 2020 09:44:46 -0800 (PST) X-Google-Smtp-Source: APXvYqyYMikw5OiyaAiOfYf5abU0y8l33Q08DowSZqqvY2qJRWnKI1ChP7ZgBO/SQPz/9/kFYE2u X-Received: by 2002:a0c:f685:: with SMTP id p5mr3405491qvn.44.1581011086636; Thu, 06 Feb 2020 09:44:46 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581011086; cv=none; d=google.com; s=arc-20160816; b=TyFi6f2cqXVSb7BQSdWWOFHo2eeBJu5dpzDwxnPFFna6//xc0eA/rk1YKWJg3Cjkck 95OrCf64d9j2uYSXSCFjVVG/ITCv4hINyu/m/zxMf8xRTn0YCzRyoplkRm85sO6NM4Oz Xp5Pe0+3R2KGc0+jO/j6RlOYKkSwM9GE0tPuekx9jNeVMV7bXKsPLmxddWTgzNC87yPl jQgQdbGhmvpiHmkNybamYSwAJdKKCziNvExCzWCkqFY57Ovyj9j71MqzIvTadZ8I6dJd 5hcVq/mY2QnFH2Rav+ttpo1sDNyy1UEAuqmO0pawrPc5UJucvsJUzri944yRFiz4BtX1 Trig== 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=r46aBihEOGQbzY2WpFB3AupNkAhrK/38I7UbJd+jXYs=; b=YUk2B1KL0EDV59CAjLGGE5FIEH60d5vNzG2Y6OKnGsgYwglpnkG++lc1gQZXFyNRd8 d2wzH2UAfahH0RWopJoGxdnNkx8UybyfSBHJ6Vr1m8ckJlxnnIE0OT1A8YdCSzItPmB1 4Fq+MHUXkCpLXN0khHYKl1qydrfKpI+mL/rQrtNS3ElEBmE7gf1h1V0GUZaBOkbRH+Ka /PBCxskkmNj9RTgSjoBm9SnAv5PQhzWkqrLbrvyQwqQaj6wGtacfO3gTjtXxWuKQYpN+ a8WqAznXevDPMYzfXlDXEo4kfKtQJlg1EQ+Az+nYPwf3fQI3gAITiheqx3cz/TZvSu9F y1Ng== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=hj+8A4MG; 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 g6si1899737qkl.203.2020.02.06.09.44.46 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:44:46 -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=hj+8A4MG; 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]:43656 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlCo-0004Si-53 for patch@linaro.org; Thu, 06 Feb 2020 12:44:46 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43658) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl09-0006uu-AE for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:42 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl08-00071R-5Q for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:41 -0500 Received: from mail-wr1-x42b.google.com ([2a00:1450:4864:20::42b]:42904) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izl07-0006xa-V3 for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:40 -0500 Received: by mail-wr1-x42b.google.com with SMTP id k11so8181586wrd.9 for ; Thu, 06 Feb 2020 09:31:39 -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=r46aBihEOGQbzY2WpFB3AupNkAhrK/38I7UbJd+jXYs=; b=hj+8A4MGp5X+dxRQ1rF1O0gSrKg3TP0Jn6m+dX9hjIgl9pmrFNY9FA+vqDwmNG77pc JfbSerHKFnq9kWU2fypJ60cipFsCpMssa44FDAGclNeb8Uxn+Qbscy2/1+M74rmXWrig WU8UC6PcJo/2QIN5KMWIO45Ak21Lzgy4l/5pb+GxWIHVmcC9Srg9EbhK61zMb9x4bmpR kz+eDrixeMP5SuURsHPp5q6zWRqtfEFS4fIZq6FkQ8SNj9lUQaVo1PgHZvgKjgm6zXFE 8QIKihCxs4pQV72PhC/C8yfjZtq+9r5SESDhfsZGTwmrmHoNEh7vMtiyRXMP1/9PSpiQ jQLw== 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=r46aBihEOGQbzY2WpFB3AupNkAhrK/38I7UbJd+jXYs=; b=Ej7sM9/2M+YnS2MQRgCTEDT/FgOVHIDiXBEjd4l0VRDnjkzipM6kurdM20wJkUAPUp 1PTvdqMETzJcfFghsW30k48STIOpPKsCZXjViDbZtz3/Zu/ogLiOyR73PaIiu8krlhbM 0tuRSNMYPp/EtgtOSfB2A7xQLAboMeR/W9Mz4zJhAbNXZgyMq09mi2Cmxg+DcZro+a2m CgiiWSZvPXcBi4hv4yCwIpcuoUN7WX/6vx+OYgSYG/sjM1muBaGoIB1w9gzfsuiY3iGe QFWpyBnKdKPB8qiV55+PkePIsKvFo+JKdP7005Ern3+F+cQe5qpglp07UYlti6ve0Mcs M8mg== X-Gm-Message-State: APjAAAWKkkDDMHEJucoOKWYUbFwd9BArU8nENtJhkB37Ml/dmDKStUrN T1n1AR9mcAcPUGceEAFGPxYkIF6nkFk= X-Received: by 2002:adf:fa50:: with SMTP id y16mr5226789wrr.204.1581010298564; Thu, 06 Feb 2020 09:31:38 -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.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:38 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 26/29] qapi: Use rST markup for literal blocks Date: Thu, 6 Feb 2020 17:30:37 +0000 Message-Id: <20200206173040.17337-27-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::42b 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" There are exactly two places in our json doc comments where we use the markup accepted by the texi doc generator where a '|' in the first line of a doc comment means the line should be emitted as a literal block (fixed-width font, whitespace preserved). Since we use this syntax so rarely, instead of making the rST generator support it, instead just convert the two uses to rST-format literal blocks, which are indented and introduced with '::'. (The rST generator doesn't complain about the old style syntax, it just emits it with the '|' and with the whitespace not preserved, which looks odd, but means we can safely leave this change until after we've stopped generating texinfo.) Signed-off-by: Peter Maydell --- qapi/block-core.json | 16 +++++++++------- qapi/qapi-schema.json | 6 ++++-- 2 files changed, 13 insertions(+), 9 deletions(-) -- 2.20.1 diff --git a/qapi/block-core.json b/qapi/block-core.json index 092cd8f13d9..ea0371c33fb 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -550,13 +550,15 @@ # For the example above, @bins may be something like [3, 1, 5, 2], # and corresponding histogram looks like: # -# | 5| * -# | 4| * -# | 3| * * -# | 2| * * * -# | 1| * * * * -# | +------------------ -# | 10 50 100 +# :: +# +# 5| * +# 4| * +# 3| * * +# 2| * * * +# 1| * * * * +# +------------------ +# 10 50 100 # # Since: 4.0 ## diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index f7ba60a5d0b..1d3fb573846 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -22,8 +22,10 @@ # # Example: # -# | -> data issued by the Client -# | <- Server data response +# :: +# +# -> data issued by the Client +# <- Server data response # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. From patchwork Thu Feb 6 17:30:38 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183124 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1844299ile; Thu, 6 Feb 2020 09:44:38 -0800 (PST) X-Google-Smtp-Source: APXvYqxeLfYG9p4pkl3XkJ7lRcBG8+7LLEzoev33kGTVPBvXR5o7EEMPtW9TuLnXHZyY9/iyU7WH X-Received: by 2002:aed:3fb7:: with SMTP id s52mr3533190qth.97.1581011078803; Thu, 06 Feb 2020 09:44:38 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581011078; cv=none; d=google.com; s=arc-20160816; b=aoqlh0M26cFTqGTprSdaNeyYnq7xS6q5ApPDrKuV5o+O2IVYITWHrRr2D3kBt+20nG U6tdqYhUD68CPOOnEAN66zu9m/gEKGcTCmjTywN+ZBdW52+8cu3vg5zir5qe2fdafsuu 9hAq7DWf9BgS/HZjUxN8uiI+7AgYnhoNa4S6Sl0i+inkKLGEc0IJXVBd5cuDFOtZiUGR SFU7jOlvqRnqSEiiDnNfg5CPGd3eypC1vTBnwHJ7jz9b1oDbqXDbhwxhilGMfpZ8IGmA 3Q1AYVwxj55oFWTk0zd5ph7KGtPkBBoaIBSfvxobikqJVmSFW/R+Ab3abkkNTu07UxaV N9oA== 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=t+6Sog2K+ZVcTg/jfh6NF1pfex6NujGk7p8MyQqFuec=; b=ppDvCQBQ2q9VAz0aDwiefbCa0cVbSuaz1d7U63WEisV/toTLgHkBIS65orYmxxLJgy vza52+exm8aPvyaJSYCGYINLkYYlxehQHhsEqFugKY/oUcrHw+ZlFwbesLARz6XyP5yF 3+elYsZks87WufWWoPubg8WaWZScC6v1FefvFShUCLn0ZyJSglDt5Pjh1bs1BXex4peD 1EJA3sSP7Xlu/5FbADklcfFzX+PlOaA+tRhW4F0OFortuRY1tAKpHPWX2W+z0jbn184L hu5s+836Teef7Hxjqr8ku9hYPdWRTuLVnSFAbXTcuuxIHwelCSTdfx03xEn2nzWm2r46 47Ug== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="Bf1X+gN/"; 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 a17si2031409qkc.242.2020.02.06.09.44.38 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:44:38 -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="Bf1X+gN/"; 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]:43642 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlCg-0003eR-Ao for patch@linaro.org; Thu, 06 Feb 2020 12:44:38 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43684) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl0A-0006yR-U7 for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:43 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl09-00079B-Oi for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:42 -0500 Received: from mail-wr1-x441.google.com ([2a00:1450:4864:20::441]:37433) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izl09-00075g-Gp for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:41 -0500 Received: by mail-wr1-x441.google.com with SMTP id w15so8201938wru.4 for ; Thu, 06 Feb 2020 09:31:41 -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=t+6Sog2K+ZVcTg/jfh6NF1pfex6NujGk7p8MyQqFuec=; b=Bf1X+gN/uCwdxcYq+OcHFKR1c9QWhrjpWTwJdEDrkBDo5Tn85GshAXuMf6HN0WtlvD dH9YQsOyywi4A5RQO7z4PasqkiQJWTPWULmMGSjORF+4CJR16R2PETfTxjaDJpgG4EkQ SF1YoCOu1nuIQKnvR8JSKQUrWOnS77QZaMFpQE4jM+bS7bvf1ZS7Xm2Bu8QbNh0EStv9 7WDNdT7mHiByKpvWUxUA2RG4b0z9Pyyo/fBz87++LZsG6ozEsgzS3n1XAJR42f5hY9Si XFKj/8vaJDsOjon3q50cTBXl2acpSl8RyeiXuE9ffTzGHRojLfvWp7CP7W7krPZ34qC1 +N4A== 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=t+6Sog2K+ZVcTg/jfh6NF1pfex6NujGk7p8MyQqFuec=; b=I2MeTXnJopbJ/7Byc7CvAY87YWoiEoep8u+3vH39EyTIIC3MHzw70Eoz499td/Ok6z anc3GlOhCYgq+yPpjPfoIpF19l31kodPfPsY65S1AAP44zNkZaFOY7IRYoKoIc5fxPdP 7vCOxO4njq25+gpypdZThXbOKtYr9TTsGHpxFQtud7UrEztat40pbM4D9QlAqyKuaHnP vgVeiD/R8wu+zAGm2hIRymgDjCsXrnQlDRSztkBH8I+73diKrkY4B7uJFRmuZ69wsmef KsQ7BgxKPymAHPgMe/eyY4Hs17daE+DzG3Mr6H7AR8c/DRwcJH5GofdTCDeCcGvWI45A C/RQ== X-Gm-Message-State: APjAAAWZDNmczoxDK/97ufHeSa79XzqScmuj3sXpgmoVueI6e8Mbc2Yd tW5/TFVxHN/M9aOaP4FbEels/hu44/w= X-Received: by 2002:adf:df0e:: with SMTP id y14mr4670915wrl.377.1581010300052; Thu, 06 Feb 2020 09:31:40 -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.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:39 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 27/29] qga/qapi-schema.json: Add some headings Date: Thu, 6 Feb 2020 17:30:38 +0000 Message-Id: <20200206173040.17337-28-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::441 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" Add some section headings to the QGA json; this is purely so that we have some H1 headings, as otherwise each command ends up being visible in the interop/ manual's table of contents. In an ideal world there might be a proper 'Introduction' section the way there is in qapi/qapi-schema.json. Signed-off-by: Peter Maydell --- qga/qapi-schema.json | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) -- 2.20.1 diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 0e3a00ee052..0b44da359b6 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -1,14 +1,18 @@ # *-*- Mode: Python -*-* ## -# -# General note concerning the use of guest agent interfaces: -# +# = General note concerning the use of guest agent interfaces +## + +## # "unsupported" is a higher-level error than the errors that individual # commands might document. The caller should always be prepared to receive # QERR_UNSUPPORTED, even if the given command doesn't specify it, or doesn't # document any failure mode at all. -# +## + +## +# = QEMU guest agent protocol commands and structs ## { 'pragma': { 'doc-required': true } } From patchwork Thu Feb 6 17:30:39 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183131 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1849394ile; Thu, 6 Feb 2020 09:49:34 -0800 (PST) X-Google-Smtp-Source: APXvYqyRnNQOXPejaTb/EHtgPGh3dZRv4V3t56DDM7Phtv7KAH/So/GsV9MkT1yF3xNVKbkncV1f X-Received: by 2002:ac8:3482:: with SMTP id w2mr3716601qtb.192.1581011373558; Thu, 06 Feb 2020 09:49:33 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581011373; cv=none; d=google.com; s=arc-20160816; b=It5v3YKblTwl0r+C32+zk51yBvtX/swARw8Ep80SeFEjpOIJ4m9d+u1r553JxCOKKL TZqiJ2QxNdS2rvhznyZ7MOz93MKru3i+Pj6Gy3PWIRIaxK2knFakZkVquaAtzWvxUnjw z3y6ZYGtTSD5tu/yTYB2TLenuEwNVPCBh/OcmNMbeKAEoJRUtaOf9o7xj9q2oYcOdg8s 3nau4tN24QJxu4O72rqs+dXQUXxqc4jCyfXUcFpxC0DXoptgtOWS6RLDDpY5ep62kxOk FCOei6lRY6IJKcsZxdkWBz2Eg6oq0ZU5+xES0GxxNYyoXGiQFcEusIYGIPS2wj9K0vvx jwgg== 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=De2wmukXywbOCB6BvE2Tm39fg1QJNVUGNIoqYOFA1D8=; b=Ngg1Ytn5mdj86pBds5yPWRO9G3x8Z6SQqFAM7Utrv2zlvNTVhgPfKtssMhQ3zsfm8M p7jYaoIq64wuhhyu9uHBxpBTsGrCAaBcHcNcrrFvixn4aQQWyA7wnrRbnapfMTBDJ3AH 8k6Iq6NSPrshlzRj0xtEj6ut0XPrUO61vd3vAXfeVZEIoXZtzdEY998NqZ3jtCCoHr8C dBnZPDbjISyH+/OaJx35gqGoXwraWbOfrbzYIzqIUMgt3xttzC6LHm8Ow9To57ShtXKd Bry4C1/6LEFd7WrRuwN+P8V+MZ732VW353525t93o1K4TrAF9WEI49hRAMd0S0RIIGoq TVFA== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=URAL6PBe; 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 g21si96511qtp.41.2020.02.06.09.49.33 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:49:33 -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=URAL6PBe; 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]:43774 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlHQ-0003a6-Vc for patch@linaro.org; Thu, 06 Feb 2020 12:49:33 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43717) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl0E-00076T-EM for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:48 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl0B-0007JN-TR for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:46 -0500 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]:45392) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izl0B-0007ES-Iq for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:43 -0500 Received: by mail-wr1-x442.google.com with SMTP id a6so8165428wrx.12 for ; Thu, 06 Feb 2020 09:31:43 -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=De2wmukXywbOCB6BvE2Tm39fg1QJNVUGNIoqYOFA1D8=; b=URAL6PBeeD9a92918b1Gau8IfxinhB7yb2xxpkK0zkfodhnWjOKlsxUCzVzm4clG7W iEc24+h5lrzlZEr2Eb1glo0Nn9ThzKIGnMhqc+j1XaQX33hd5ahbUHqkklbUciwctawm cEMs8lGKFdaJSBiZqguPltWjNk8Vw7kwW58YwCgqOnx1PbrSMQ3AqOM8OcE5MKpxYy07 LQ+wPZYZtMk3ppWwr/P7MGgsxvcr4zFKuEZyqXu9EujxlqQPcrDWTe/NskpuCJvJe50x WGf6AfWX3Zg0Nz+XELbOaImC+Kx9897necJniNdbRJs6voeDv1oOnhU0OXgvW2EfyjU6 ZeiA== 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=De2wmukXywbOCB6BvE2Tm39fg1QJNVUGNIoqYOFA1D8=; b=DnT+uhyGZ8C768h8XjVUYTOQcKuoGb1fcCzEIcmpRwO+3cOWFMkB2rfOBtB1oNS4e5 uuy4xwkMGL493JZ5Y4XMPOdLOp7Bsq4i0gkLTJg7Efwxij/2JqAe7K/gGZ+i4Hq7NHW0 rfNlMRXIYkA/Ym1i/6gluaSxdO3C6AR4Sa7nBXErzgJFlLXwOwgpkrs+ru2vPyg5gHJa CBd9OwJ0csFikjt1vIQvv08H4ctbthjnxKQiZ/vrR4aCOtUmrNV5/UVTClpiHvp70w1H 1GSLNkl+lq4FWE/xVnI3ZUgTrY1yHp9vl467kZ1XT1GeSYCr0JIQvwpBYbdstifEzPtR qJlg== X-Gm-Message-State: APjAAAW5EK6ZM7nbxJyBNi61kqg/G6nw0lJH3xAAfAPn9hTf5nfPv1sx Wi9r0EdlcGWFj4102N9ZhrJb+Z38Xxc= X-Received: by 2002:adf:f1c6:: with SMTP id z6mr4640238wro.279.1581010301883; Thu, 06 Feb 2020 09:31:41 -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.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:41 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 28/29] scripts/qapi: Remove texinfo generation support Date: Thu, 6 Feb 2020 17:30:39 +0000 Message-Id: <20200206173040.17337-29-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::442 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" We no longer use the generated texinfo format documentation, so delete the code that generates it, and the test case for the generation. Signed-off-by: Peter Maydell --- Makefile | 1 - tests/Makefile.include | 15 +- scripts/qapi-gen.py | 2 - scripts/qapi/doc.py | 303 ----------------------------------------- scripts/qapi/gen.py | 7 - 5 files changed, 1 insertion(+), 327 deletions(-) delete mode 100644 scripts/qapi/doc.py -- 2.20.1 diff --git a/Makefile b/Makefile index 159ac78dd24..8213dfec013 100644 --- a/Makefile +++ b/Makefile @@ -595,7 +595,6 @@ qemu-keymap$(EXESUF): QEMU_CFLAGS += $(XKBCOMMON_CFLAGS) qapi-py = $(SRC_PATH)/scripts/qapi/__init__.py \ $(SRC_PATH)/scripts/qapi/commands.py \ $(SRC_PATH)/scripts/qapi/common.py \ -$(SRC_PATH)/scripts/qapi/doc.py \ $(SRC_PATH)/scripts/qapi/error.py \ $(SRC_PATH)/scripts/qapi/events.py \ $(SRC_PATH)/scripts/qapi/expr.py \ diff --git a/tests/Makefile.include b/tests/Makefile.include index 2f1cafed720..ee766a77091 100644 --- a/tests/Makefile.include +++ b/tests/Makefile.include @@ -32,7 +32,6 @@ export SRC_PATH qapi-py = $(SRC_PATH)/scripts/qapi/__init__.py \ $(SRC_PATH)/scripts/qapi/commands.py \ $(SRC_PATH)/scripts/qapi/common.py \ -$(SRC_PATH)/scripts/qapi/doc.py \ $(SRC_PATH)/scripts/qapi/error.py \ $(SRC_PATH)/scripts/qapi/events.py \ $(SRC_PATH)/scripts/qapi/expr.py \ @@ -486,16 +485,8 @@ tests/test-qapi-gen-timestamp: \ $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \ -o tests -p "test-" $<, \ "GEN","$(@:%-timestamp=%)") - @rm -f tests/test-qapi-doc.texi @>$@ -tests/qapi-schema/doc-good.test.texi: $(SRC_PATH)/tests/qapi-schema/doc-good.json $(qapi-py) - $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \ - -o tests/qapi-schema -p "doc-good-" $<, \ - "GEN","$@") - @mv tests/qapi-schema/doc-good-qapi-doc.texi $@ - @rm -f tests/qapi-schema/doc-good-qapi-*.[ch] tests/qapi-schema/doc-good-qmp-*.[ch] - tests/qtest/dbus-vmstate1.h tests/qtest/dbus-vmstate1.c: tests/qtest/dbus-vmstate1-gen-timestamp ; tests/qtest/dbus-vmstate1-gen-timestamp: $(SRC_PATH)/tests/qtest/dbus-vmstate1.xml $(call quiet-command,$(GDBUS_CODEGEN) $< \ @@ -847,10 +838,6 @@ check-tests/qapi-schema/frontend: $(addprefix $(SRC_PATH)/, $(check-qapi-schema- PYTHONIOENCODING=utf-8 $(PYTHON) $(SRC_PATH)/tests/qapi-schema/test-qapi.py $^, \ TEST, check-qapi-schema) -.PHONY: check-tests/qapi-schema/doc-good.texi -check-tests/qapi-schema/doc-good.texi: tests/qapi-schema/doc-good.test.texi - @diff -u $(SRC_PATH)/tests/qapi-schema/doc-good.texi $< - .PHONY: check-decodetree check-decodetree: $(call quiet-command, \ @@ -898,7 +885,7 @@ check-acceptance: check-venv $(TESTS_RESULTS_DIR) # Consolidated targets .PHONY: check-block check-qapi-schema check-qtest check-unit check check-clean -check-qapi-schema: check-tests/qapi-schema/frontend check-tests/qapi-schema/doc-good.texi +check-qapi-schema: check-tests/qapi-schema/frontend check-qtest: $(patsubst %,check-qtest-%, $(QTEST_TARGETS)) ifeq ($(CONFIG_TOOLS),y) check-block: $(patsubst %,check-%, $(check-block-y)) diff --git a/scripts/qapi-gen.py b/scripts/qapi-gen.py index f93f3c7c233..2d39714fa36 100755 --- a/scripts/qapi-gen.py +++ b/scripts/qapi-gen.py @@ -11,7 +11,6 @@ import re import sys from qapi.commands import gen_commands -from qapi.doc import gen_doc from qapi.events import gen_events from qapi.introspect import gen_introspect from qapi.schema import QAPIError, QAPISchema @@ -52,7 +51,6 @@ def main(argv): gen_commands(schema, args.output_dir, args.prefix) gen_events(schema, args.output_dir, args.prefix) gen_introspect(schema, args.output_dir, args.prefix, args.unmask) - gen_doc(schema, args.output_dir, args.prefix) if __name__ == '__main__': diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py deleted file mode 100644 index 96346c9b14f..00000000000 --- a/scripts/qapi/doc.py +++ /dev/null @@ -1,303 +0,0 @@ -# QAPI texi generator -# -# This work is licensed under the terms of the GNU LGPL, version 2+. -# See the COPYING file in the top-level directory. -"""This script produces the documentation of a qapi schema in texinfo format""" - -from __future__ import print_function -import re -from qapi.gen import QAPIGenDoc, QAPISchemaVisitor - - -MSG_FMT = """ -@deftypefn {type} {{}} {name} - -{body}{members}{features}{sections} -@end deftypefn - -""".format - -TYPE_FMT = """ -@deftp {{{type}}} {name} - -{body}{members}{features}{sections} -@end deftp - -""".format - -EXAMPLE_FMT = """@example -{code} -@end example -""".format - - -def subst_strong(doc): - """Replaces *foo* by @strong{foo}""" - return re.sub(r'\*([^*\n]+)\*', r'@strong{\1}', doc) - - -def subst_emph(doc): - """Replaces _foo_ by @emph{foo}""" - return re.sub(r'\b_([^_\n]+)_\b', r'@emph{\1}', doc) - - -def subst_vars(doc): - """Replaces @var by @code{var}""" - return re.sub(r'@([\w-]+)', r'@code{\1}', doc) - - -def subst_braces(doc): - """Replaces {} with @{ @}""" - return doc.replace('{', '@{').replace('}', '@}') - - -def texi_example(doc): - """Format @example""" - # TODO: Neglects to escape @ characters. - # We should probably escape them in subst_braces(), and rename the - # function to subst_special() or subs_texi_special(). If we do that, we - # need to delay it until after subst_vars() in texi_format(). - doc = subst_braces(doc).strip('\n') - return EXAMPLE_FMT(code=doc) - - -def texi_format(doc): - """ - Format documentation - - Lines starting with: - - |: generates an @example - - =: generates @section - - ==: generates @subsection - - 1. or 1): generates an @enumerate @item - - */-: generates an @itemize list - """ - ret = '' - doc = subst_braces(doc) - doc = subst_vars(doc) - doc = subst_emph(doc) - doc = subst_strong(doc) - inlist = '' - lastempty = False - for line in doc.split('\n'): - line = line.strip() - empty = line == '' - - # FIXME: Doing this in a single if / elif chain is - # problematic. For instance, a line without markup terminates - # a list if it follows a blank line (reaches the final elif), - # but a line with some *other* markup, such as a = title - # doesn't. - # - # Make sure to update section "Documentation markup" in - # docs/devel/qapi-code-gen.txt when fixing this. - if line.startswith('| '): - line = EXAMPLE_FMT(code=line[2:]) - elif line.startswith('= '): - line = '@section ' + line[2:] - elif line.startswith('== '): - line = '@subsection ' + line[3:] - elif re.match(r'^([0-9]*\.) ', line): - if not inlist: - ret += '@enumerate\n' - inlist = 'enumerate' - ret += '@item\n' - line = line[line.find(' ')+1:] - elif re.match(r'^[*-] ', line): - if not inlist: - ret += '@itemize %s\n' % {'*': '@bullet', - '-': '@minus'}[line[0]] - inlist = 'itemize' - ret += '@item\n' - line = line[2:] - elif lastempty and inlist: - ret += '@end %s\n\n' % inlist - inlist = '' - - lastempty = empty - ret += line + '\n' - - if inlist: - ret += '@end %s\n\n' % inlist - return ret - - -def texi_body(doc): - """Format the main documentation body""" - return texi_format(doc.body.text) - - -def texi_if(ifcond, prefix='\n', suffix='\n'): - """Format the #if condition""" - if not ifcond: - return '' - return '%s@b{If:} @code{%s}%s' % (prefix, ', '.join(ifcond), suffix) - - -def texi_enum_value(value, desc, suffix): - """Format a table of members item for an enumeration value""" - return '@item @code{%s}\n%s%s' % ( - value.name, desc, texi_if(value.ifcond, prefix='@*')) - - -def texi_member(member, desc, suffix): - """Format a table of members item for an object type member""" - typ = member.type.doc_type() - membertype = ': ' + typ if typ else '' - return '@item @code{%s%s}%s%s\n%s%s' % ( - member.name, membertype, - ' (optional)' if member.optional else '', - suffix, desc, texi_if(member.ifcond, prefix='@*')) - - -def texi_members(doc, what, base=None, variants=None, - member_func=texi_member): - """Format the table of members""" - items = '' - for section in doc.args.values(): - # TODO Drop fallbacks when undocumented members are outlawed - if section.text: - desc = texi_format(section.text) - elif (variants and variants.tag_member == section.member - and not section.member.type.doc_type()): - values = section.member.type.member_names() - members_text = ', '.join(['@t{"%s"}' % v for v in values]) - desc = 'One of ' + members_text + '\n' - else: - desc = 'Not documented\n' - items += member_func(section.member, desc, suffix='') - if base: - items += '@item The members of @code{%s}\n' % base.doc_type() - if variants: - for v in variants.variants: - when = ' when @code{%s} is @t{"%s"}%s' % ( - variants.tag_member.name, v.name, texi_if(v.ifcond, " (", ")")) - if v.type.is_implicit(): - assert not v.type.base and not v.type.variants - for m in v.type.local_members: - items += member_func(m, desc='', suffix=when) - else: - items += '@item The members of @code{%s}%s\n' % ( - v.type.doc_type(), when) - if not items: - return '' - return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items) - - -def texi_arguments(doc, boxed_arg_type): - if boxed_arg_type: - assert not doc.args - return ('\n@b{Arguments:} the members of @code{%s}\n' - % boxed_arg_type.name) - return texi_members(doc, 'Arguments') - - -def texi_features(doc): - """Format the table of features""" - items = '' - for section in doc.features.values(): - desc = texi_format(section.text) - items += '@item @code{%s}\n%s' % (section.name, desc) - if not items: - return '' - return '\n@b{Features:}\n@table @asis\n%s@end table\n' % (items) - - -def texi_sections(doc, ifcond): - """Format additional sections following arguments""" - body = '' - for section in doc.sections: - if section.name: - # prefer @b over @strong, so txt doesn't translate it to *Foo:* - body += '\n@b{%s:}\n' % section.name - if section.name and section.name.startswith('Example'): - body += texi_example(section.text) - else: - body += texi_format(section.text) - body += texi_if(ifcond, suffix='') - return body - - -def texi_type(typ, doc, ifcond, members): - return TYPE_FMT(type=typ, - name=doc.symbol, - body=texi_body(doc), - members=members, - features=texi_features(doc), - sections=texi_sections(doc, ifcond)) - - -def texi_msg(typ, doc, ifcond, members): - return MSG_FMT(type=typ, - name=doc.symbol, - body=texi_body(doc), - members=members, - features=texi_features(doc), - sections=texi_sections(doc, ifcond)) - - -class QAPISchemaGenDocVisitor(QAPISchemaVisitor): - def __init__(self, prefix): - self._prefix = prefix - self._gen = QAPIGenDoc(self._prefix + 'qapi-doc.texi') - self.cur_doc = None - - def write(self, output_dir): - self._gen.write(output_dir) - - def visit_enum_type(self, name, info, ifcond, members, prefix): - doc = self.cur_doc - self._gen.add(texi_type('Enum', doc, ifcond, - texi_members(doc, 'Values', - member_func=texi_enum_value))) - - def visit_object_type(self, name, info, ifcond, base, members, variants, - features): - doc = self.cur_doc - if base and base.is_implicit(): - base = None - self._gen.add(texi_type('Object', doc, ifcond, - texi_members(doc, 'Members', base, variants))) - - def visit_alternate_type(self, name, info, ifcond, variants): - doc = self.cur_doc - self._gen.add(texi_type('Alternate', doc, ifcond, - texi_members(doc, 'Members'))) - - def visit_command(self, name, info, ifcond, arg_type, ret_type, gen, - success_response, boxed, allow_oob, allow_preconfig, - features): - doc = self.cur_doc - self._gen.add(texi_msg('Command', doc, ifcond, - texi_arguments(doc, - arg_type if boxed else None))) - - def visit_event(self, name, info, ifcond, arg_type, boxed): - doc = self.cur_doc - self._gen.add(texi_msg('Event', doc, ifcond, - texi_arguments(doc, - arg_type if boxed else None))) - - def symbol(self, doc, entity): - if self._gen._body: - self._gen.add('\n') - self.cur_doc = doc - entity.visit(self) - self.cur_doc = None - - def freeform(self, doc): - assert not doc.args - if self._gen._body: - self._gen.add('\n') - self._gen.add(texi_body(doc) + texi_sections(doc, None)) - - -def gen_doc(schema, output_dir, prefix): - vis = QAPISchemaGenDocVisitor(prefix) - vis.visit_begin(schema) - for doc in schema.docs: - if doc.symbol: - vis.symbol(doc, schema.lookup_entity(doc.symbol)) - else: - vis.freeform(doc) - vis.write(output_dir) diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py index 95afae0615a..7712d2d49f7 100644 --- a/scripts/qapi/gen.py +++ b/scripts/qapi/gen.py @@ -177,13 +177,6 @@ def ifcontext(ifcond, *args): arg.end_if() -class QAPIGenDoc(QAPIGen): - - def _top(self): - return (QAPIGen._top(self) - + '@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n\n') - - class QAPISchemaMonolithicCVisitor(QAPISchemaVisitor): def __init__(self, prefix, what, blurb, pydoc): From patchwork Thu Feb 6 17:30:40 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 183129 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp1849080ile; Thu, 6 Feb 2020 09:49:14 -0800 (PST) X-Google-Smtp-Source: APXvYqwlfDfUGXd1UwEy8HivwcMhtJqN7QW5zh+qphV+JfCs4ZvTx0+RLXTEQ7LYZzoPKCMOkK8Y X-Received: by 2002:a05:620a:6b8:: with SMTP id i24mr3741352qkh.9.1581011353994; Thu, 06 Feb 2020 09:49:13 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581011353; cv=none; d=google.com; s=arc-20160816; b=ciX9/zBfSx+P7BSLpT6nBoi0FsMs6beDWGu1/N8KuJ5S26K5WTB1rKBUgmdb6cZCSg 9Of7QgSq48VFb8Y4abNSO6nszQZZGCU6q/7258uuaEWQQu6QRZUl9RByzXqEmR3m4NWn E6vsPyhlYFw/nX8tUr33qt89JUd5zJEb7R3RQDKbqIHi2pSTRPc8sJ/RNITLcTeoqdSc CtK3JpsoPCvSNE7qL7gpiXGEFQ+hRAfwRXQ5RWi6u4f1fds0RNNGdJm2nn5KQ/2t84g1 RFMUxTwJ1o024XFycCEb7vgcg2LEEJ9mb9QQ7oDmYe7rQMrnth8PGWxtfmmAbnJhJURM yAIA== 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=AtxEKrKRqNjfOrT9JbNHlMjgTudjr9VoMdnqfaiOYHo=; b=vCI/cXWL+9UiwqUkMGvyZLo4mTsdwXFLCrVQUDLDhJImGIBmcdNs46CBoPAdaoulhC XVrgkCSe55h//Q6om7SpT4uXGcv8UJtAhJwDZRP5lFhwSFvScminuqq4COkp0N+e5w81 P/h1AaeA1sq/LE9HirC0aMEogWKTmZtaGONmdTzsjKH5aETpL0pti6zfVM+5HKZd6Hzp Jhwa4pV41abGS/iUGLFc4zfN1SafR6sDZfLsbHaXr2A3ab9+wVpostWdT10z0hWY5Vu5 L8EtkGsnTJeBpNjjUxnHvxSHz9rymKNo/LJQUFUZknU11CugWo1O904iCxCNw3Ekesu8 LWpQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=pbmruM8Y; 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 e25si2033643qkl.373.2020.02.06.09.49.13 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 06 Feb 2020 09:49:13 -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=pbmruM8Y; 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]:43770 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izlH7-0003RR-Gc for patch@linaro.org; Thu, 06 Feb 2020 12:49:13 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:43720) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1izl0E-00077M-RN for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:48 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1izl0D-0007PV-8r for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:46 -0500 Received: from mail-wr1-x441.google.com ([2a00:1450:4864:20::441]:44252) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1izl0D-0007Lw-0q for qemu-devel@nongnu.org; Thu, 06 Feb 2020 12:31:45 -0500 Received: by mail-wr1-x441.google.com with SMTP id m16so8171841wrx.11 for ; Thu, 06 Feb 2020 09:31:44 -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=AtxEKrKRqNjfOrT9JbNHlMjgTudjr9VoMdnqfaiOYHo=; b=pbmruM8YbkTpjiYhOedn8z5wFg4jSKmwzn+kn7hTm033lhV5v/TH2hoBMf2l+Yrdwz a8sK1QuJFXpobaSBLsNX1TIaJw+JVic0fgh1rVToMc8wG9V07K0N9i0LtzF6wLJUFOTO 4L4y9fbb7aHVaq//1iEaOycU2VUhHvKudyCdOM+gyDd3elrqHFcOpZ0F0agw0woHpJNQ ZsXuAY0KnyGvzt4yszJRz/WtRXKiQoQOPJat89e3Q3IXMJtmW6/jEq9JPKABepuiGOMd /TmwuP2aeGmkowe8xTWHZjOWYhSwrYgbZ/SrXOyd3xEwRm/gULTQYNf/Rc+cwOrVXzQX qGIQ== 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=AtxEKrKRqNjfOrT9JbNHlMjgTudjr9VoMdnqfaiOYHo=; b=pBm23kMOT6cwHo1RKzQ6kRgstJXNYaOq4WNKwvFkmgtSJsE/ruYZKxGeMotnH52Qej 5XQUvAPw3sm9dAxfcX4Ca6e2oOErhdh/tS6U7SN8si8eDvRvKgqLQl2pckFUoAGt8LH6 bwL64BRYfwDaIK+D2Z5NHRJ61GoQ9NhLatQ0XFLvx4ExZSYPcJOdq2OY2rz0QOCk+pzU jmAAoauAbhpMM0Bo6M4GHLh+HmFPuoWf9bVm7P/XmIkSE96HcVSWfUGadTpabK8yziV4 R+ux2/5XVth/+9G0MGOgPLr/NhICrOoKlb2ks+1DR0B8Ym6owc7QLRwpuZajtYStPzfu /hOA== X-Gm-Message-State: APjAAAU8fPJkN9xOyxouXXLnuxhI8VNonyWLdVJDO0Vj3jeRu+XxoBVr HP72aFZL+U31P0dgj84LbSY5sRIsXps= X-Received: by 2002:adf:f3cc:: with SMTP id g12mr4802565wrp.236.1581010303402; Thu, 06 Feb 2020 09:31:43 -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.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Feb 2020 09:31:42 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 29/29] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions Date: Thu, 6 Feb 2020 17:30:40 +0000 Message-Id: <20200206173040.17337-30-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::441 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" Update the documentation of QAPI document comment syntax to match the new rST backend requirements. The principal changes are: * whitespace is now significant, and multiline definitions must have their second and subsequent lines indented to match the first line * general rST format markup is permitted, not just the small set of markup the old texinfo generator handled. For most things (notably bulleted and itemized lists) the old format is the same as rST was. * Specific things that might trip people up: - instead of *bold* and _italic_ rST has **bold** and *italic* - lists need a preceding and following blank line - a lone literal '*' will need to be backslash-escaped to avoid a rST syntax error * the old leading '|' for example (literal text) blocks is replaced by the standard rST '::' literal block. * headings and subheadings must now be in a freeform documentation comment of their own * we support arbitrary levels of sub- and sub-sub-heading, not just a main and sub-heading like the old texinfo generator Signed-off-by: Peter Maydell --- docs/devel/qapi-code-gen.txt | 90 ++++++++++++++++++++++++------------ 1 file changed, 61 insertions(+), 29 deletions(-) -- 2.20.1 diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 59d6973e1ec..688eb2a0237 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -795,21 +795,39 @@ See below for more on definition documentation. Free-form documentation may be used to provide additional text and structuring content. +==== Headings and subheadings ==== + +A free-form documentation comment containing a single line +which starts with some '=' symbols and then a space defines +a section heading: + + ## + # = This is a top level heading + ## + + ## + # This is a free-form comment which will go under the + # top level heading. + ## + + ## + # == This is a second level heading + ## + +Section headings must always be correctly nested, so you can only +define a third-level heading inside a second-level heading, and so +on. The documentation generator will catch nesting mistakes and report +a syntax error. ==== Documentation markup ==== -Comment text starting with '=' is a section title: +Documentation comments can use most rST markup. In particular, +a '::' literal block can be used for examples: - # = Section title - -Double the '=' for a subsection title: - - # == Subsection title - -'|' denotes examples: - - # | Text of the example, may span - # | multiple lines + # :: + # + # Text of the example, may span + # multiple lines '*' starts an itemized list: @@ -825,37 +843,35 @@ A decimal number followed by '.' starts a numbered list: # multiple lines # 2. Second item -The actual number doesn't matter. You could even use '*' instead of -'2.' for the second item. +The actual number doesn't matter. -Lists can't be nested. Blank lines are currently not supported within -lists. +Lists of either kind must be preceded and followed by a blank line. +If a list item's text spans multiple lines, then the second and +subsequent lines must be correctly indented to line up with the +first character of the first line. -Additional whitespace between the initial '#' and the comment text is -permitted. - -*foo* and _foo_ are for strong and emphasis styles respectively (they -do not work over multiple lines). @foo is used to reference a name in -the schema. +The usual '**strong**', '*emphasised*' and '``literal``' markup should +be used. If you need a single literal '*' you will need to backslash-escape it. +As an extension beyond the usual rST syntax, you can also +use '@foo' to reference a name in the schema; this is rendered +the same way as '``foo``'. Example: ## -# = Section -# == Subsection -# -# Some text foo with *strong* and _emphasis_ +# Some text foo with **bol** and *emphasis* # 1. with a list # 2. like that # # And some code: -# | $ echo foo -# | -> do this -# | <- get that # +# :: +# +# $ echo foo +# -> do this +# <- get that ## - ==== Definition documentation ==== Definition documentation, if present, must immediately precede the @@ -870,6 +886,12 @@ commands and events), member (for structs and unions), branch (for alternates), or value (for enums), and finally optional tagged sections. +Descriptions of arguments can span multiple lines; if they +do then the second and subsequent lines must be indented +to line up with the first character of the first line of the +description. The parser will report a syntax error if there +is insufficient indentation. + FIXME: the parser accepts these things in almost any order. FIXME: union branches should be described, too. @@ -883,6 +905,16 @@ The section ends with the start of a new section. A 'Since: x.y.z' tagged section lists the release that introduced the definition. +The text of a section can start on a new line, in +which case it must not be indented at all. It can also start +on the same line as the 'Note:', 'Returns:', etc tag. In this +case if it spans multiple lines then second and subsequent +lines must be indented to match the first. + +An 'Example' or 'Examples' section is automatically rendered +entirely as literal fixed-width text. In other sections, +the text is formatted, and rST markup can be used. + For example: ##