On Thu, Jan 9, 2025, 6:48 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes: > > > On Thu, Dec 19, 2024 at 7:31 AM Markus Armbruster <arm...@redhat.com> > wrote: > > > >> John Snow <js...@redhat.com> writes: > >> > >> > based-on: > >> https://patchew.org/QEMU/20241213011307.2942030-1-js...@redhat.com/ > >> > > >> > Hi! > >> > > >> > This series is a very, very barebones implementation for the new QAPI > >> > doc generator. It does not have many features that I presented on at > KVM > >> > Forum; the point of this patch set is instead to present a stripped > down > >> > basis for ongoing work so we can discuss on-list with full context of > >> > the code available to do so. > >> > > >> > The documentation this series generates is *not suitable* for > replacing > >> > the current document generator, it has a few glaring omissions - on > >> > purpose - those features have been factored out intentionally so they > >> > can be reviewed with fuller context and more careful review. > >> > > >> > What this series does: > >> > > >> > - Adds the new "Transmogrifier" rST generator to qapidoc.py, which > >> > generates an in-memory rST document using qapi-domain directives. > >> > - Adds a test document that showcases this new transmogrifier. > >> > >> Note to other reviewers: transmogrifier output is > >> docs/manual/qapi/index.html. > >> > >> > What this series very notably does not do (yet): > >> > > >> > - "ifcond" data for anything other than top-level entities is not > >> > considered or rendered. This means "if" statements for features and > >> > members are entirely absent. > >> > > >> > - The inliner is not present at all. This series renders only > >> > documentation exactly as it is exists in the source files. > >> > >> This item is not even a regression. > >> > > > > No; but the version of this series as sent also does not add "The members > > of ..." stubs, which would be a regression. > > Right. > > > I didn't necessarily intend > for > > this to be merged as-is; more of a "part one, with additional tricky > > elements that require more careful thought isolated into separate patches > > for later". > > > > where "later" means "in v2" or "as a follow-up series as we stage things > in > > a development branch before final submission for inclusion to > > origin/master" or whatever the actual mechanism is. I don't have a strong > > vision there, really; I just wanted to nail down the basics out in the > open > > even if that was just between you (Markus) and I and we have a > gentleman's > > agreement that it looks tentatively OK. > > Got it. > > >> > - *branches* are themselves not considered at all; they're skipped > >> > entirely for now. They will be included alongside the inliner in > >> > either a subsequent series or a followup to this series. > >> > > >> > - Undocumented members and return statements are not autogenerated. > >> > >> The current doc generator auto-generates missing member documentation > >> ("Not documented"). It doesn't auto-generate missing returns > >> documentation. I explored auto-generating them, but shelved my work to > >> not interfere with yours. > >> > >> > - Pseudofeatures (Things like allow-oob) are not generated as > documented > >> > features. > >> > >> What exactly are "pseudofeatures"? > >> > > > > What I've named things like allow-oob that aren't features, but ought to > be > > documented. We may well decide to promote them to real-deal special > > features, or maybe not. My work-in-progress branch currently just adds > > "dummy" features to document them. We can discuss this later alongside > the > > patch that implements this. > > I agree this is a digression, so feel free to ignore the remainder of my > reply for now. > > We have two kinds of flags in the QAPI schema language: features and ad > hoc flags. The ad hoc flags are 'boxed' (commands and events), 'gen', > 'success-response', 'allow-oob', 'allow-preconfig', 'coroutine' > (commands only). > > The flags sort into three buckets: > > 1. Code generation directives that do not affect the external interface, > and thus should not be visible in introspection: 'boxed', 'gen', > 'coroutine'. > > 2. Flags that are visible at the external interface, but don't affect > code generation beyond making them visible in introspection: the > non-special features. > > 3. Code generation directives that affect the external interface, and > thus are (or should be) visible in introspection. > > 3a. The special features: are visible. > > 3b. 'allow-oob': is visible, but differently, because it predates > special features. > > 3c. 'allow-preconfig': not visible. > > 3d. 'success-response': not visible, because we use it for QGA only, > which doesn't provide introspection. > > Bucket 3 could use cleanup. > Yep. We can get into it on the pseudofeatures patch. Your analysis here matches my understanding. > [...] > >
