diff options
| author | Markus Armbruster <armbru@redhat.com> | 2024-02-16 15:58:34 +0100 |
|---|---|---|
| committer | Markus Armbruster <armbru@redhat.com> | 2024-02-26 10:43:56 +0100 |
| commit | d23055b8db88a54b372ebbbffe3681169d2a767a (patch) | |
| tree | d1c9331cc9a6c44000043d8f2b8f03f37b8ca2da /docs/devel | |
| parent | 56c64dd60aebb9c856ab63de74c9e81acd079436 (diff) | |
| download | qemu-d23055b8db88a54b372ebbbffe3681169d2a767a.zip qemu-d23055b8db88a54b372ebbbffe3681169d2a767a.tar.gz qemu-d23055b8db88a54b372ebbbffe3681169d2a767a.tar.bz2 | |
qapi: Require descriptions and tagged sections to be indented
By convention, we indent the second and subsequent lines of
descriptions and tagged sections, except for examples.
Turn this into a hard rule, and apply it to examples, too.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240216145841.2099240-11-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
[Straightforward conflicts in qapi/migration.json resolved]
Diffstat (limited to 'docs/devel')
| -rw-r--r-- | docs/devel/qapi-code-gen.rst | 15 |
1 files changed, 7 insertions, 8 deletions
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 756adc1..77a40f3 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -973,7 +973,7 @@ commands and events), member (for structs and unions), branch (for alternates), or value (for enums), a description of each feature (if any), and finally optional tagged sections. -Descriptions start with '\@name:'. The description text should be +Descriptions start with '\@name:'. The description text must be indented like this:: # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed @@ -997,8 +997,8 @@ A tagged section starts with one of the following words: "Note:"/"Notes:", "Since:", "Example:"/"Examples:", "Returns:", "TODO:". The section ends with the start of a new section. -The second and subsequent lines of sections other than -"Example"/"Examples" should be indented like this:: +The second and subsequent lines of tagged sections must be indented +like this:: # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco # laboris nisi ut aliquip ex ea commodo consequat. @@ -1049,11 +1049,10 @@ For example:: # # Example: # - # -> { "execute": "query-blockstats" } - # <- { - # ... lots of output ... - # } - # + # -> { "execute": "query-blockstats" } + # <- { + # ... lots of output ... + # } ## { 'command': 'query-blockstats', 'data': { '*query-nodes': 'bool' }, |