[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v4 06/18] scripts/qapi/parser.py: improve doc comment indent
From: |
Richard Henderson |
Subject: |
Re: [PATCH v4 06/18] scripts/qapi/parser.py: improve doc comment indent handling |
Date: |
Tue, 10 Mar 2020 23:08:33 -0700 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1 |
On 3/9/20 8:43 AM, Peter Maydell wrote:
> 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.
>
> The exception is that we always retain indentation as-is for Examples
> sections, because these are literal text.
>
> 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.
>
> Signed-off-by: Peter Maydell <address@hidden>
> ---
> v1->v2: Update doc-good.out as per final para.
> ---
> scripts/qapi/parser.py | 81 +++++++++++++++++++++++++++-------
> tests/qapi-schema/doc-good.out | 4 +-
> 2 files changed, 67 insertions(+), 18 deletions(-)
Reviewed-by: Richard Henderson <address@hidden>
r~
- Re: [PATCH v4 02/18] qapi/qapi-schema.json: Put headers in their own doc-comment blocks, (continued)
- [PATCH v4 03/18] qapi/machine.json: Escape a literal '*' in doc comment, Peter Maydell, 2020/03/09
- [PATCH v4 05/18] scripts/qapi: Move doc-comment whitespace stripping to doc.py, Peter Maydell, 2020/03/09
- [PATCH v4 04/18] tests/qapi/doc-good.json: Clean up markup, Peter Maydell, 2020/03/09
- [PATCH v4 01/18] qapi/migration.json: Fix indentation, Peter Maydell, 2020/03/09
- [PATCH v4 06/18] scripts/qapi/parser.py: improve doc comment indent handling, Peter Maydell, 2020/03/09
- Re: [PATCH v4 06/18] scripts/qapi/parser.py: improve doc comment indent handling,
Richard Henderson <=
- [PATCH v4 07/18] docs/sphinx: Add new qapi-doc Sphinx extension, Peter Maydell, 2020/03/09
- [PATCH v4 08/18] docs/interop: Convert qemu-ga-ref to rST, Peter Maydell, 2020/03/09
- [PATCH v4 10/18] qapi: Use rST markup for literal blocks, Peter Maydell, 2020/03/09
- [PATCH v4 09/18] docs/interop: Convert qemu-qmp-ref to rST, Peter Maydell, 2020/03/09
- [PATCH v4 13/18] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions, Peter Maydell, 2020/03/09
- [PATCH v4 12/18] scripts/qapi: Remove texinfo generation support, Peter Maydell, 2020/03/09