scripts/qapi: Move doc-comment whitespace stripping to doc.py

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>
This commit is contained in:
Peter Maydell 2020-09-25 17:22:59 +01:00 committed by Markus Armbruster
parent 63a97cf5a0
commit 99dff36d3a
3 changed files with 11 additions and 14 deletions

View File

@ -79,6 +79,7 @@ def texi_format(doc):
inlist = '' inlist = ''
lastempty = False lastempty = False
for line in doc.split('\n'): for line in doc.split('\n'):
line = line.strip()
empty = line == '' empty = line == ''
# FIXME: Doing this in a single if / elif chain is # FIXME: Doing this in a single if / elif chain is

View File

@ -427,10 +427,10 @@ class QAPIDoc:
self._append_line = self._append_various_line self._append_line = self._append_various_line
self._append_various_line(line) self._append_various_line(line)
else: else:
self._append_freeform(line.strip()) self._append_freeform(line)
else: else:
# This is a free-form documentation block # This is a free-form documentation block
self._append_freeform(line.strip()) self._append_freeform(line)
def _append_args_line(self, line): def _append_args_line(self, line):
""" """
@ -463,7 +463,7 @@ class QAPIDoc:
self._append_various_line(line) self._append_various_line(line)
return return
self._append_freeform(line.strip()) self._append_freeform(line)
def _append_features_line(self, line): def _append_features_line(self, line):
name = line.split(' ', 1)[0] name = line.split(' ', 1)[0]
@ -482,7 +482,7 @@ class QAPIDoc:
self._append_various_line(line) self._append_various_line(line)
return return
self._append_freeform(line.strip()) self._append_freeform(line)
def _append_various_line(self, line): def _append_various_line(self, line):
""" """
@ -505,10 +505,6 @@ class QAPIDoc:
line = line[len(name)+1:] line = line[len(name)+1:]
self._start_section(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) self._append_freeform(line)
def _start_symbol_section(self, symbols_dict, name): def _start_symbol_section(self, symbols_dict, name):

View File

@ -78,20 +78,20 @@ doc freeform
* List item one * List item one
* Two, multiple * Two, multiple
lines lines
* Three * Three
Still in list Still in list
Not in list Not in list
- Second list - Second list
Note: still in list Note: still in list
Note: not in list Note: not in list
1. Third list 1. Third list
is numbered is numbered
2. another item 2. another item
@ -159,7 +159,7 @@ doc symbol=Alternate
arg=i arg=i
an integer an integer
@b is undocumented @b is undocumented
arg=b arg=b
feature=alt-feat feature=alt-feat
@ -174,7 +174,7 @@ doc symbol=cmd
the first argument the first argument
arg=arg2 arg=arg2
the second the second
argument argument
arg=arg3 arg=arg3
feature=cmd-feat1 feature=cmd-feat1