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>

diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 445471daee810a397d31be4788cd3e8616c87f61..34c3dcbe97cf8c0eb9b3266a6a9f29983fd61820 100644 (file)
--- 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 afa48dcd9442314878ca9b5b417df9ff3df8ea94..2ba72ae558dcd96c1dc661d46b336d237ec1a52d 100644 (file)
--- 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