[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v2 14/16] docs/devel/qapi-code-gen: Rewrite intr
From: |
Markus Armbruster |
Subject: |
Re: [Qemu-devel] [PATCH v2 14/16] docs/devel/qapi-code-gen: Rewrite introduction to schema |
Date: |
Fri, 13 Sep 2019 17:16:50 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.2 (gnu/linux) |
Eric Blake <address@hidden> writes:
> On 9/10/19 1:37 AM, Markus Armbruster wrote:
>> The introduction to the QAPI schema is somewhat rambling. Rewrite for
>> clarity.
>
> The curse of additions over time. Thanks for tackling this.
>
>>
>> Signed-off-by: Markus Armbruster <address@hidden>
>> ---
>> docs/devel/qapi-code-gen.txt | 106 ++++++++++++++++-------------------
>> 1 file changed, 47 insertions(+), 59 deletions(-)
>>
>
>> +=== Schema syntax ===
>> +
>> +Syntax is loosely based on JSON (http://www.ietf.org/rfc/rfc8259.txt).
>> +Differences:
>> +
>> +* Comments: start with a hash character (#) that is not part of a
>> + string, and extend to the end of the line.
>> +
>> +* Strings are enclosed in 'single quotes', not "double quotes".
>> +
>> +* Strings are restricted to ASCII. All control characters must be
>> + escaped, even DEL.
>
> Or rather, control characters are not permitted. (May affect the
> earlier 7/16...)
I neglected to update this for v2. Will change to "Strings are
restricted to printable ASCII, and escape sequences to just '\\'.
>> +
>> +* Numbers are not supported.
>
> Yet. But if we allow default values, it won't be much longer before we
> get there. (Doesn't affect this patch)
>
>> +
>> +A QAPI schema consists of a series of top-level expressions (JSON
>> +objects). Their order does not matter.
>
> Does the order of 'include' and/or 'pragma' matter?
Pragma no, because their scope is the complete schema.
Include no, as long as order doesn't matter for anything else.
Hmm, there's one thing that cares for order: generated documentation is
in source order.
Hmm^2, subsection "Documentation comments" doesn't mention doc
generation at all, and we also lack a dsubsection on it under section
"Code generation".
I'll see what I can do for v3.
> Touchups seem minor enough that I trust you, so you can add:
> Reviewed-by: Eric Blake <address@hidden>
Thanks!
- [Qemu-devel] [PATCH v2 07/16] qapi: Drop support for escape sequences other than \\, (continued)
[Qemu-devel] [PATCH v2 14/16] docs/devel/qapi-code-gen: Rewrite introduction to schema, Markus Armbruster, 2019/09/10
[Qemu-devel] [PATCH v2 08/16] qapi: Permit 'boxed' with empty type, Markus Armbruster, 2019/09/10
[Qemu-devel] [PATCH v2 15/16] docs/devel/qapi-code-gen: Improve QAPI schema language doc, Markus Armbruster, 2019/09/10
Re: [Qemu-devel] [PATCH v2 00/16] qapi: Schema language cleanups & doc improvements, no-reply, 2019/09/10
Re: [Qemu-devel] [PATCH v2 00/16] qapi: Schema language cleanups & doc improvements, no-reply, 2019/09/10