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]

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.
@@ -1053,7 +1053,6 @@ For example::
  #     <- {
  #          ... lots of output ...
  #        }
- #
  ##
  { 'command': 'query-blockstats',
    'data': { '*query-nodes': 'bool' },

scripts/qapi/parser.py

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