Peter Xu <pet...@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.
