ShuriZma
/
xemu
mirror of https://github.com/xemu-project/xemu.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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]
This commit is contained in:
Markus Armbruster 2024-02-16 15:58:34 +01:00
parent 56c64dd60a
commit d23055b8db
28 changed files with 2289 additions and 2287 deletions
docs/devel
qapi-code-gen.rst
scripts/qapi
parser.py

7
docs/devel/qapi-code-gen.rst
View File

@ -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 alternates), or value (for enums), a description of each feature (if
any), and finally optional tagged sections. 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:: indented like this::
# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # @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:", "Note:"/"Notes:", "Since:", "Example:"/"Examples:", "Returns:",
"TODO:". The section ends with the start of a new section. "TODO:". The section ends with the start of a new section.
The second and subsequent lines of sections other than The second and subsequent lines of tagged sections must be indented
"Example"/"Examples" should be indented like this:: like this::
# Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco
# laboris nisi ut aliquip ex ea commodo consequat. # laboris nisi ut aliquip ex ea commodo consequat.
@ -1053,7 +1053,6 @@ For example::
# <- { # <- {
# ... lots of output ... # ... lots of output ...
# } # }
#
## ##
{ 'command': 'query-blockstats', { 'command': 'query-blockstats',
'data': { '*query-nodes': 'bool' }, 'data': { '*query-nodes': 'bool' },

3
scripts/qapi/parser.py
View File

@ -492,6 +492,9 @@ class QAPIDoc:
# indeterminate indentation # indeterminate indentation
if self.text != '': if self.text != '':
# non-blank, non-first line determines indentation # non-blank, non-first line determines indentation
if indent == 0:
raise QAPIParseError(
self._parser, "line needs to be indented")
self._indent = indent self._indent = indent
elif indent < self._indent: elif indent < self._indent:
raise QAPIParseError( raise QAPIParseError(