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