[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v2 08/30] qapi: Use ':' after @argument in doc comments
From: |
Markus Armbruster |
Subject: |
Re: [PATCH v2 08/30] qapi: Use ':' after @argument in doc comments |
Date: |
Fri, 14 Feb 2020 14:28:47 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) |
Markus Armbruster <address@hidden> writes:
> Peter Maydell <address@hidden> writes:
>
>> Some qapi doc comments have forgotten the ':' after the
>> @argument, like this:
>>
>> # @filename Filename for the new image file
>> # @size Size of the virtual disk in bytes
>>
>> The result is that these are parsed as part of the body
>> text and appear as a run-on line:
>> filename Filename for the new image file size Size of the virtual disk in
>> bytes"
>> followed by
>> filename: string
>> Not documented
>> size: int
>> Not documented
>>
>> in the 'Members' section.
>>
>> Correct the formatting.
>>
>> Signed-off-by: Peter Maydell <address@hidden>
>> Reviewed-by: Markus Armbruster <address@hidden>
>
> The title sounds like it's just a tweak, but it actually fixes bugs in
> the generated documentation. Suggest to change the title to
>
> qapi: Fix incorrect "Not documented" claims in QMP documentation
>
> R-by stands regardless.
Forgot to mention:
[...]
>> @@ -4645,17 +4645,17 @@
>> #
>> # Driver specific image creation options for vhdx.
>> #
>> -# @file Node to create the image format on
>> -# @size Size of the virtual disk in bytes
>> -# @log-size Log size in bytes, must be a multiple of 1 MB
>> -# (default: 1 MB)
>> -# @block-size Block size in bytes, must be a multiple of 1 MB and not
>> -# larger than 256 MB (default: automatically choose a
>> block
>> -# size depending on the image size)
>> -# @subformat vhdx subformat (default: dynamic)
>> -# @block-state-zero Force use of payload blocks of type 'ZERO'.
>> Non-standard,
>> -# but default. Do not set to 'off' when using 'qemu-img
>> -# convert' with subformat=dynamic.
>> +# @file: Node to create the image format on
>> +# @size: Size of the virtual disk in bytes
>> +# @log-size: Log size in bytes, must be a multiple of 1 MB
>> +# (default: 1 MB)
>> +# @block-size: Block size in bytes, must be a multiple of 1 MB and not
>> +# larger than 256 MB (default: automatically choose a block
>> +# size depending on the image size)
>> +# @subformat: vhdx subformat (default: dynamic)
>> +# @block-state-zero: Force use of payload blocks of type 'ZERO'.
>> Non-standard,
>> +# but default. Do not set to 'off' when using 'qemu-img
>> +# convert' with subformat=dynamic.
>> #
>> # Since: 2.12
>> ##
Kevin dislikes the loss of visual alignment here. I dislike the
formatting before and after the patch. I suggested a new style:
# @file:
# Node to create the image format on
#
# @size:
# Size of the virtual disk in bytes
#
# @log-size:
# Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
#
# @block-size:
# Block size in bytes, must be a multiple of 1 MB and not larger
# than 256 MB (default: automatically choose a block size depending
# on the image size)
#
# @subformat:
# vhdx subformat (default: dynamic)
#
# @block-state-zero:
# Force use of payload blocks of type 'ZERO'. Non-standard, but
# default. Do not set to 'off' when using 'qemu-img convert' with
# subformat=dynamic.
Nobody disliked this style. Peter reports his code already supports it,
but objects to converting to it in his series. Okay; we can convert
later. More churn, but the individual patches / series are simpler.
- [PATCH v2 05/30] qga/qapi-schema.json: Fix indent level on doc comments, (continued)
- [PATCH v2 10/30] qapi: Remove hardcoded tabs, Peter Maydell, 2020/02/13
- [PATCH v2 06/30] qga/qapi-schema.json: minor format fixups for rST, Peter Maydell, 2020/02/13
- [PATCH v2 08/30] qapi: Use ':' after @argument in doc comments, Peter Maydell, 2020/02/13
- [PATCH v2 11/30] qapi/ui.json: Put input-send-event body text in the right place, Peter Maydell, 2020/02/13
- [PATCH v2 12/30] qapi/ui.json: Avoid `...' texinfo style quoting, Peter Maydell, 2020/02/13
- [PATCH v2 13/30] qapi/block-core.json: Use explicit bulleted lists, Peter Maydell, 2020/02/13
- [PATCH v2 14/30] qapi/ui.json: Use explicit bulleted lists, Peter Maydell, 2020/02/13
- [PATCH v2 16/30] qapi: Add blank lines before bulleted lists, Peter Maydell, 2020/02/13