Re: [PATCH] qapi: Fix format of the memory-backend-file's @rom property doc comment
David Hildenbrand writes:
> On 29.02.24 11:58, Stefano Garzarella wrote:
>> Reflow paragraph following commit a937b6aa73 ("qapi: Reformat doc
>> comments to conform to current conventions"): use 4 spaces indentation,
>> 70 columns width, and two spaces to separate sentences.
>>
>> Suggested-by: Markus Armbruster
>> Signed-off-by: Stefano Garzarella
>> ---
>> qapi/qom.json | 27 ++-
>> 1 file changed, 14 insertions(+), 13 deletions(-)
>> diff --git a/qapi/qom.json b/qapi/qom.json
>> index 2a6e49365a..db1b0fdea2 100644
>> --- a/qapi/qom.json
>> +++ b/qapi/qom.json
>> @@ -668,19 +668,20 @@
>> # @readonly: if true, the backing file is opened read-only; if false,
>> # it is opened read-write. (default: false)
>> #
>> -# @rom: whether to create Read Only Memory (ROM) that cannot be modified
>> -# by the VM. Any write attempts to such ROM will be denied. Most
>> -# use cases want writable RAM instead of ROM. However, selected use
>> -# cases, like R/O NVDIMMs, can benefit from ROM. If set to 'on',
>> -# create ROM; if set to 'off', create writable RAM; if set to
>> -# 'auto', the value of the @readonly property is used. This
>> -# property is primarily helpful when we want to have proper RAM in
>> -# configurations that would traditionally create ROM before this
>> -# property was introduced: VM templating, where we want to open a
>> -# file readonly (@readonly set to true) and mark the memory to be
>> -# private for QEMU (@share set to false). For this use case, we need
>> -# writable RAM instead of ROM, and want to set this property to 'off'.
>> -# (default: auto, since 8.2)
>> +# @rom: whether to create Read Only Memory (ROM) that cannot be
>> +# modified by the VM. Any write attempts to such ROM will be
>> +# denied. Most use cases want writable RAM instead of ROM.
>> +# However, selected use cases, like R/O NVDIMMs, can benefit from
>> +# ROM. If set to 'on', create ROM; if set to 'off', create
>> +# writable RAM; if set to 'auto', the value of the @readonly
>> +# property is used. This property is primarily helpful when we
>> +# want to have proper RAM in configurations that would
>> +# traditionally create ROM before this property was introduced: VM
>> +# templating, where we want to open a file readonly (@readonly set
>> +# to true) and mark the memory to be private for QEMU (@share set
>> +# to false). For this use case, we need writable RAM instead of
>> +# ROM, and want to set this property to 'off'. (default: auto,
>> +# since 8.2)
>> #
>> # Since: 2.1
>> ##
>
> Ideally, we'd have a format checker that complains like checkpatch usually
> would.
I agree!
A documentation pretty-printer would be best, but feels too hard. reST
syntax is baroque, and our own extensions make it more so.
A checker catching common mistakes should be feasible.
Patches welcome :)
> Reviewed-by: David Hildenbrand
Thanks!
Reviewed-by: Markus Armbruster
Re: [PATCH] qapi: Fix format of the memory-backend-file's @rom property doc comment
On 29.02.24 11:58, Stefano Garzarella wrote:
Reflow paragraph following commit a937b6aa73 ("qapi: Reformat doc
comments to conform to current conventions"): use 4 spaces indentation,
70 columns width, and two spaces to separate sentences.
Suggested-by: Markus Armbruster
Signed-off-by: Stefano Garzarella
---
qapi/qom.json | 27 ++-
1 file changed, 14 insertions(+), 13 deletions(-)
diff --git a/qapi/qom.json b/qapi/qom.json
index 2a6e49365a..db1b0fdea2 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -668,19 +668,20 @@
# @readonly: if true, the backing file is opened read-only; if false,
# it is opened read-write. (default: false)
#
-# @rom: whether to create Read Only Memory (ROM) that cannot be modified
-# by the VM. Any write attempts to such ROM will be denied. Most
-# use cases want writable RAM instead of ROM. However, selected use
-# cases, like R/O NVDIMMs, can benefit from ROM. If set to 'on',
-# create ROM; if set to 'off', create writable RAM; if set to
-# 'auto', the value of the @readonly property is used. This
-# property is primarily helpful when we want to have proper RAM in
-# configurations that would traditionally create ROM before this
-# property was introduced: VM templating, where we want to open a
-# file readonly (@readonly set to true) and mark the memory to be
-# private for QEMU (@share set to false). For this use case, we need
-# writable RAM instead of ROM, and want to set this property to 'off'.
-# (default: auto, since 8.2)
+# @rom: whether to create Read Only Memory (ROM) that cannot be
+# modified by the VM. Any write attempts to such ROM will be
+# denied. Most use cases want writable RAM instead of ROM.
+# However, selected use cases, like R/O NVDIMMs, can benefit from
+# ROM. If set to 'on', create ROM; if set to 'off', create
+# writable RAM; if set to 'auto', the value of the @readonly
+# property is used. This property is primarily helpful when we
+# want to have proper RAM in configurations that would
+# traditionally create ROM before this property was introduced: VM
+# templating, where we want to open a file readonly (@readonly set
+# to true) and mark the memory to be private for QEMU (@share set
+# to false). For this use case, we need writable RAM instead of
+# ROM, and want to set this property to 'off'. (default: auto,
+# since 8.2)
#
# Since: 2.1
##
Ideally, we'd have a format checker that complains like checkpatch
usually would.
Reviewed-by: David Hildenbrand
--
Cheers,
David / dhildenb
[PATCH] qapi: Fix format of the memory-backend-file's @rom property doc comment
Reflow paragraph following commit a937b6aa73 ("qapi: Reformat doc
comments to conform to current conventions"): use 4 spaces indentation,
70 columns width, and two spaces to separate sentences.
Suggested-by: Markus Armbruster
Signed-off-by: Stefano Garzarella
---
qapi/qom.json | 27 ++-
1 file changed, 14 insertions(+), 13 deletions(-)
diff --git a/qapi/qom.json b/qapi/qom.json
index 2a6e49365a..db1b0fdea2 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -668,19 +668,20 @@
# @readonly: if true, the backing file is opened read-only; if false,
# it is opened read-write. (default: false)
#
-# @rom: whether to create Read Only Memory (ROM) that cannot be modified
-# by the VM. Any write attempts to such ROM will be denied. Most
-# use cases want writable RAM instead of ROM. However, selected use
-# cases, like R/O NVDIMMs, can benefit from ROM. If set to 'on',
-# create ROM; if set to 'off', create writable RAM; if set to
-# 'auto', the value of the @readonly property is used. This
-# property is primarily helpful when we want to have proper RAM in
-# configurations that would traditionally create ROM before this
-# property was introduced: VM templating, where we want to open a
-# file readonly (@readonly set to true) and mark the memory to be
-# private for QEMU (@share set to false). For this use case, we need
-# writable RAM instead of ROM, and want to set this property to 'off'.
-# (default: auto, since 8.2)
+# @rom: whether to create Read Only Memory (ROM) that cannot be
+# modified by the VM. Any write attempts to such ROM will be
+# denied. Most use cases want writable RAM instead of ROM.
+# However, selected use cases, like R/O NVDIMMs, can benefit from
+# ROM. If set to 'on', create ROM; if set to 'off', create
+# writable RAM; if set to 'auto', the value of the @readonly
+# property is used. This property is primarily helpful when we
+# want to have proper RAM in configurations that would
+# traditionally create ROM before this property was introduced: VM
+# templating, where we want to open a file readonly (@readonly set
+# to true) and mark the memory to be private for QEMU (@share set
+# to false). For this use case, we need writable RAM instead of
+# ROM, and want to set this property to 'off'. (default: auto,
+# since 8.2)
#
# Since: 2.1
##
--
2.44.0
