docs/devel/qapi-code-gen: Update doc comment conventions

The commit before previous relaxed the indentation rules to let us
improve the doc comment conventions.  This commit changes the written
conventions.  The next commits will update QAPI schemas to conform to
them.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-16-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>

docs/devel/qapi-code-gen.rst

@@ -947,6 +947,11 @@ Example::
  #   <- get that
  ##
 
+For legibility, wrap text paragraphs so every line is at most 70
+characters long.
+
+Separate sentences with two spaces.
+
 
 Definition documentation
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -963,22 +968,12 @@ 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.
 
-The description of an argument or feature 'name' starts with
+Descriptions start with '\@name:'.  The description text should be
-'\@name:'.  The description text can start on the line following the
+indented like this::
-'\@name:', in which case it must not be indented at all.  It can also
-start on the same line as the '\@name:'.  In this case if it spans
-multiple lines then second and subsequent lines must be indented to
-line up with the first character of the first line of the
-description::
 
- # @argone:
+ # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
- # This is a two line description
+ #     do eiusmod tempor incididunt ut labore et dolore magna aliqua.
- # in the first style.
- #
- # @argtwo: This is a two line description
- #          in the second style.
 
-The number of spaces between the ':' and the text is not significant.
 .. FIXME The parser accepts these things in almost any order.
 
 .. FIXME union branches should be described, too.
@@ -990,23 +985,26 @@ The feature descriptions must be preceded by a line "Features:", like
 this::
 
   # Features:
+  #
   # @feature: Description text
 
 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 text of a section can start on a new line, in
+The second and subsequent lines of sections other than
-which case it must not be indented at all.  It can also start
+"Example"/"Examples" should be indented like this::
-on the same line as the "Note:", "Returns:", etc tag.  In this
+
-case if it spans multiple lines then second and subsequent
+ # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco
-lines must be indented to match the first, in the same way as
+ #     laboris nisi ut aliquip ex ea commodo consequat.
-multiline argument descriptions.
+ #
+ #     Duis aute irure dolor in reprehenderit in voluptate velit esse
+ #     cillum dolore eu fugiat nulla pariatur.
 
 A "Since: x.y.z" tagged section lists the release that introduced the
 definition.
 
-An "Example" or "Examples" section is automatically rendered entirely
+An "Example" or "Examples" section is rendered entirely
 as literal fixed-width text.  "TODO" sections are not rendered at all
 (they are for developers, not users of QMP).  In other sections, the
 text is formatted, and rST markup can be used.
@@ -1036,8 +1034,8 @@ For example::
  #
  # Query the @BlockStats for all virtual block devices.
  #
- # @query-nodes: If true, the command will query all the
+ # @query-nodes: If true, the command will query all the block nodes
- #               block nodes ... explain, explain ...  (since 2.3)
+ #     ... explain, explain ...  (since 2.3)
  #
  # Returns: A list of @BlockStats for each virtual block devices.
  #