Eric Blake <ebl...@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 <arm...@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 <ebl...@redhat.com> Thanks!