[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v2 05/30] qga/qapi-schema.json: Fix indent level on doc comme
From: |
Markus Armbruster |
Subject: |
Re: [PATCH v2 05/30] qga/qapi-schema.json: Fix indent level on doc comments |
Date: |
Fri, 14 Feb 2020 13:36:43 +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
Let's spell Texinfo with a capital T.
> levels, but we would like to add a rST backend, and rST does care
> about indentation.
Nitpick: an rST *backend* should not care about the doc generator's
*input* format. We actually intend to change the input format into a
domain-specific dialect of rST, as you state in your cover letter: "This
series switches all our QAPI doc comments over from texinfo format to
rST."
Perhaps:
The current doc generation doesn't care much about indentation levels,
but we would like to switch to an rST format, 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.
>
> 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>
R-by stands even without the commit message improvement I suggested.
- Re: [PATCH v2 01/30] configure: Allow user to specify sphinx-build binary, (continued)
[PATCH v2 02/30] configure: Check that sphinx-build is using Python 3, Peter Maydell, 2020/02/13
[PATCH v2 03/30] Makefile: Fix typo in dependency list for interop manpages, Peter Maydell, 2020/02/13
[PATCH v2 04/30] qga/qapi-schema.json: Fix missing '-' in GuestDiskBusType doc comment, Peter Maydell, 2020/02/13
[PATCH v2 07/30] qapi/block-core.json: Use literal block for ascii art, Peter Maydell, 2020/02/13
[PATCH v2 05/30] qga/qapi-schema.json: Fix indent level on doc comments, Peter Maydell, 2020/02/13
- Re: [PATCH v2 05/30] qga/qapi-schema.json: Fix indent level on doc comments,
Markus Armbruster <=
[PATCH v2 10/30] qapi: Remove hardcoded tabs, Peter Maydell, 2020/02/13
[PATCH v2 06/30] qga/qapi-schema.json: minor format fixups for rST, Peter Maydell, 2020/02/13
[PATCH v2 08/30] qapi: Use ':' after @argument in doc comments, Peter Maydell, 2020/02/13
[PATCH v2 11/30] qapi/ui.json: Put input-send-event body text in the right place, Peter Maydell, 2020/02/13