Re: [PATCH v1] qapi: document parameters of query-cpu-model-* QAPI commands

[Markus Armbruster <armbru@redhat.com>]

David Hildenbrand <david@redhat.com> writes:

> Let's document the parameters of these commands, so we can remove them
> from the "documentation-exceptions" list.
>
> While at it, extend the "Returns:" documentation as well, fixing a wrong
> use of CpuModelBaselineInfo vs. CpuModelCompareInfo for
> query-cpu-model-comparison.
>
> Cc: Markus Armbruster <armbru@redhat.com>
> Cc: Eric Blake <eblake@redhat.com>
> Cc: Eduardo Habkost <eduardo@habkost.net>
> Cc: Marcel Apfelbaum <marcel.apfelbaum@gmail.com>
> Cc: "Philippe Mathieu-Daudé" <philmd@linaro.org>
> Cc: Yanan Wang <wangyanan55@huawei.com>
> Signed-off-by: David Hildenbrand <david@redhat.com>
> ---
>  qapi/machine-target.json | 46 +++++++++++++++++++++++++++-------------
>  qapi/pragma.json         |  3 ---
>  2 files changed, 31 insertions(+), 18 deletions(-)
>
> diff --git a/qapi/machine-target.json b/qapi/machine-target.json
> index 519adf3220..7883616cce 100644
> --- a/qapi/machine-target.json
> +++ b/qapi/machine-target.json
> @@ -124,11 +124,12 @@
>  ##
>  # @query-cpu-model-comparison:
>  #
> -# Compares two CPU models, returning how they compare in a specific
> -# configuration.  The results indicates how both models compare
> -# regarding runnability.  This result can be used by tooling to make
> -# decisions if a certain CPU model will run in a certain configuration
> -# or if a compatible CPU model has to be created by baselining.
> +# Compares two CPU models, @modela and @modelb, returning how they
> +# compare in a specific configuration.  The results indicates how
> +# both models compare regarding runnability.  This result can be
> +# used by tooling to make decisions if a certain CPU model will
> +# run in a certain configuration or if a compatible CPU model has
> +# to be created by baselining.
>  #
>  # Usually, a CPU model is compared against the maximum possible CPU
>  # model of a certain configuration (e.g. the "host" model for KVM).
> @@ -154,7 +155,14 @@
>  # Some architectures may not support comparing CPU models.  s390x
>  # supports comparing CPU models.
>  #
> -# Returns: a CpuModelBaselineInfo
> +# @modela: description of the first CPU model to compare, referred to as
> +#     "model A" in CpuModelCompareResult
> +#
> +# @modelb: description of the second CPU model to compare, referred to as
> +#     "model B" in CpuModelCompareResult
> +#
> +# Returns: a CpuModelCompareInfo, describing how both CPU models

Scratch the comma?

> +#     compare
>  #
>  # Errors:
>  #     - if comparing CPU models is not supported
> @@ -175,9 +183,9 @@
>  ##
>  # @query-cpu-model-baseline:
>  #
> -# Baseline two CPU models, creating a compatible third model.  The
> -# created model will always be a static, migration-safe CPU model (see
> -# "static" CPU model expansion for details).
> +# Baseline two CPU models, @modela and @modelb, creating a compatible
> +# third model.  The created model will always be a static,
> +# migration-safe CPU model (see "static" CPU model expansion for details).
>  #
>  # This interface can be used by tooling to create a compatible CPU
>  # model out two CPU models.  The created CPU model will be identical
> @@ -204,7 +212,11 @@
>  # Some architectures may not support baselining CPU models.  s390x
>  # supports baselining CPU models.
>  #
> -# Returns: a CpuModelBaselineInfo
> +# @modela: description of the first CPU model to baseline
> +#
> +# @modelb: description of the second CPU model to baseline
> +#
> +# Returns: a CpuModelBaselineInfo, describing the baselined CPU model

Scratch the comma?

>  #
>  # Errors:
>  #     - if baselining CPU models is not supported
> @@ -243,10 +255,10 @@
>  ##
>  # @query-cpu-model-expansion:
>  #
> -# Expands a given CPU model (or a combination of CPU model +
> -# additional options) to different granularities, allowing tooling to
> -# get an understanding what a specific CPU model looks like in QEMU
> -# under a certain configuration.
> +# Expands a given CPU model, @model, (or a combination of CPU model +
> +# additional options) to different granularities, specified by
> +# @type, allowing tooling to get an understanding what a specific
> +# CPU model looks like in QEMU under a certain configuration.
>  #
>  # This interface can be used to query the "host" CPU model.
>  #
> @@ -269,7 +281,11 @@
>  # Some architectures may not support all expansion types.  s390x
>  # supports "full" and "static". Arm only supports "full".
>  #
> -# Returns: a CpuModelExpansionInfo
> +# @model: description of the CPU model to expand
> +#
> +# @type: expansion type, specifying how to expand the CPU model
> +#
> +# Returns: a CpuModelExpansionInfo, describing the expanded CPU model
>  #
>  # Errors:
>  #     - if expanding CPU models is not supported
> diff --git a/qapi/pragma.json b/qapi/pragma.json
> index 6929ab776e..0d82bc1a03 100644
> --- a/qapi/pragma.json
> +++ b/qapi/pragma.json
> @@ -90,9 +90,6 @@
>          'XDbgBlockGraph',
>          'YankInstanceType',
>          'blockdev-reopen',
> -        'query-cpu-model-baseline',
> -        'query-cpu-model-comparison',
> -        'query-cpu-model-expansion',
>          'query-rocker',
>          'query-rocker-ports',
>          'query-stats-schemas',

Reviewed-by: Markus Armbruster <armbru@redhat.com>