[Qemu-devel] [PATCH for-2.9 5/6] tests/qapi-schema: Systematic positive doc comment tests

[Markus Armbruster]

We have a number of negative tests, but we don't have systematic
positive coverage.  Fix that.

Signed-off-by: Markus Armbruster <address@hidden>
---
 tests/Makefile.include          |  13 ++-
 tests/qapi-schema/doc-good.err  |   0
 tests/qapi-schema/doc-good.exit |   1 +
 tests/qapi-schema/doc-good.json | 136 ++++++++++++++++++++++
 tests/qapi-schema/doc-good.out  | 148 ++++++++++++++++++++++++
 tests/qapi-schema/doc-good.texi | 243 ++++++++++++++++++++++++++++++++++++++++
 6 files changed, 537 insertions(+), 4 deletions(-)
 create mode 100644 tests/qapi-schema/doc-good.err
 create mode 100644 tests/qapi-schema/doc-good.exit
 create mode 100644 tests/qapi-schema/doc-good.json
 create mode 100644 tests/qapi-schema/doc-good.out
 create mode 100644 tests/qapi-schema/doc-good.texi

diff --git a/tests/Makefile.include b/tests/Makefile.include
index 402e71c..8b497c5 100644
--- a/tests/Makefile.include
+++ b/tests/Makefile.include
@@ -379,6 +379,7 @@ qapi-schema += doc-duplicated-since.json
 qapi-schema += doc-empty-arg.json
 qapi-schema += doc-empty-section.json
 qapi-schema += doc-empty-symbol.json
+qapi-schema += doc-good.json
 qapi-schema += doc-interleaved-section.json
 qapi-schema += doc-invalid-end.json
 qapi-schema += doc-invalid-end2.json
@@ -607,6 +608,9 @@ $(SRC_PATH)/tests/qapi-schema/qapi-schema-test.json 
$(SRC_PATH)/scripts/qapi-int
                $(gen-out-type) -o tests -p "test-" $<, \
                "GEN","$@")
 
+tests/qapi-schema/doc-good.test.texi: 
$(SRC_PATH)/tests/qapi-schema/doc-good.json $(SRC_PATH)/scripts/qapi2texi.py 
$(qapi-py)
+       $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi2texi.py $< > 
$@,"GEN","$@")
+
 tests/test-string-output-visitor$(EXESUF): tests/test-string-output-visitor.o 
$(test-qapi-obj-y)
 tests/test-string-input-visitor$(EXESUF): tests/test-string-input-visitor.o 
$(test-qapi-obj-y)
 tests/test-qmp-event$(EXESUF): tests/test-qmp-event.o $(test-qapi-obj-y)
