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

[Markus Armbruster <armbru@redhat.com>]

Peter Xu <peterx@redhat.com> writes:

> 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.

Unless we can get rid of it.

> 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).

Yes.  A different example is QKeyCode.

>> * 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.

Yes.

> 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.

Makes sense, but even then tools to assist with spotting missing
documentation would be useful.  How to best do that is not obvious to
me.