Re: [PATCH v3 4/4] migration/qapi: Drop @MigrationParameter enum

[Markus Armbruster <armbru@redhat.com>]

Peter Xu <peterx@redhat.com> writes:

> On Mon, Oct 16, 2023 at 08:29:58AM +0200, Markus Armbruster wrote:
>> Better, because even stupider: drop the feature flags.  They have no
>> effect on internal use, and there is no external use.
>> 
>>     ##
>>     # @MigrationParameter:
>>     #
>>     # TODO: elide from generated documentation (type is used only
>>     #     internally, and not visible in QMP)
>>     #
>>     # Since: 2.4
>>     ##
>>     { 'enum': 'MigrationParameter',
>>       'data': ['announce-initial', 'announce-max',
>>                'announce-rounds', 'announce-step',
>>                'compress-level', 'compress-threads', 'decompress-threads',
>>                'compress-wait-thread', 'throttle-trigger-threshold',
>>                'cpu-throttle-initial', 'cpu-throttle-increment',
>>                'cpu-throttle-tailslow',
>>                'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth',
>>                'downtime-limit',
>>                'x-checkpoint-delay',
>>                'block-incremental',
>>                'multifd-channels',
>>                'xbzrle-cache-size', 'max-postcopy-bandwidth',
>>                'max-cpu-throttle', 'multifd-compression',
>>                'multifd-zlib-level', 'multifd-zstd-level',
>>                'block-bitmap-mapping',
>>                'x-vcpu-dirty-limit-period',
>>                'vcpu-dirty-limit'] }
>
> Didn't work either, unfortunately..  Compile is fine, but I still see the
> lines generated in qemu-qmp-ref.7.
>
>         MigrationParameter (Enum)
>         Values
>         announce-initial
>                 Not documented
>
>         announce-max
>                 Not documented
>
>         announce-rounds
>                 Not documented
>
>         announce-step
>                 Not documented
>
>         compress-level
>                 Not documented
>         [...]

I didn't claim these will *not* be generated :)

> Patch attached.
>
> Thanks,

Solutions:

0. Do nothing

   The QEMU QMP Reference manual documents MigrationParameter, even
   though it is not actually visible in QMP.

   The documentation source is a duplicate.

1. Dumb down MigrationParameter's doc comment (your attached patch)

   The QEMU QMP Reference manual documents MigrationParameter, even
   though it is not actually visible in QMP.  In addition to useless,
   the documentation is embarrassing: lots of "Not documented".

2. Make MigrationParameter a C enum instead of a QAPI enum (your v3
   patch)

   The QEMU QMP Reference manual doesn't uselessly document
   MigrationParameter (it still uselessly documents other internal-only
   things).

   We replace 20 lines of QAPI schema by 100 lines of C.

3. Improve the QAPI generator to generate docs only for definitions
   visible externally, and to require doc comments only then

   The QEMU QMP Reference manual doesn't uselessly document
   internal-only stuff.

   This solution doesn't exist, yet.