On Wed, Mar 4, 2026, 5:46 AM Markus Armbruster <[email protected]> wrote:
> John Snow <[email protected]> writes: > > > Hi, let's recap... > > > > In general, it would be nice to have a strict inter-section ordering > > for a few reasons: > > > > (1) It makes it easier to add generated sections such as return > > values, undocumented members, or undocumented features/flags (such as > > Out-of-band execution), because there is a clear and obvious place > > where we should insert the generated doc. We have a few spots in the > > code now where we have a bespoke algorithm to find the correct > > insertion point, and it would be nice to consolidate this logic. > > > > (2) It makes the inliner easier, because merging two doc sections is > > more obvious when there is a normal order that must be adhered to; > > fields that are absent in one or the other docs list do not cause > > problems or complex edge cases. > > > > (3) It allows us to design around a unified look and layout in the > > HTML generator, which increases visual cohesion and yadda yadda yadda. > > In particular, each "group" of doc types is laid out in a block where > > having multiple fields of the same type be non-contiguous greatly > > increases visual clutter. i.e. all arguments should be contiguous, all > > features should be contiguous, etc. I have in the past referred to > > these groupings of doc section types as "doc regions". > > > > For these reasons, I'd like to nail down the order once and for all, > > and clarify a few things. > > > > The order I think you prefer is something like this: > > > > (1) Introduction ("Plain text", currently) - Always the first section, > > always precisely one section. (But may be multiple paragraphs housed > > within that single section.) > > (2) Arguments/members/values/alternatives > > (3) Return(s) > > (4) Error(s) > > (5) Feature(s) > > (6) Details ("Plain text", currently - generally used for clarifying > > detail, examples, and other information.) > > (7) Since > Ah, right. Because I remove "since" from the flow of the document, I wind up caring about it less, but yes. It can be last in the source. > > Before I go any further, is this order "roughly correct" to you? > > Yes! > > > ... > > > > We previously discussed prohibiting "plain text" from appearing > > anywhere except in (1) or (6). From memory, the summary of that > > discussion is: > > > > Me: Prohibiting plaintext from appearing between 2-5 makes inlining > > easier, and improves HTML output by preventing plaintext paragraphs > > from interrupting the "tabular" output used to render metadata fields. > > > > You: Although it is not often utilized, we may want the freedom/power > > to use plaintext paragraphs to add addendums/notes attached to > > specific sections, i.e. adding a "Note:" to the tail of the arguments > > section specifically. > > > > I recall we debated this particular restriction quite a few times and > > at length; does this summary sound roughly accurate as far as you > > remember? > > It does. > > What breaks right now if you prohibit untagged sections between (2) to > (5)? > Not much. I think we have an interloping plaintext section maybe once or twice in the docs currently. In my previous patches, I just removed those sections but there was some concern about the ability to annotate e.g. arguments sections with a note. I haven't actually worked on this feature, but I suggested once we could add an "addendum" or "section-note" tag to include these. I don't currently have a strong sense of how hard that would or wouldn't be. >
