Re: [PATCH v6 00/21] Convert QAPI doc comments to generate rST instead of texinfo

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Mon, 28 Sep 2020 at 14:04, Markus Armbruster <armbru@redhat.com> wrote:
>>
>> Peter Maydell <peter.maydell@linaro.org> writes:
>>
>> > On Fri, 25 Sep 2020 at 20:25, <no-reply@patchew.org> wrote:
>> >
>> >> In file included from ../src/qapi/qapi-schema.json:78:
>> >> ../src/qapi/migration.json:1747:1: unexpected de-indent (expected at 
>> >> least 13 spaces)
>> >
>> > This is yet another mis-indented line in a change to the QAPI
>> > doc-comments (commit 4c437254b807). It hit master in the
>> > latest migration pull after I'd sent out this patchseries
>> > but before patchew got round to testing..
>>
>> Obvious fixup for your PATCH 01:
>>
>> diff --git a/qapi/migration.json b/qapi/migration.json
>> index 7d9342c064..7f5e6fd681 100644
>> --- a/qapi/migration.json
>> +++ b/qapi/migration.json
>> @@ -1744,9 +1744,9 @@
>>  # Information about current dirty page rate of vm.
>>  #
>>  # @dirty-rate: @dirtyrate describing the dirty page rate of vm
>> -#          in units of MB/s.
>> -#          If this field returns '-1', it means querying has not
>> -#          yet started or completed.
>> +#              in units of MB/s.
>> +#              If this field returns '-1', it means querying has not
>> +#              yet started or completed.
>>  #
>>  # @status: status containing dirtyrate query status includes
>>  #          'unstarted' or 'measuring' or 'measured'
>>
>> Happy to fix it up in my tree.
>
> Yes, please.

One more issue:

    /work/armbru/qemu/docs/../qapi/machine.json:1000: WARNING: Unexpected 
indentation.
    /work/armbru/qemu/docs/../qapi/machine.json:1000: WARNING: Block quote ends 
without a blank line; unexpected unindent.

Line 1000 is at the beginning of a comment block.  Suboptimal.

After a bit of guessing, I arrived at this fix:

diff --git a/qapi/machine.json b/qapi/machine.json
index 7c9e69a9f5..756dacb06f 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1001,9 +1001,11 @@
 #
 # Request the balloon driver to change its balloon size.
 #
-# @value: the target logical size of the VM in bytes
+# @value: the target logical size of the VM in bytes.
 #         We can deduce the size of the balloon using this formula:
+#
 #            logical_vm_size = vm_ram_size - balloon_size
+#
 #         From it we have: balloon_size = vm_ram_size - @value
 #
 # Returns: - Nothing on success

Looks good?