diff options
| author | Peter Maydell <peter.maydell@linaro.org> | 2020-01-31 15:36:08 +0000 |
|---|---|---|
| committer | Peter Maydell <peter.maydell@linaro.org> | 2020-09-22 16:39:46 +0100 |
| commit | 33cbee76b5798f470358270bcd612c01488fb9ff (patch) | |
| tree | 1953ca9c35d17d85149cefc278955e3612cb523a /tests/qapi-schema | |
| parent | b155f42035f4187e7c3e7a753d790ae1bb9864f2 (diff) | |
scripts/qapi/parser.py: improve doc comment indent handling
Make the handling of indentation in doc comments more sophisticated,
so that when we see a section like:
Notes: some text
some more text
indented line 3
we save it for the doc-comment processing code as:
some text
some more text
indented line 3
and when we see a section with the heading on its own line:
Notes:
some text
some more text
indented text
we also accept that and save it in the same form.
If we detect that the comment document text is not indented as much
as we expect it to be, we throw a parse error. (We don't complain
about over-indented sections, because for rST this can be legitimate
markup.)
The golden reference for the doc comment text is updated to remove
the two 'wrong' indents; these now form a test case that we correctly
stripped leading whitespace from an indented multi-line argument
definition.
We update the documentation in docs/devel/qapi-code-gen.txt to
describe the new indentation rules.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
v5->v6:
* various fixes to issues noted by Markus
* we no longer special-case "Example" indentation
* added a test case for the de-indent error
* put the relevant part of the docs update into this patch
(in the optimistic hope that if the series up to this point
is OK then we could commit the first half and thus avoid
further breaches of the new indent rules being committed)
Diffstat (limited to 'tests/qapi-schema')
| -rw-r--r-- | tests/qapi-schema/doc-bad-indent.err | 1 | ||||
| -rw-r--r-- | tests/qapi-schema/doc-bad-indent.json | 8 | ||||
| -rw-r--r-- | tests/qapi-schema/doc-bad-indent.out | 0 | ||||
| -rw-r--r-- | tests/qapi-schema/doc-good.out | 4 | ||||
| -rw-r--r-- | tests/qapi-schema/meson.build | 1 |
5 files changed, 12 insertions, 2 deletions
diff --git a/tests/qapi-schema/doc-bad-indent.err b/tests/qapi-schema/doc-bad-indent.err new file mode 100644 index 0000000000..67844539bd --- /dev/null +++ b/tests/qapi-schema/doc-bad-indent.err @@ -0,0 +1 @@ +doc-bad-indent.json:6:1: unexpected de-indent (expected at least 4 spaces) diff --git a/tests/qapi-schema/doc-bad-indent.json b/tests/qapi-schema/doc-bad-indent.json new file mode 100644 index 0000000000..edde8f21dc --- /dev/null +++ b/tests/qapi-schema/doc-bad-indent.json @@ -0,0 +1,8 @@ +# Multiline doc comments should have consistent indentation + +## +# @foo: +# @a: line one +# line two is wrongly indented +## +{ 'command': 'foo', 'data': { 'a': 'int' } } diff --git a/tests/qapi-schema/doc-bad-indent.out b/tests/qapi-schema/doc-bad-indent.out new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/tests/qapi-schema/doc-bad-indent.out diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 9993ffcd89..b7e3f4313d 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -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 diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index f1449298b0..83a0a68389 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -53,6 +53,7 @@ schemas = [ 'doc-bad-enum-member.json', 'doc-bad-event-arg.json', 'doc-bad-feature.json', + 'doc-bad-indent.json', 'doc-bad-section.json', 'doc-bad-symbol.json', 'doc-bad-union-member.json', |