Re: [PATCH v3 0/4] qapi/migration: Dedup migration parameter objects and fix tls-authz crash

[Peter Xu]

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