From a87a9b4d4fc4dcfa2925b1b90474f0ec69d59edf Mon Sep 17 00:00:00 2001
From: Markus Armbruster <armbru@redhat.com>
Date: Fri, 28 Apr 2023 12:54:22 +0200
Subject: [PATCH] tests/qapi-schema/doc-good: Improve argument description
 tests

Improve the comments to better describe what they test.

Cover argument description starting on a new line indented.  This
style isn't documented in docs/devel/qapi-code-gen.rst.  qapi-gen.py
accepts it, but messes up indentation: it's stripped from the first
line, not subsequent ones.  The next commit will fix this.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-11-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
---
 tests/qapi-schema/doc-good.json | 15 +++++++++------
 tests/qapi-schema/doc-good.out  | 16 +++++++++-------
 2 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 445471daee..34c3dcbe97 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -54,7 +54,7 @@
 ##
 # @Enum:
 #
-# @one: The _one_ {and only}
+# @one: The _one_ {and only}, description on the same line
 #
 # Features:
 # @enum-feat: Also _one_ {and only}
@@ -73,7 +73,8 @@
 # @Base:
 #
 # @base1:
-# the first member
+# description starts on a new line,
+# not indented
 ##
 { 'struct': 'Base', 'data': { 'base1': 'Enum' },
   'if': { 'all': ['IFALL1', 'IFALL2'] } }
@@ -120,7 +121,8 @@
 ##
 # @Alternate:
 #
-# @i: an integer
+# @i: description starts on the same line
+#     remainder indented the same
 #     @b is undocumented
 #
 # Features:
@@ -138,10 +140,11 @@
 ##
 # @cmd:
 #
-# @arg1: the first argument
+# @arg1:
+#     description starts on a new line,
+#     indented
 #
-# @arg2: the second
-#        argument
+# @arg2: the second argument
 #
 # Features:
 # @cmd-feat1: a feature
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index afa48dcd94..2ba72ae558 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -104,7 +104,7 @@ doc symbol=Enum
     body=
 
     arg=one
-The _one_ {and only}
+The _one_ {and only}, description on the same line
     arg=two
 
     feature=enum-feat
@@ -117,12 +117,13 @@ doc symbol=Base
     body=
 
     arg=base1
-the first member
+description starts on a new line,
+not indented
 doc symbol=Variant1
     body=
 A paragraph
 
-Another paragraph (but no @var: line)
+Another paragraph
 
 @var1 is undocumented
     arg=var1
@@ -143,7 +144,8 @@ doc symbol=Alternate
     body=
 
     arg=i
-an integer
+description starts on the same line
+remainder indented the same
 @b is undocumented
     arg=b
 
@@ -156,10 +158,10 @@ doc symbol=cmd
     body=
 
     arg=arg1
-the first argument
+description starts on a new line,
+    indented
     arg=arg2
-the second
-argument
+the second argument
     arg=arg3
 
     feature=cmd-feat1