From 99dff36d3a5fb38bd3d079cd16b811bbfcb3ad07 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Fri, 25 Sep 2020 17:22:59 +0100 Subject: [PATCH] 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 Reviewed-by: Markus Armbruster Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-5-peter.maydell@linaro.org> Signed-off-by: Markus Armbruster --- 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