Re: [PATCH for-8.2 v2 1/2] qapi/migration: Deduplicate migration parameter field comments

[Markus Armbruster <armbru@redhat.com>]

Peter Xu <peterx@redhat.com> writes:

> We used to have three objects that have always the same list of parameters

We have!

> and comments are always duplicated:
>
>   - @MigrationParameter
>   - @MigrationParameters
>   - @MigrateSetParameters
>
> Before we can deduplicate the code, it's fairly straightforward to
> deduplicate the comments first, so for each time we add a new migration
> parameter we don't need to copy the same paragraphs three times.

De-duplicating the code would be nice, but we haven't done so in years,
which suggests it's hard enough not to be worth the trouble.

De-duplicating the documentation is certainly easier.

Is that what you're trying to say?

Our discussion pros and cons that is happening in review of v1 should be
captured in the commit message, right here.

> Make the @MigrationParameter the major source of truth, while leaving the
> rest two to reference to it.

Any particular reason for picking this one?

> We do have a slight problem in the man/html pages generated, that for the
> latter two objects we'll get a list of Members but with all of them saying
> "Not documented":
>
>    Members
>        announce-initial: int (optional)
>               Not documented
>
>        announce-max: int (optional)
>               Not documented
>
>        announce-rounds: int (optional)
>               Not documented
>
>        [...]
>
> Even though we'll have a reference there telling the reader to jump over to
> read the @MigrationParameter sections instead, for example:
>
>    MigrationParameters (Object)
>
>        The object structure to represent a list of migration parameters.
>        The optional members aren't actually optional.  For detailed
>        explanation for each of the field, please refer to the documentation
>        of MigrationParameter.
>
> So hopefully that's not too bad.. and we can leave it for later to make it
> even better.

It's plenty bad, I'm afraid.  It comes out as a short paragraph "don't
look here, look there", followed by screenfuls claiming "not
documented."  Embarrassing.  Worse, *misleading*, because the short
paragraph is easy to miss.

Also discussed in review of v1.  Let's continue there, to avoid
splitting the thread.

> Signed-off-by: Peter Xu <peterx@redhat.com>