Re: qapi: [RFC] Doc comment convention for @arg: sections

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Fri, 24 Mar 2023 at 12:05, Markus Armbruster <armbru@redhat.com> wrote:
>>
>> Peter Maydell <peter.maydell@linaro.org> writes:
>>
>> > On Thu, 23 Mar 2023 at 14:48, Markus Armbruster <armbru@redhat.com> wrote:
>> >>
>> >> The QAPI schema doc comment language provides special syntax for command
>> >> and event arguments, struct and union members, alternate branches,
>> >> enumeration values, and features: "sections" starting with @arg:.
>> >>
>> >> By convention, we format them like this:
>> >>
>> >>     # @arg: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
>> >>     #       do eiusmod tempor incididunt ut labore et dolore magna
>> >>     #       aliqua.
>> >>
>> >> Okay for names as short as "name", but we have much longer ones.  Their
>> >> description gets squeezed against the right margin, like this:
>> >>
>> >>     # @dirty-sync-missed-zero-copy: Number of times dirty RAM 
>> >> synchronization could
>> >>     #                               not avoid copying dirty pages. This 
>> >> is between
>> >>     #                               0 and @dirty-sync-count * 
>> >> @multifd-channels.
>> >>     #                               (since 7.1)
>> >>
>> >> The description is effectively 50 characters wide.  Easy enough to read,
>> >> but awkward to write.
>> >
>> > The documentation also permits a second form:
>> >
>> >  # @argone:
>> >  # This is a two line description
>> >  # in the first style.
>>
>> Yes.  We use this in exactly one place: the guest agent's GuestOSInfo.
>>
>> > We tend to use that for type names, not field names, but IIRC
>> > it's the same handling for both.
>>
>> Kind of.
>>
>> Definition documentation consist of "sections".
>>
>> The first section (called "body" in the code) starts with a line of the
>> from
>>
>>     # @NAME:
>>
>> Nothing may follow the colon.
>>
>> Ordinary text may follow.  Indentation is not stripped.
>
> I guess this has changed since I added the rst stuff. Back
> at the time (assuming my email comments at that time are
> correct) this was all basically in the same code path, so
> the "allow field descriptions that start on the following line"
> falls out of having to handle "allow section definitions with
> text that starts on the following line".

Could be the same path in qapidoc.py, but has always been separate in
parser.py, as far as I remember.

>> Our current doc comment syntax has two layers:
>>
>> 1. The upper layer uses home-grown markup (= heading, @def: for special
>>    definition lists, @ref to reference QAPI names, tag: special
>>    sections).
>>
>> 2. The lower layer is reStructuredText.
>>
>> Parsing mirrors this:
>>
>> 1. parser.py parses the upper layer into an internal representation.
>>
>> 2. Sphinx extension qapidoc.py maps this internal representation to
>>    Sphinx's.  It feeds its text parts to the rST parser, and splices its
>>    output into the Sphinx IR.
>>
>> I'm wary of blurring the boundary between the two.  If we use rST syntax
>> for argument sections, parser.py effectively parses a limited subset of
>> rST.  Second-guessing the real rST parser doesn't feel wise to me.
>
> I didn't mean to say "use rst syntax entirely throughout"
> so much as "use the same rules for multi-line syntax that rst does,
> not a subtly different set of rules". We could keep our @markup stuff.

Fair point.