Re: [PATCH 1/2] qapi/block-core: Improve MapEntry documentation

[Markus Armbruster]

Max Reitz <mreitz@redhat.com> writes:

> MapEntry and BlockDeviceMapEntry are kind of the same thing, and the
> latter is not used, so we want to remove it.  However, the documentation
> it provides for some fields is better than that of MapEntry, so steal
> some of it for the latter.
>
> (And adjust them a bit in the process, because I feel like we can make
> them even clearer.)
>
> Signed-off-by: Max Reitz <mreitz@redhat.com>
> ---
>  qapi/block-core.json | 18 +++++++++++++-----
>  1 file changed, 13 insertions(+), 5 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index 1b8b4156b4..3f86675357 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -244,17 +244,25 @@
>  #
>  # Mapping information from a virtual block range to a host file range
>  #
> -# @start: the start byte of the mapped virtual range
> +# @start: virtual (guest) offset of the first byte described by this
> +#         entry
>  #
>  # @length: the number of bytes of the mapped virtual range
>  #
> -# @data: whether the mapped range has data
> +# @data: reading the image will actually read data from a file (in
> +#        particular, if @offset is present this means that the sectors
> +#        are not simply preallocated, but contain actual data in raw
> +#        format)
>  #
> -# @zero: whether the virtual blocks are zeroed
> +# @zero: whether the virtual blocks read as zeroes
>  #
> -# @depth: the depth of the mapping
> +# @depth: number of layers (0 = top image, 1 = top image's backing
> +#         file, ..., n - 1 = bottom image (where n is the number of
> +#         images in the chain)) before reaching one for which the
> +#         range is allocated
>  #
> -# @offset: the offset in file that the virtual sectors are mapped to
> +# @offset: if present, the image file stores the data for this range
> +#          in raw format at the given (host) offset
>  #
>  # @filename: filename that is referred to by @offset
>  #

I can't vouch for the comment's accuracy without reading a lot of code,
but I can say that the comment is clearly much clearer, so:

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