From nobody Tue Feb 10 15:46:26 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1597089138; cv=none; d=zohomail.com; s=zohoarc; b=aJzZ9BYo5n11qJAFxDjAwJwJnPzXYK/9QQL12XPoTGZwE5/x7ludRmpgniL58HE/wNO9PsVBg8TrDoDOA+9dLXXTizHPRmAIxiOi1aPvns5wpgMaJGUZ0pEPr7zHbRca0pvhtPCS0cuM5THIUv12PTq/XHvWeeQYgJXL6bExaZ0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1597089138; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=e0cYa2LpgDtFPEx6dbDjbhZ7m+B+8SmWLGFLVWEF5JA=; b=mVLOTBbRn/lXgXgK9U3ddP/3Yj5VEZO5FHda1+6gOVpL/O1+Q9xf3ea5flSRD4H/lKYRj55p40WYZFY04l3enKXod5db2MQJWxQvIIDiqtEqgWoCG+kUwPFxfhNFAck3TM4D3Sne3KmxaJC41J2aMBcw3a73/iMLNi9D5qX6woo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1597089138725793.9753303345437; Mon, 10 Aug 2020 12:52:18 -0700 (PDT) Received: from localhost ([::1]:37412 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DqD-0003dd-D6 for importer@patchew.org; Mon, 10 Aug 2020 15:52:17 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51098) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Doc-0000Kw-2y for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:38 -0400 Received: from mail-wr1-x441.google.com ([2a00:1450:4864:20::441]:45031) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Doa-0004kz-4p for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:37 -0400 Received: by mail-wr1-x441.google.com with SMTP id c15so9293830wrs.11 for ; Mon, 10 Aug 2020 12:50:35 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:33 -0700 (PDT) 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=e0cYa2LpgDtFPEx6dbDjbhZ7m+B+8SmWLGFLVWEF5JA=; b=qoFwy4I7lwv+KfNqEeMprNM3B5CBTEDKAzGEaq9BEcHBVUHIUXbelf85gUJdVhi71L W7uF8P9XFy4YETsxBRXONwXJ6Uc5ydg7itBPaZ+1mXhBoftWr4/Bih2BTHPyRVQsRJKQ uJcZrlpqydhjEMNUxyvQaDrUZiIMqIC7i02ypYvQKN9VBVIj/3oHb4R6VazKWs9Ex/7F ZR/j7RdLKVzT/DskaZgc9vZOKBfq4Npf+K40OI9T7BVCjPFZryGgqvsMvqw4XdRXzZ5X 6ivEBmBs8oAkhqkUyZ9lhHZniv87f2WZUsn1vb0cShsLp0AfIuO5lXYKzDIBK1RJu4DG rZKQ== 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=e0cYa2LpgDtFPEx6dbDjbhZ7m+B+8SmWLGFLVWEF5JA=; b=RbxzIf50b8nSepOsZ3w+bWmhWsz9EHrWEvJWDTGycl7VJK8WoOEbJySuQQxhzEbKho JX0xfIZcUp544s/BgJlf0uJC5aYk9xzzaMCop5rSyexJpr+SFYrNv5XSgU+PdgJbmLHc U6m/i1b46W8fVNVpCy0hFoXrQekrygDtUVfbIUKqsmsfQSN4yNCf8sFGUQ1T0ecQD6OR zToJ22Sk4LMGNXRlEthE1PB8el1xA8V/QtpKSVutgd2upOKMWfAYAzRKzM/4OjnV48dQ n8MEMv6sQdDO1eTUCSLXqnvBN+ZaBB84TvDoB4mH9yeEsVWoRD67KWaIuiThmZU280wm zSCw== X-Gm-Message-State: AOAM533+9EXrYrMIRZyvxXmRajCTqpInbnbut9AdNJBScZtf9h9qRCGA K+Kxe1MpUVkXSudfV6sySsI8wnUUdQP/Mw== X-Google-Smtp-Source: ABdhPJyJJWeNeJSU1em6JiPRw8PNkcCgebBwIy1zbRFa0bNKPHIlgOYO1HzFozWR3k635T0D/xM0Xw== X-Received: by 2002:adf:9ed4:: with SMTP id b20mr26158582wrf.206.1597089033962; Mon, 10 Aug 2020 12:50:33 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 07/20] scripts/qapi: Move doc-comment whitespace stripping to doc.py Date: Mon, 10 Aug 2020 20:50:06 +0100 Message-Id: <20200810195019.25427-8-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::441; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x441.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action 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: Markus Armbruster Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" 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. Because the qapi-schema test checks the exact values of the documentation comments against a reference, we need to update that reference to match the new whitespace. In the first four places this is now correctly checking that we did put in the amount of whitespace to pass a rST-formatted list to the backend; in the last two places the extra whitespace is 'wrong' and will go away again in the following commit. Reviewed-by: Richard Henderson Reviewed-by: Markus Armbruster Signed-off-by: Peter Maydell --- v4->v5: just fixed the caps in 'Texinfo' in commit message --- scripts/qapi/doc.py | 1 + scripts/qapi/parser.py | 12 ++++-------- tests/qapi-schema/doc-good.out | 12 ++++++------ 3 files changed, 11 insertions(+), 14 deletions(-) diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py index 92f584edcf1..7764de1e4bc 100644 --- a/scripts/qapi/doc.py +++ b/scripts/qapi/doc.py @@ -79,6 +79,7 @@ def texi_format(doc): inlist =3D '' lastempty =3D False for line in doc.split('\n'): + line =3D line.strip() empty =3D line =3D=3D '' =20 # FIXME: Doing this in a single if / elif chain is diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index abadacbb0e8..7fae4478d34 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -417,10 +417,10 @@ class QAPIDoc: self._append_line =3D 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) =20 def _append_args_line(self, line): """ @@ -453,7 +453,7 @@ class QAPIDoc: self._append_various_line(line) return =20 - self._append_freeform(line.strip()) + self._append_freeform(line) =20 def _append_features_line(self, line): name =3D line.split(' ', 1)[0] @@ -472,7 +472,7 @@ class QAPIDoc: self._append_various_line(line) return =20 - self._append_freeform(line.strip()) + self._append_freeform(line) =20 def _append_various_line(self, line): """ @@ -495,10 +495,6 @@ class QAPIDoc: line =3D line[len(name)+1:] self._start_section(name[:-1]) =20 - if (not self._section.name or - not self._section.name.startswith('Example')): - line =3D line.strip() - self._append_freeform(line) =20 def _start_symbol_section(self, symbols_dict, name): diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 4c24eb96486..0ef85d959ac 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -77,20 +77,20 @@ doc freeform =20 * List item one * Two, multiple -lines + lines =20 * Three -Still in list + Still in list =20 Not in list =20 - Second list -Note: still in list + Note: still in list =20 Note: not in list =20 1. Third list -is numbered + is numbered =20 2. another item =20 @@ -158,7 +158,7 @@ doc symbol=3DAlternate =20 arg=3Di an integer -@b is undocumented + @b is undocumented arg=3Db =20 feature=3Dalt-feat @@ -173,7 +173,7 @@ doc symbol=3Dcmd the first argument arg=3Darg2 the second -argument + argument arg=3Darg3 =20 feature=3Dcmd-feat1 --=20 2.20.1