On Tue, Oct 17, 2023 at 08:32:02AM +0200, Markus Armbruster wrote: > I can see two useful QAPI generator features:
Agreed. > > * Improved handling of missing member documentation > > Problem: many members lack documentation. We silently generate > documentation like > > name-of-member > Not documented > > for them. > > Possible improvement: make missing member documentation a hard error, > create a knob to suppress the error for a type. Open question: how to > best document member documentation is incomplete. @MigrationSetParameters should fall into this category. IMHO it's just wanted in some use case that we don't want to list member documentations, instead we want to show something else. In this case referring to documentation of another object (@MigrationParameters). > > * Suppress documentation for internal-only definitions > > Problem: generated documentation covers everything, even types that > aren't visible in QMP. The irrelevant material is distracting and > possibly confusing for users, and may be bothersome to maintain for > developers. > > Possible improvement: include only the types visible in QMP in > documentation, similar to how we do for query-qmp-schema. Open > question: what level of documentation to require for internal-only > types. @MigrationParameter should fall into this category. IMHO we should treat them the same as any code written, for example, in C. We don't necessarily need to apply any rule on it, like we don't require comment for any line of code, but we prefer comments / documentations when necessary. That (how much documentation needed for the code) is judged during code review, and can apply also to internally used QAPI definitions. Thanks, -- Peter Xu
