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

[Peter Maydell]

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".

> 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.

thanks
-- PMM