Re: [Qemu-devel] [PATCH v2 14/16] docs/devel/qapi-code-gen: Rewrite introduction to schema

[Markus Armbruster <armbru@redhat.com>]

Eric Blake <eblake@redhat.com> 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 <armbru@redhat.com>
>> ---
>>  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 <eblake@redhat.com>

Thanks!