[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v2 09/30] qapi: Fix indent level on doc comments in json file
From: |
Markus Armbruster |
Subject: |
Re: [PATCH v2 09/30] qapi: Fix indent level on doc comments in json files |
Date: |
Fri, 14 Feb 2020 14:45:04 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) |
Peter Maydell <address@hidden> writes:
> The texinfo doc generation doesn't care much about indentation
> levels, but we would like to add a rST backend, and rST does care
> about indentation.
>
> Make the doc comments more strongly consistent about indentation
> for multiline constructs like:
>
> @arg: description line 1
> description line 2
>
> Returns: line one
> line 2
>
> so that there is always exactly one space after the colon, and
> subsequent lines align with the first.
>
> This commit is a purely whitespace change, and it does not alter the
> generated .texi files (because the texi generation code strips away
> all the extra whitespace). This does mean that we end up with some
> over-length lines.
Overlong lines need to be corrected. Not necessarily in this patch.
> Note that when the documentation for an argument fits on a single
> line like this:
>
> @arg: one line only
>
> then stray extra spaces after the ':' don't affect the rST output, so
> I have not attempted to methodically fix them, though the preference
> is a single space here too.
>
> Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Markus Armbruster <address@hidden>
- [PATCH v2 17/30] qapi/migration.json: Replace _this_ with *this*, (continued)
- [PATCH v2 17/30] qapi/migration.json: Replace _this_ with *this*, Peter Maydell, 2020/02/13
- [PATCH v2 22/30] scripts/qapi: Move doc-comment whitespace stripping to doc.py, Peter Maydell, 2020/02/13
- [PATCH v2 20/30] qapi/machine.json: Escape a literal '*' in doc comment, Peter Maydell, 2020/02/13
- [PATCH v2 21/30] tests/qapi/doc-good.json: Clean up markup, Peter Maydell, 2020/02/13
- [PATCH v2 28/30] qga/qapi-schema.json: Add some headings, Peter Maydell, 2020/02/13
- [PATCH v2 25/30] docs/interop: Convert qemu-ga-ref to rST, Peter Maydell, 2020/02/13
- [PATCH v2 09/30] qapi: Fix indent level on doc comments in json files, Peter Maydell, 2020/02/13
- Re: [PATCH v2 09/30] qapi: Fix indent level on doc comments in json files,
Markus Armbruster <=
- [PATCH v2 24/30] docs/sphinx: Add new qapi-doc Sphinx extension, Peter Maydell, 2020/02/13
- [PATCH v2 27/30] qapi: Use rST markup for literal blocks, Peter Maydell, 2020/02/13
- [PATCH v2 23/30] scripts/qapi/parser.py: improve doc comment indent handling, Peter Maydell, 2020/02/13
- [PATCH v2 26/30] docs/interop: Convert qemu-qmp-ref to rST, Peter Maydell, 2020/02/13
- [PATCH v2 30/30] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions, Peter Maydell, 2020/02/13
- [PATCH v2 29/30] scripts/qapi: Remove texinfo generation support, Peter Maydell, 2020/02/13
- Re: [PATCH v2 00/30] Convert QAPI doc comments to generate rST instead of texinfo, no-reply, 2020/02/13