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

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.

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.

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

[...]