Re: [PATCH v2 08/18] qapi: add cross-references to migration.json

[John Snow <jsnow@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 2042 bytes --]

On Fri, Jul 11, 2025, 4:55 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  qapi/migration.json | 68 ++++++++++++++++++++++-----------------------
> >  1 file changed, 34 insertions(+), 34 deletions(-)
> >
> > diff --git a/qapi/migration.json b/qapi/migration.json
> > index 59a213aeb6c..eda27c18102 100644
> > --- a/qapi/migration.json
> > +++ b/qapi/migration.json
>
> [...]
>
> > @@ -1735,8 +1735,8 @@
> >  #     list connected to a destination interface endpoint.
> >  #
> >  # @exit-on-error: Exit on incoming migration failure.  Default true.
> > -#     When set to false, the failure triggers a MIGRATION event, and
> > -#     error details could be retrieved with query-migrate.
> > +#     When set to false, the failure triggers a :qapi:event:`MIGRATION`
> > +#     event, and error details could be retrieved with `query-migrate`.
> >  #     (since 9.1)
>
> Suggest to have the the commit message note why we need :qapi:event:.
> Perhaps like this:
>
>   Note that a reference to MIGRATION needs to be disambiguated with a
>   :qapi:event: prefix.  Without this, Sphinx complains
>
>       more than one target found for 'any' cross-reference 'MIGRATION':
> could be :std:ref:`Migration framework` or
> :qapi:event:`QMP:migration.MIGRATION`
>

OK


> Aside: this fuzzy matching of references feels too clever by half.
>

That's the perils of the `any` syntax. In exchange for something very
terse, you have to contend with multiple domains of possible match targets.

On the whole, I think it's nice that you can reference `something` without
needing to know the precise geospatial coordinates of where that thing is.
Downside is that the matches may occasionally be fuzzier than you'd prefer.

The QAPI domain only ever matches in a case sensitive way, but other
domains in Sphinx aren't as strict, and I don't control those!


> >  #
> >  # Since: 2.3
>
> [...]
>
>

[-- Attachment #2: Type: text/html, Size: 3296 bytes --]