From patchwork Thu Feb 13 17:56: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: 183426 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp841055ile; Thu, 13 Feb 2020 10:16:47 -0800 (PST) X-Google-Smtp-Source: APXvYqzFEDpD5EEqeUH2aLm8z1f6x+vG5p8tXdQjnouJaOY47c2uf2XfvITsFzgSVskKXhOndHbg X-Received: by 2002:a05:620a:1679:: with SMTP id d25mr13042011qko.67.1581617807716; Thu, 13 Feb 2020 10:16:47 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1581617807; cv=none; d=google.com; s=arc-20160816; b=WjihXWuGj5Qw1Z5rrQEEeYp4lCG4jCrcbxUaDh59YtFR7gUK14TwRdsc66KN/5BWtq lKkl9ttByGvmE63/ZAXErzFDnlyoRPcJhC/0unsieybLqJy32T2ufJ/AY6RCMNarRXoz 1lvx7TxC0cqu4HtHYG7O9sgxVOfKIU3S0hsDQ+C1SI8iSAiaZI0RFXs1sTonIM4cHAYV eJndV8MSU9nd/uIIBPnVnnHAHvgNt9V+/6vGZBMnu7ZZVeS7rw8r77pRw1bgxbPJ98aG B6T8p1EameJU492W+6yHsvCM8JulTMPLnI8qA/QWuGE7md8xIEiMW8itp3sv8KgW888w T4Ag== 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=wpXd5QxscHZ5Ze+pVlbaJlNdMe0Q3RlgSzZJLeNwcSk=; b=bwh1wIrff09yt5Ohxhbx7IYi/s0sYwaaS3c1CWNDSqO7ZKCrcBWetqJhUYZU3U2vm/ 2xzT0NmVwR136t7xKfv/Hf5N6OrXGZPHDjLhPoGAEoZdRXk7oV8LUt8q9bjaQbr8lUTg 50NtPoPctZZ+2Ytnkepsdc1NbV7OhyxeZNemLignWlDDylz3+EcIXXfHOQSFV7XrBSuy VT09KW1fHLv0iIGUaCfA7vDnrW9H5FPuFrYu0Zt9Dt8GWnKjMtdisdOTofvoukMaHR6+ LIR5/IDSelUgki3ccXk5Q8clRvGI1REUdVbXy6bWMHUTRqz7fMIMZS+LrM2WZb2jqJIL lhmw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=UirwSC0W; 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 y200si1567817qka.124.2020.02.13.10.16.47 for (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 13 Feb 2020 10:16: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=UirwSC0W; 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]:57524 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j2J2d-00018o-5c for patch@linaro.org; Thu, 13 Feb 2020 13:16:47 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:34338) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j2Ijr-0000mL-HN for qemu-devel@nongnu.org; Thu, 13 Feb 2020 12:57:24 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j2Ijp-00035l-T4 for qemu-devel@nongnu.org; Thu, 13 Feb 2020 12:57:23 -0500 Received: from mail-wr1-x42d.google.com ([2a00:1450:4864:20::42d]:33657) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j2Ijp-00033Q-Km for qemu-devel@nongnu.org; Thu, 13 Feb 2020 12:57:21 -0500 Received: by mail-wr1-x42d.google.com with SMTP id u6so7849583wrt.0 for ; Thu, 13 Feb 2020 09:57: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=wpXd5QxscHZ5Ze+pVlbaJlNdMe0Q3RlgSzZJLeNwcSk=; b=UirwSC0WPnPtZx8dyMewg+fuLEeN+VYHty+qCll09IjdIfyajD7PMeU1cJRH77Lu+h UchqNPNSDpKlaYqzlTt/gQwtrO11jv5SQW6/irbQpeaIhD3uEhXIMl4/Wp41zt8TiRt/ fhKcLPLu7unjaYUWm5g8/AByhV6CALsNBGzkhVc/SeIDYYc2UDUVRF4XMhMZV9NKMgrr HB1ocjka/MNnMy2eYI23wYgOqe7SDZydT1tu43J1mLEqYlR5fjGjDSEaRENeCafxYiF3 1whPVv/izr0zoTE7KsN2MCSJJ0Ma4CfjcU2dhJxINJfjgAC0iOSxZ6s7EZlJ2oH4cpmV An5w== 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=wpXd5QxscHZ5Ze+pVlbaJlNdMe0Q3RlgSzZJLeNwcSk=; b=ACe/qlWSFAbWxzlDYlDw107rnVHl5ADLxJxclXVeaj5V9ete89A1K+brj1VC+qSDqF tVIzgFdvp7pq4/vSBMypHsj8PiO3nXV+JbvUbGPRkVCRwaEh/w2f1RrZKQ0HM/D6/nGn O7Ep+MBvOgVGXx5Re6GW7Vl9KswjwFNgorv4k+cSiMAOrBd8uyGOXGoC9wpsvZhF7VkH 63lGDvgVmB3qq5cB9wVZb5LLcfHuVHB1lh44LrVdRWU/Ip1bdNVbZW9tiFRn7UjJSMIp eBeirOPuGhbH/4QhhjXW+mAo9fwzpvWoGveP7TGec9V7BXB8v/phmdZN3Lg+NgsHWeJe fzhg== X-Gm-Message-State: APjAAAUfdaGCjAa2+PCKEFmHCjXtN6LuKcWbvbXpe9tGxgAxCzAd2BCE DolXdXvtdZus/+YcfbOuFVR1QNuHCu4= X-Received: by 2002:adf:ffc5:: with SMTP id x5mr23553063wrs.92.1581616640457; Thu, 13 Feb 2020 09:57:20 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id p26sm3692913wmc.24.2020.02.13.09.57.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 13 Feb 2020 09:57:19 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v2 22/30] scripts/qapi: Move doc-comment whitespace stripping to doc.py Date: Thu, 13 Feb 2020 17:56:39 +0000 Message-Id: <20200213175647.17628-23-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200213175647.17628-1-peter.maydell@linaro.org> References: <20200213175647.17628-1-peter.maydell@linaro.org> MIME-Version: 1.0 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" 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. Signed-off-by: Peter Maydell --- New in v2: update doc-good.out as noted in final para of commit msg --- scripts/qapi/doc.py | 1 + scripts/qapi/parser.py | 12 ++++-------- tests/qapi-schema/doc-good.out | 12 ++++++------ 3 files changed, 11 insertions(+), 14 deletions(-) -- 2.20.1 diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py index 1787a53d91a..26cd1a1751e 100644 --- a/scripts/qapi/doc.py +++ b/scripts/qapi/doc.py @@ -79,6 +79,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): diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 9503a3a3178..a65bce639ff 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -71,20 +71,20 @@ doc freeform * List item one * Two, multiple -lines + lines * Three -Still in list + Still in list Not in list - Second list -Note: still in list + Note: still in list Note: not in list 1. Third list -is numbered + is numbered 2. another item @@ -144,7 +144,7 @@ doc symbol=Alternate arg=i an integer -@b is undocumented + @b is undocumented arg=b doc freeform @@ -157,7 +157,7 @@ doc symbol=cmd the first argument arg=arg2 the second -argument + argument arg=arg3 feature=cmd-feat1