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

John Snow <[email protected]> writes:

> On Fri, Jul 24, 2026 at 4:04 AM Markus Armbruster <[email protected]> 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.

Right, I forgot about this.  There goes my review shortcut...

> (*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.
>>
>> [...]
>>