[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 12/29] scripts/qapi: Move doc-comment whitespace stripping to doc.
From: |
Markus Armbruster |
Subject: |
[PULL 12/29] scripts/qapi: Move doc-comment whitespace stripping to doc.py |
Date: |
Tue, 29 Sep 2020 22:19:09 +0200 |
From: Peter Maydell <peter.maydell@linaro.org>
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 <richard.henderson@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-5-peter.maydell@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
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 92f584edcf..7764de1e4b 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 165925ca72..04bf10db37 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -427,10 +427,10 @@ class QAPIDoc:
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):
"""
@@ -463,7 +463,7 @@ class QAPIDoc:
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]
@@ -482,7 +482,7 @@ class QAPIDoc:
self._append_various_line(line)
return
- self._append_freeform(line.strip())
+ self._append_freeform(line)
def _append_various_line(self, line):
"""
@@ -505,10 +505,6 @@ class QAPIDoc:
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 acb00ade17..9993ffcd89 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -78,20 +78,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
@@ -159,7 +159,7 @@ doc symbol=Alternate
arg=i
an integer
-@b is undocumented
+ @b is undocumented
arg=b
feature=alt-feat
@@ -174,7 +174,7 @@ doc symbol=cmd
the first argument
arg=arg2
the second
-argument
+ argument
arg=arg3
feature=cmd-feat1
--
2.26.2
- [PULL 16/29] docs/interop: Convert qemu-ga-ref to rST, (continued)
- [PULL 16/29] docs/interop: Convert qemu-ga-ref to rST, Markus Armbruster, 2020/09/29
- [PULL 26/29] scripts/texi2pod: Delete unused script, Markus Armbruster, 2020/09/29
- [PULL 28/29] configure: Drop texinfo requirement, Markus Armbruster, 2020/09/29
- [PULL 23/29] tests/qapi-schema: Add test of the rST QAPI doc-comment output, Markus Armbruster, 2020/09/29
- [PULL 17/29] docs/interop: Convert qemu-qmp-ref to rST, Markus Armbruster, 2020/09/29
- [PULL 24/29] scripts/qapi: Remove texinfo generation support, Markus Armbruster, 2020/09/29
- [PULL 18/29] qapi: Use rST markup for literal blocks, Markus Armbruster, 2020/09/29
- [PULL 13/29] scripts/qapi/parser.py: improve doc comment indent handling, Markus Armbruster, 2020/09/29
- [PULL 15/29] docs/sphinx: Add new qapi-doc Sphinx extension, Markus Armbruster, 2020/09/29
- [PULL 22/29] meson.build: Make manuals depend on source to Sphinx extensions, Markus Armbruster, 2020/09/29
- [PULL 12/29] scripts/qapi: Move doc-comment whitespace stripping to doc.py,
Markus Armbruster <=
- [PULL 02/29] qapi: Correct balloon documentation, Markus Armbruster, 2020/09/29
- [PULL 14/29] qapi/machine.json: Escape a literal '*' in doc comment, Markus Armbruster, 2020/09/29
- [PULL 05/29] qapi: Restrict query-uuid command to machine code, Markus Armbruster, 2020/09/29
- [PULL 25/29] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions, Markus Armbruster, 2020/09/29
- Re: [PULL 00/29] QAPI patches patches for 2020-09-29, Peter Maydell, 2020/09/30