[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 10/17] tests/qapi-schema/doc-good: Improve argument description t
From: |
Markus Armbruster |
Subject: |
[PATCH 10/17] tests/qapi-schema/doc-good: Improve argument description tests |
Date: |
Fri, 28 Apr 2023 12:54:22 +0200 |
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>
---
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
--
2.39.2
- Re: [PATCH 11/17] qapi: Fix argument description indentation stripping, (continued)
- [PATCH 04/17] meson: Fix to make QAPI generator output depend on main.py, Markus Armbruster, 2023/04/28
- [PATCH 07/17] qapi: Tidy up a slightly awkward TODO comment, Markus Armbruster, 2023/04/28
- [PATCH 14/17] qapi: Section parameter @indent is no longer used, drop, Markus Armbruster, 2023/04/28
- [PATCH 03/17] qapi: Fix crash on stray double quote character, Markus Armbruster, 2023/04/28
- [PATCH 10/17] tests/qapi-schema/doc-good: Improve argument description tests,
Markus Armbruster <=
- [PATCH 09/17] tests/qapi-schema/doc-good: Improve a comment, Markus Armbruster, 2023/04/28
- [PATCH 15/17] docs/devel/qapi-code-gen: Update doc comment conventions, Markus Armbruster, 2023/04/28
- [PATCH 06/17] sphinx/qapidoc: Do not emit TODO sections into user manuals, Markus Armbruster, 2023/04/28
- [PATCH 08/17] qapi/dump: Indent bulleted lists consistently, Markus Armbruster, 2023/04/28