@@ -856,9 +860,6 @@ QEMU_IOTESTS_HELPERS-$(CONFIG_LINUX) = 
tests/qemu-iotests/socket_scm_helper$(EXE
 check-tests/qemu-iotests-quick.sh: tests/qemu-iotests-quick.sh 
qemu-img$(EXESUF) qemu-io$(EXESUF) $(QEMU_IOTESTS_HELPERS-y)
        $<
 
-.PHONY: check-tests/test-qapi.py
-check-tests/test-qapi.py: tests/test-qapi.py
-
 .PHONY: $(patsubst %, check-%, $(check-qapi-schema-y))
 $(patsubst %, check-%, $(check-qapi-schema-y)): check-%.json: 
$(SRC_PATH)/%.json
        $(call quiet-command, PYTHONPATH=$(SRC_PATH)/scripts \
@@ -871,10 +872,14 @@ $(patsubst %, check-%, $(check-qapi-schema-y)): 
check-%.json: $(SRC_PATH)/%.json
        @perl -p -e 's|\Q$(SRC_PATH)\E/||g' $*.test.err | diff -q 
$(SRC_PATH)/$*.err -
        @diff -q $(SRC_PATH)/$*.exit $*.test.exit
 
+.PHONY: check-tests/qapi-schema/doc-good.texi
+check-tests/qapi-schema/doc-good.texi: tests/qapi-schema/doc-good.test.texi
+       @diff -q $(SRC_PATH)/tests/qapi-schema/doc-good.texi $<
+
 # Consolidated targets
 
 .PHONY: check-qapi-schema check-qtest check-unit check check-clean
-check-qapi-schema: $(patsubst %,check-%, $(check-qapi-schema-y))
+check-qapi-schema: $(patsubst %,check-%, $(check-qapi-schema-y)) 
check-tests/qapi-schema/doc-good.texi
 check-qtest: $(patsubst %,check-qtest-%, $(QTEST_TARGETS))
 check-unit: $(patsubst %,check-%, $(check-unit-y))
 check-block: $(patsubst %,check-%, $(check-block-y))
diff --git a/tests/qapi-schema/doc-good.err b/tests/qapi-schema/doc-good.err
new file mode 100644
index 0000000..e69de29
diff --git a/tests/qapi-schema/doc-good.exit b/tests/qapi-schema/doc-good.exit
new file mode 100644
index 0000000..573541a
--- /dev/null
+++ b/tests/qapi-schema/doc-good.exit
@@ -0,0 +1 @@
+0
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
new file mode 100644
index 0000000..cfdc0a8
--- /dev/null
+++ b/tests/qapi-schema/doc-good.json
@@ -0,0 +1,136 @@
+# -*- Mode: Python -*-
+# Positive QAPI doc comment tests
+
+{ 'pragma': { 'doc-required': true } }
+
+##
+# = Section
+#
+# == Subsection
+#
+# *strong* _with emphasis_
+# @var {in braces}
+# * List item one
+# - Two, multiple
+#   lines
+#
+# 3. Three
+# Still in list
+#
+#   Not in list
+# - Second list
+# Note: still in list
+#
+# Note: not in list
+# 1. Third list
+#    is numbered
+#
+# - another item
+#
+# | example
+# | multiple lines
+#
+# Returns: the King
+# Since: the first age
+# Notes:
+#
+# 1. Lorem ipsum dolor sit amet
+#
+# 2. Ut enim ad minim veniam
+#
+# Duis aute irure dolor
+#
+# Example:
+#
+# -> in
+# <- out
+# Examples:
+# - *verbatim*
+# - {braces}
+##
+
+##
+# @Enum:
+# == Produces *invalid* texinfo
+# @one: The _one_ {and only}
+#
+# @two is undocumented
+##
+{ 'enum': 'Enum', 'data': [ 'one', 'two' ] }
+
+##
+# @Base:
+# @base1:
+#   the first member
+##
+{ 'struct': 'Base', 'data': { 'base1': 'Enum' } }
+
+##
+# @Variant1:
+# A paragraph
+#
+# Another paragraph (but no @var: line)
+##
+{ 'struct': 'Variant1', 'data': { 'var1': 'str' } }
+
+##
+# @Variant2:
+##
+{ 'struct': 'Variant2', 'data': {} }
+
+##
+# @Object:
+##
+{ 'union': 'Object',
+  'base': 'Base',
+  'discriminator': 'base1',
+  'data': { 'one': 'Variant1', 'two': 'Variant2' } }
+
+##
+# @SugaredUnion:
+##
+{ 'union': 'SugaredUnion',
+  'data': { 'one': 'Variant1', 'two': 'Variant2' } }
+
+##
+# == Another subsection
+##
+
+##
+# @cmd:
+# @arg1: the first argument
+#
+# @arg2: the second
+# argument
+# Note: @arg3 is undocumented
+# Returns: @Object
+# TODO: frobnicate
+# Notes:
+# - Lorem ipsum dolor sit amet
+# - Ut enim ad minim veniam
+#
+# Duis aute irure dolor
+# Example:
+#
+# -> in
+# <- out
+# Examples:
+# - *verbatim*
+# - {braces}
+# Since: 2.10
+##
+{ 'command': 'cmd',
+  'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
+  'returns': 'Object' }
+
+##
+# @cmd-boxed:
+# If you're bored enough to read this, go see a video of boxed cats
+# Example:
+#
+# -> in
+#
+# <- out
+##
+{ 'command': 'cmd-boxed', 'boxed': true,
+  'data': 'Object' }
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
new file mode 100644
index 0000000..70c1252
--- /dev/null
+++ b/tests/qapi-schema/doc-good.out
@@ -0,0 +1,148 @@
+object Base
+    member base1: Enum optional=False
+enum Enum ['one', 'two']
+object Object
+    base Base
+    tag base1
+    case one: Variant1
+    case two: Variant2
+enum QType ['none', 'qnull', 'qint', 'qstring', 'qdict', 'qlist', 'qfloat', 
'qbool']
+    prefix QTYPE
+object SugaredUnion
+    member type: SugaredUnionKind optional=False
+    tag type
+    case one: q_obj_Variant1-wrapper
+    case two: q_obj_Variant2-wrapper
+enum SugaredUnionKind ['one', 'two']
+object Variant1
+    member var1: str optional=False
+object Variant2
+command cmd q_obj_cmd-arg -> Object
+   gen=True success_response=True boxed=False
+command cmd-boxed Object -> None
+   gen=True success_response=True boxed=True
+object q_empty
+object q_obj_Variant1-wrapper
+    member data: Variant1 optional=False
+object q_obj_Variant2-wrapper
+    member data: Variant2 optional=False
+object q_obj_cmd-arg
+    member arg1: int optional=False
+    member arg2: str optional=True
+    member arg3: bool optional=False
+doc freeform
+    body=
+= Section
+
+== Subsection
+
+*strong* _with emphasis_
address@hidden {in braces}
+* List item one
+- Two, multiple
+lines
+
+3. Three
+Still in list
+
+Not in list
+- Second list
+Note: still in list
+
+Note: not in list
+1. Third list
+is numbered
+
+- another item
+
+| example
+| multiple lines
+
+Returns: the King
+Since: the first age
+Notes:
+
+1. Lorem ipsum dolor sit amet
+
+2. Ut enim ad minim veniam
+
+Duis aute irure dolor
+
+Example:
+
+-> in
+<- out
+Examples:
+- *verbatim*
+- {braces}
+doc symbol=Enum
+    body=
+== Produces *invalid* texinfo
+    arg=one
+The _one_ {and only}
+    arg=two
+
+    section=
address@hidden is undocumented
+doc symbol=Base
+    body=
+
+    arg=base1
+the first member
+doc symbol=Variant1
+    body=
+A paragraph
+
+Another paragraph (but no @var: line)
+    arg=var1
+
+doc symbol=Variant2
+    body=
+
+doc symbol=Object
+    body=
+
+doc symbol=SugaredUnion
+    body=
+
+    arg=type
+
+doc freeform
+    body=
+== Another subsection
+doc symbol=cmd
+    body=
+
+    arg=arg1
+the first argument
+    arg=arg2
+the second
+argument
+    arg=arg3
+
+    section=Note
address@hidden is undocumented
+    section=Returns
address@hidden
+    section=TODO
+frobnicate
+    section=Notes
+- Lorem ipsum dolor sit amet
+- Ut enim ad minim veniam
+
+Duis aute irure dolor
+    section=Example
+-> in
+<- out
+    section=Examples
+- *verbatim*
+- {braces}
+    section=Since
+2.10
+doc symbol=cmd-boxed
+    body=
+If you're bored enough to read this, go see a video of boxed cats
+    section=Example
+-> in
+
+<- out
diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi
new file mode 100644
index 0000000..1160aaf
--- /dev/null
+++ b/tests/qapi-schema/doc-good.texi
@@ -0,0 +1,243 @@
address@hidden Section
+
address@hidden Subsection
+
address@hidden  @emph{with emphasis} 
address@hidden @{in address@hidden
address@hidden @bullet
address@hidden
+List item one
address@hidden
+Two, multiple
+lines
+
address@hidden
+Three
+Still in list
+
address@hidden itemize
+
+Not in list
address@hidden @minus
address@hidden
+Second list
+Note: still in list
+
address@hidden itemize
+
+Note: not in list
address@hidden
address@hidden
+Third list
+is numbered
+
address@hidden
+another item
+
address@hidden
+example
address@hidden example
+
address@hidden
+multiple lines
address@hidden example
+
+
address@hidden enumerate
+
+Returns: the King
+Since: the first age
+Notes:
+
address@hidden
address@hidden
+Lorem ipsum dolor sit amet
+
address@hidden
+Ut enim ad minim veniam
+
address@hidden enumerate
+
+Duis aute irure dolor
+
+Example:
+
+-> in
+<- out
+Examples:
address@hidden @minus
address@hidden
address@hidden
address@hidden
address@hidden@}
address@hidden itemize
+
+
+
address@hidden {Enum} Enum
+
address@hidden Produces @emph{invalid} texinfo
+
address@hidden:}
address@hidden @asis
address@hidden @code{one}
+The  @emph{one}  @{and address@hidden
address@hidden @code{two}
+Not documented
address@hidden table
address@hidden is undocumented
+
address@hidden deftp
+
+
+
address@hidden {Object} Base
+
+
+
address@hidden:}
address@hidden @asis
address@hidden @code{base1: Enum}
+the first member
address@hidden table
+
+
address@hidden deftp
+
+
+
address@hidden {Object} Variant1
+
+A paragraph
+
+Another paragraph (but no @code{var}: line)
+
address@hidden:}
address@hidden @asis
address@hidden @code{var1: string}
+Not documented
address@hidden table
+
+
address@hidden deftp
+
+
+
address@hidden {Object} Variant2
+
+
+
+
address@hidden deftp
+
+
+
address@hidden {Object} Object
+
+
+
address@hidden:}
address@hidden @asis
address@hidden The members of @code{Base}
address@hidden The members of @code{Variant1} when @code{base1} is @t{"one"}
address@hidden The members of @code{Variant2} when @code{base1} is @t{"two"}
address@hidden table
+
+
address@hidden deftp
+
+
+
address@hidden {Object} SugaredUnion
+
+
+
address@hidden:}
address@hidden @asis
address@hidden @code{type}
+One of @t{"one"}, @t{"two"}
address@hidden @code{data: Variant1} when @code{type} is @t{"one"}
address@hidden @code{data: Variant2} when @code{type} is @t{"two"}
address@hidden table
+
+
address@hidden deftp
+
+
address@hidden Another subsection
+
+
address@hidden Command {} cmd
+
+
+
address@hidden:}
address@hidden @asis
address@hidden @code{arg1: int}
+the first argument
address@hidden @code{arg2: string} (optional)
+the second
+argument
address@hidden @code{arg3: boolean}
+Not documented
address@hidden table
+
+
address@hidden:}
address@hidden is undocumented
+
address@hidden:}
address@hidden
+
address@hidden:}
+frobnicate
+
address@hidden:}
address@hidden @minus
address@hidden
+Lorem ipsum dolor sit amet
address@hidden
+Ut enim ad minim veniam
+
address@hidden itemize
+
+Duis aute irure dolor
+
address@hidden:}
address@hidden
+-> in
+<- out
address@hidden example
+
+
address@hidden:}
address@hidden
+- *verbatim*
+- @address@hidden
address@hidden example
+
+
address@hidden:}
+2.10
+
address@hidden deftypefn
+
+
+
address@hidden Command {} cmd-boxed
+
+If you're bored enough to read this, go see a video of boxed cats
+
address@hidden:} the members of @code{Object}
+
address@hidden:}
address@hidden
+-> in
+
+<- out
address@hidden example
+
+
address@hidden deftypefn
+
+
-- 
2.7.4