Re: [PATCH v2 00/44] qapi: convert trivial intro sections

On Fri, Jul 24, 2026 at 4:04=E2=80=AFAM Markus Armbruster <[email protected]=
m> wrote:
>
> Markus Armbruster <[email protected]> writes:
>
> [...]
>
> > Converting single first paragraps is mechanical.  For it to be correct,
> > this single paragraph must actually be the overview, and not some other
> > crap.  I expect it to be almost always overview.  Not sure how to best
> > look for the exceptions.
>
> The separation truly matters only when the inliner inlines the doc
> comment.  It potentially matters when it would inline it if the type was
> used differently.

It also (potentially) matters for auto-generated docs, such as
undocumented members, return types, features*, errors*. The break
point is where these fields get inserted.

(*Not currently performed. Not asserting that it will be performed, or
that it is necessarily valuable to do so. Just fleshing out the
category.)

>
> If I remember correctly, the inliner inlines doc of struct / union base
> type, union branch type, command / event argument type.
>
> Argument can only be struct or union.  Base and branch can only be
> struct.
>
> We talked about maybe inlining return types some day.  This would be
> struct, union, or array of struct or union.
>
> So, for anything other than struct and union, the inliner doesn't get
> involved, and separating the overview cleanly is just a matter of
> writing style.  I'm not sure we care.  Even if we elect to care,
> cleaning it up is hardly this series' business.  In short, your
> mechanical conversion of single first paragraphs to overview syntax
> should be fine even where a paragraph's contents isn't clearly overview.

Except in cases where stub positioning matters, see also the former
"TODO:" syntax used to delineate intro/details.

>
> Structs and unions, however, could use an eye-over.
>
> [...]
>