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

[Markus Armbruster <armbru@redhat.com>]

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`

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

>  #
>  # Since: 2.3

[...]