Peter Maydell <peter.mayd...@linaro.org> writes: > On Fri, 24 Mar 2023 at 12:05, Markus Armbruster <arm...@redhat.com> wrote: >> >> Peter Maydell <peter.mayd...@linaro.org> writes: >> >> > On Thu, 23 Mar 2023 at 14:48, Markus Armbruster <arm...@redhat.com> wrote: >> >> >> >> The QAPI schema doc comment language provides special syntax for command >> >> and event arguments, struct and union members, alternate branches, >> >> enumeration values, and features: "sections" starting with @arg:. >> >> >> >> By convention, we format them like this: >> >> >> >> # @arg: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed >> >> # do eiusmod tempor incididunt ut labore et dolore magna >> >> # aliqua. >> >> >> >> Okay for names as short as "name", but we have much longer ones. Their >> >> description gets squeezed against the right margin, like this: >> >> >> >> # @dirty-sync-missed-zero-copy: Number of times dirty RAM >> >> synchronization could >> >> # not avoid copying dirty pages. This >> >> is between >> >> # 0 and @dirty-sync-count * >> >> @multifd-channels. >> >> # (since 7.1) >> >> >> >> The description is effectively 50 characters wide. Easy enough to read, >> >> but awkward to write. >> > >> > The documentation also permits a second form: >> > >> > # @argone: >> > # This is a two line description >> > # in the first style. >> >> Yes. We use this in exactly one place: the guest agent's GuestOSInfo. >> >> > We tend to use that for type names, not field names, but IIRC >> > it's the same handling for both. >> >> Kind of. >> >> Definition documentation consist of "sections". >> >> The first section (called "body" in the code) starts with a line of the >> from >> >> # @NAME: >> >> Nothing may follow the colon. >> >> Ordinary text may follow. Indentation is not stripped. > > I guess this has changed since I added the rst stuff. Back > at the time (assuming my email comments at that time are > correct) this was all basically in the same code path, so > the "allow field descriptions that start on the following line" > falls out of having to handle "allow section definitions with > text that starts on the following line".
Could be the same path in qapidoc.py, but has always been separate in parser.py, as far as I remember. >> Our current doc comment syntax has two layers: >> >> 1. The upper layer uses home-grown markup (= heading, @def: for special >> definition lists, @ref to reference QAPI names, tag: special >> sections). >> >> 2. The lower layer is reStructuredText. >> >> Parsing mirrors this: >> >> 1. parser.py parses the upper layer into an internal representation. >> >> 2. Sphinx extension qapidoc.py maps this internal representation to >> Sphinx's. It feeds its text parts to the rST parser, and splices its >> output into the Sphinx IR. >> >> I'm wary of blurring the boundary between the two. If we use rST syntax >> for argument sections, parser.py effectively parses a limited subset of >> rST. Second-guessing the real rST parser doesn't feel wise to me. > > I didn't mean to say "use rst syntax entirely throughout" > so much as "use the same rules for multi-line syntax that rst does, > not a subtly different set of rules". We could keep our @markup stuff. Fair point.