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

[Peter Xu]

On Tue, Sep 26, 2023 at 10:43:22PM +0200, Markus Armbruster wrote:
> Loophole...  Here's the stupidest solution that could possibly work:
> 
>     ##
>     # @MigrationParameter:
>     #
>     # TODO: elide from generated documentation (type is used only
>     #     internally, and not visible in QMP)
>     #
>     # Features:
>     #
>     # @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period
>     #     are experimental.
>     #
>     # Since: 2.4
>     ##
> 
> Works because the QAPI generator currently doesn't flag missing member
> documentation, and quietly substitutes "Not documented" instead.

Didn't work for me..

In file included from ../qapi/qapi-schema.json:61:
../qapi/migration.json:681:1: unexpected de-indent (expected at least 4 spaces)

L681 points to the "Features:".

But maybe I did it wrong somewhere?

> Looks like
> 
>     "MigrationParameter" (Enum)
>     ---------------------------
> 
> 
>     Values
>     ~~~~~~
> 
>     "announce-initial"
>        Not documented
> 
>     "announce-max"
>        Not documented
> 
> and so forth.  Sure ugly, but is it really worse than before?  It's now
> obviously useless, whereas before it was unobviously useless.
> 
> This will break when we tighten up the QAPI generator to require member
> documentation.  Along we a few hundred other violators.
> 
> We might want to add a way to say "members intentionally undocumented".
> Could be useful for qapi/ui.json's QKeyCode.  Most of its 162 members
> don't really need documentation...

Yes I'd be super happy if we can declare that in qapi/.

Please let me know if I missed something above on the trick; you're right
it's only about the documentation we want to get rid of.  If we can achieve
that with qapi generating the helpers that'll definitely be perfect.

Thanks,

-- 
Peter Xu