From 976474fdb2706626987677990e22f10d71918902 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:25 +0100 Subject: tests/qapi-schema: Fix test 'QAPI rST doc' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The test compares Sphinx plain-text output against a golden reference. To work on Windows hosts, it filters out carriage returns in both files. Unfortunately, the filter doesn't work: it creates an empty file. Comparing empty files always succeeds. Fix the filter, and update the golden reference to current Sphinx output. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-2-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-good.txt | 21 +++++++++------------ tests/qapi-schema/meson.build | 10 ++++++---- 2 files changed, 15 insertions(+), 16 deletions(-) (limited to 'tests') diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index b3b76bd..879f6ff 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -44,7 +44,7 @@ Values ~~~~~~ "one" (**If: **"IFONE") - The _one_ {and only} + The _one_ {and only}, description on the same line "two" Not documented @@ -76,7 +76,7 @@ Members ~~~~~~~ "base1": "Enum" - the first member + description starts on a new line, minimally indented If @@ -90,7 +90,9 @@ If A paragraph -Another paragraph (but no "var": line) +Another paragraph + +"var1" is undocumented Members @@ -141,7 +143,8 @@ Members ~~~~~~~ "i": "int" - an integer "b" is undocumented + description starts on the same line remainder indented the same "b" + is undocumented "b": "boolean" Not documented @@ -172,10 +175,10 @@ Arguments ~~~~~~~~~ "arg1": "int" - the first argument + description starts on a new line, indented "arg2": "string" (optional) - the second argument + description starts on the same line remainder indented differently "arg3": "boolean" Not documented @@ -203,12 +206,6 @@ Returns "Object" -TODO -~~~~ - -frobnicate - - Notes ~~~~~ diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index af085f7..44a9385 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -273,15 +273,17 @@ if build_docs output: ['doc-good.txt.nocr'], input: qapi_doc_out[0], build_by_default: true, - command: [remove_cr, '@INPUT@'], - capture: true) + command: [remove_cr], + capture: true, + feed: true) qapi_doc_ref_nocr = custom_target('QAPI rST doc reference newline-sanitized', output: ['doc-good.ref.nocr'], input: files('doc-good.txt'), build_by_default: true, - command: [remove_cr, '@INPUT@'], - capture: true) + command: [remove_cr], + capture: true, + feed: true) test('QAPI rST doc', diff, args: ['-u', qapi_doc_ref_nocr[0], qapi_doc_out_nocr[0]], suite: ['qapi-schema', 'qapi-doc']) -- cgit v1.1 From fc68b9ffc933a5c38c0b880629a7f543a4a9b06b Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:26 +0100 Subject: tests/qapi-schema: Cover duplicate 'Features:' line MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We don't actually recognize the second 'Features:' line. Instead, we treat it as an untagged section. If it was followed by feature description, we'd reject that like "description of '@feat2:' follows a section". Less than clear. To be improved shortly. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-3-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-duplicate-features.err | 0 tests/qapi-schema/doc-duplicate-features.json | 11 +++++++++++ tests/qapi-schema/doc-duplicate-features.out | 22 ++++++++++++++++++++++ tests/qapi-schema/meson.build | 1 + 4 files changed, 34 insertions(+) create mode 100644 tests/qapi-schema/doc-duplicate-features.err create mode 100644 tests/qapi-schema/doc-duplicate-features.json create mode 100644 tests/qapi-schema/doc-duplicate-features.out (limited to 'tests') diff --git a/tests/qapi-schema/doc-duplicate-features.err b/tests/qapi-schema/doc-duplicate-features.err new file mode 100644 index 0000000..e69de29 diff --git a/tests/qapi-schema/doc-duplicate-features.json b/tests/qapi-schema/doc-duplicate-features.json new file mode 100644 index 0000000..a4d559e --- /dev/null +++ b/tests/qapi-schema/doc-duplicate-features.json @@ -0,0 +1,11 @@ +# Duplicate 'Features:' line + +## +# @foo: +# +# Features: +# @feat: mumble +# +# Features: +## +{ 'command': 'foo', 'features': ['feat'] } diff --git a/tests/qapi-schema/doc-duplicate-features.out b/tests/qapi-schema/doc-duplicate-features.out new file mode 100644 index 0000000..43bfe10 --- /dev/null +++ b/tests/qapi-schema/doc-duplicate-features.out @@ -0,0 +1,22 @@ +module ./builtin +object q_empty +enum QType + prefix QTYPE + member none + member qnull + member qnum + member qstring + member qdict + member qlist + member qbool +module doc-duplicate-features.json +command foo None -> None + gen=True success_response=True boxed=False oob=False preconfig=False + feature feat +doc symbol=foo + body= + + feature=feat +mumble + section=None +Features: diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index 44a9385..4c714c7 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -66,6 +66,7 @@ schemas = [ 'doc-bad-union-member.json', 'doc-before-include.json', 'doc-before-pragma.json', + 'doc-duplicate-features.json', 'doc-duplicated-arg.json', 'doc-duplicated-return.json', 'doc-duplicated-since.json', -- cgit v1.1 From 0ba2915b92813ce1982563378c48b6d2ba9a71ca Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:27 +0100 Subject: tests/qapi-schema: Cover 'Features:' not followed by descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A 'Features:' line without any features is useless, but not an error now. However, a later commit will make it one, because that makes rejecting duplicate 'Features:' easier. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-4-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-empty-features.err | 0 tests/qapi-schema/doc-empty-features.json | 10 ++++++++++ tests/qapi-schema/doc-empty-features.out | 19 +++++++++++++++++++ tests/qapi-schema/meson.build | 1 + 4 files changed, 30 insertions(+) create mode 100644 tests/qapi-schema/doc-empty-features.err create mode 100644 tests/qapi-schema/doc-empty-features.json create mode 100644 tests/qapi-schema/doc-empty-features.out (limited to 'tests') diff --git a/tests/qapi-schema/doc-empty-features.err b/tests/qapi-schema/doc-empty-features.err new file mode 100644 index 0000000..e69de29 diff --git a/tests/qapi-schema/doc-empty-features.json b/tests/qapi-schema/doc-empty-features.json new file mode 100644 index 0000000..06f814e --- /dev/null +++ b/tests/qapi-schema/doc-empty-features.json @@ -0,0 +1,10 @@ +# 'Features:' line not followed by feature descriptions + +## +# @foo: +# +# Features: +# +# not a description +## +{ 'command': 'foo' } diff --git a/tests/qapi-schema/doc-empty-features.out b/tests/qapi-schema/doc-empty-features.out new file mode 100644 index 0000000..0f85623 --- /dev/null +++ b/tests/qapi-schema/doc-empty-features.out @@ -0,0 +1,19 @@ +module ./builtin +object q_empty +enum QType + prefix QTYPE + member none + member qnull + member qnum + member qstring + member qdict + member qlist + member qbool +module doc-empty-features.json +command foo None -> None + gen=True success_response=True boxed=False oob=False preconfig=False +doc symbol=foo + body= + + section=None +not a description diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index 4c714c7..4b8329d 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -71,6 +71,7 @@ schemas = [ 'doc-duplicated-return.json', 'doc-duplicated-since.json', 'doc-empty-arg.json', + 'doc-empty-features.json', 'doc-empty-section.json', 'doc-empty-symbol.json', 'doc-good.json', -- cgit v1.1 From 15333abed9112f99e0b1af4327154af733b987d3 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:29 +0100 Subject: qapi: Improve error position for bogus argument descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When documented arguments don't exist, the error message points to the beginning of the definition comment. Point to the first bogus argument description instead. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-6-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-bad-alternate-member.err | 2 +- tests/qapi-schema/doc-bad-boxed-command-arg.err | 2 +- tests/qapi-schema/doc-bad-command-arg.err | 2 +- tests/qapi-schema/doc-bad-enum-member.err | 2 +- tests/qapi-schema/doc-bad-event-arg.err | 2 +- tests/qapi-schema/doc-bad-feature.err | 2 +- tests/qapi-schema/doc-bad-union-member.err | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) (limited to 'tests') diff --git a/tests/qapi-schema/doc-bad-alternate-member.err b/tests/qapi-schema/doc-bad-alternate-member.err index d7286bb..1f6b7d2 100644 --- a/tests/qapi-schema/doc-bad-alternate-member.err +++ b/tests/qapi-schema/doc-bad-alternate-member.err @@ -1 +1 @@ -doc-bad-alternate-member.json:3: documented members 'aa', 'bb' do not exist +doc-bad-alternate-member.json:7: documented members 'aa', 'bb' do not exist diff --git a/tests/qapi-schema/doc-bad-boxed-command-arg.err b/tests/qapi-schema/doc-bad-boxed-command-arg.err index 7137af3..d6793e7 100644 --- a/tests/qapi-schema/doc-bad-boxed-command-arg.err +++ b/tests/qapi-schema/doc-bad-boxed-command-arg.err @@ -1 +1 @@ -doc-bad-boxed-command-arg.json:9: documented member 'a' does not exist +doc-bad-boxed-command-arg.json:11: documented member 'a' does not exist diff --git a/tests/qapi-schema/doc-bad-command-arg.err b/tests/qapi-schema/doc-bad-command-arg.err index 18ed076..b76167e 100644 --- a/tests/qapi-schema/doc-bad-command-arg.err +++ b/tests/qapi-schema/doc-bad-command-arg.err @@ -1 +1 @@ -doc-bad-command-arg.json:3: documented member 'b' does not exist +doc-bad-command-arg.json:6: documented member 'b' does not exist diff --git a/tests/qapi-schema/doc-bad-enum-member.err b/tests/qapi-schema/doc-bad-enum-member.err index 7efeb47..0aa8d8e 100644 --- a/tests/qapi-schema/doc-bad-enum-member.err +++ b/tests/qapi-schema/doc-bad-enum-member.err @@ -1 +1 @@ -doc-bad-enum-member.json:3: documented member 'a' does not exist +doc-bad-enum-member.json:5: documented member 'a' does not exist diff --git a/tests/qapi-schema/doc-bad-event-arg.err b/tests/qapi-schema/doc-bad-event-arg.err index d13cacf..90527d5 100644 --- a/tests/qapi-schema/doc-bad-event-arg.err +++ b/tests/qapi-schema/doc-bad-event-arg.err @@ -1 +1 @@ -doc-bad-event-arg.json:3: documented member 'a' does not exist +doc-bad-event-arg.json:5: documented member 'a' does not exist diff --git a/tests/qapi-schema/doc-bad-feature.err b/tests/qapi-schema/doc-bad-feature.err index 49d1746..3166c6a 100644 --- a/tests/qapi-schema/doc-bad-feature.err +++ b/tests/qapi-schema/doc-bad-feature.err @@ -1 +1 @@ -doc-bad-feature.json:3: documented feature 'a' does not exist +doc-bad-feature.json:7: documented feature 'a' does not exist diff --git a/tests/qapi-schema/doc-bad-union-member.err b/tests/qapi-schema/doc-bad-union-member.err index 6dd2726..cdf1225 100644 --- a/tests/qapi-schema/doc-bad-union-member.err +++ b/tests/qapi-schema/doc-bad-union-member.err @@ -1 +1 @@ -doc-bad-union-member.json:3: documented members 'a', 'b' do not exist +doc-bad-union-member.json:5: documented members 'a', 'b' do not exist -- cgit v1.1 From bf00dc19f3aacf014b308d57bb0debf250339396 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:30 +0100 Subject: qapi: Improve error position for bogus invalid "Returns" section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When something other than a command has a "Returns" section, the error message points to the beginning of the definition comment. Point to the "Returns" section instead. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-7-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-invalid-return.err | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'tests') diff --git a/tests/qapi-schema/doc-invalid-return.err b/tests/qapi-schema/doc-invalid-return.err index 2ad89c5..bc5826d 100644 --- a/tests/qapi-schema/doc-invalid-return.err +++ b/tests/qapi-schema/doc-invalid-return.err @@ -1 +1 @@ -doc-invalid-return.json:3: 'Returns:' is only valid for commands +doc-invalid-return.json:5: 'Returns:' is only valid for commands -- cgit v1.1 From 573e2223f91a1662dad3c4ab5f6724bbe2633eff Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:31 +0100 Subject: qapi: Improve error message for empty doc sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Improve the message for an empty tagged section from empty doc section 'Note' to text required after 'Note:' and the message for an empty argument or feature description from empty doc section 'foo' to text required after '@foo:' Improve the error position to refer to the beginning of the empty section instead of its end. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-8-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-empty-section.err | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'tests') diff --git a/tests/qapi-schema/doc-empty-section.err b/tests/qapi-schema/doc-empty-section.err index ba7ba70..5f03a6d 100644 --- a/tests/qapi-schema/doc-empty-section.err +++ b/tests/qapi-schema/doc-empty-section.err @@ -1 +1 @@ -doc-empty-section.json:7:1: empty doc section 'Note' +doc-empty-section.json:6: text required after 'Note:' -- cgit v1.1 From 31c54b92ad0816ab1c4eddaf4b60c0b17a75dfc9 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:32 +0100 Subject: qapi: Rename QAPIDoc.Section.name to .tag MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Since the previous commit, QAPIDoc.Section.name is either None (untagged section) or the section's tag string ('Returns', '@name', ...). Rename it to .tag. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-9-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/test-qapi.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'tests') diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py index 14f7b62..4009543 100755 --- a/tests/qapi-schema/test-qapi.py +++ b/tests/qapi-schema/test-qapi.py @@ -130,7 +130,7 @@ def test_frontend(fname): for feat, section in doc.features.items(): print(' feature=%s\n%s' % (feat, section.text)) for section in doc.sections: - print(' section=%s\n%s' % (section.name, section.text)) + print(' section=%s\n%s' % (section.tag, section.text)) def open_test_result(dir_name, file_name, update): -- cgit v1.1 From 56c64dd60aebb9c856ab63de74c9e81acd079436 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:33 +0100 Subject: qapi: Reject section heading in the middle of a doc comment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/devel/qapi-code-gen.txt claims "A heading line must be the first line of the documentation comment block" since commit 55ec69f8b16 (docs/devel/qapi-code-gen.txt: Update to new rST backend conventions). Not true, we have code to make it work anywhere in a free-form doc comment: commit dcdc07a97cb (qapi: Make section headings start a new doc comment block). Make it true, for simplicity's sake. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-10-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-good.json | 4 +++- tests/qapi-schema/doc-non-first-section.err | 1 + tests/qapi-schema/doc-non-first-section.json | 6 ++++++ tests/qapi-schema/doc-non-first-section.out | 0 4 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 tests/qapi-schema/doc-non-first-section.err create mode 100644 tests/qapi-schema/doc-non-first-section.json create mode 100644 tests/qapi-schema/doc-non-first-section.out (limited to 'tests') diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 24a84fe..0479d16 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -9,7 +9,9 @@ ## # = Section -# +## + +## # == Subsection # # *with emphasis* diff --git a/tests/qapi-schema/doc-non-first-section.err b/tests/qapi-schema/doc-non-first-section.err new file mode 100644 index 0000000..eeced2b --- /dev/null +++ b/tests/qapi-schema/doc-non-first-section.err @@ -0,0 +1 @@ +doc-non-first-section.json:5:1: '=' heading must come first in a comment block diff --git a/tests/qapi-schema/doc-non-first-section.json b/tests/qapi-schema/doc-non-first-section.json new file mode 100644 index 0000000..1590876 --- /dev/null +++ b/tests/qapi-schema/doc-non-first-section.json @@ -0,0 +1,6 @@ +# = section must be first line + +## +# +# = Not first +## diff --git a/tests/qapi-schema/doc-non-first-section.out b/tests/qapi-schema/doc-non-first-section.out new file mode 100644 index 0000000..e69de29 -- cgit v1.1 From d23055b8db88a54b372ebbbffe3681169d2a767a Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:34 +0100 Subject: qapi: Require descriptions and tagged sections to be indented MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit By convention, we indent the second and subsequent lines of descriptions and tagged sections, except for examples. Turn this into a hard rule, and apply it to examples, too. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-11-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé [Straightforward conflicts in qapi/migration.json resolved] --- tests/qapi-schema/doc-good.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'tests') diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 0479d16..977bb38 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -165,11 +165,11 @@ # Duis aute irure dolor # Example: # -# -> in -# <- out +# -> in +# <- out # Examples: -# - *verbatim* -# - {braces} +# - *verbatim* +# - {braces} # Since: 2.10 ## { 'command': 'cmd', @@ -185,9 +185,9 @@ # @cmd-feat2: another feature # Example: # -# -> in +# -> in # -# <- out +# <- out ## { 'command': 'cmd-boxed', 'boxed': true, 'data': 'Object', -- cgit v1.1 From 66227e90478b34a2bc4bbd4f11f5ea637184c20b Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:35 +0100 Subject: qapi: Recognize section tags and 'Features:' only after blank line MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Putting a blank line before section tags and 'Features:' is good, existing practice. Enforce it. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-12-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-duplicated-return.err | 2 +- tests/qapi-schema/doc-duplicated-return.json | 1 + tests/qapi-schema/doc-duplicated-since.err | 2 +- tests/qapi-schema/doc-duplicated-since.json | 1 + tests/qapi-schema/doc-good.json | 9 +++++++++ tests/qapi-schema/doc-invalid-return.err | 2 +- tests/qapi-schema/doc-invalid-return.json | 1 + 7 files changed, 15 insertions(+), 3 deletions(-) (limited to 'tests') diff --git a/tests/qapi-schema/doc-duplicated-return.err b/tests/qapi-schema/doc-duplicated-return.err index fe97e3d..f19a2b8 100644 --- a/tests/qapi-schema/doc-duplicated-return.err +++ b/tests/qapi-schema/doc-duplicated-return.err @@ -1 +1 @@ -doc-duplicated-return.json:7:1: duplicated 'Returns' section +doc-duplicated-return.json:8:1: duplicated 'Returns' section diff --git a/tests/qapi-schema/doc-duplicated-return.json b/tests/qapi-schema/doc-duplicated-return.json index b44b5ae..4e1ec2e 100644 --- a/tests/qapi-schema/doc-duplicated-return.json +++ b/tests/qapi-schema/doc-duplicated-return.json @@ -4,5 +4,6 @@ # @foo: # # Returns: 0 +# # Returns: 1 ## diff --git a/tests/qapi-schema/doc-duplicated-since.err b/tests/qapi-schema/doc-duplicated-since.err index abca141..565b753 100644 --- a/tests/qapi-schema/doc-duplicated-since.err +++ b/tests/qapi-schema/doc-duplicated-since.err @@ -1 +1 @@ -doc-duplicated-since.json:7:1: duplicated 'Since' section +doc-duplicated-since.json:8:1: duplicated 'Since' section diff --git a/tests/qapi-schema/doc-duplicated-since.json b/tests/qapi-schema/doc-duplicated-since.json index 343cd87..2755f95 100644 --- a/tests/qapi-schema/doc-duplicated-since.json +++ b/tests/qapi-schema/doc-duplicated-since.json @@ -4,5 +4,6 @@ # @foo: # # Since: 0 +# # Since: 1 ## diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 977bb38..5bb2b69 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -154,22 +154,29 @@ # Features: # @cmd-feat1: a feature # @cmd-feat2: another feature +# # 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', @@ -180,9 +187,11 @@ ## # @cmd-boxed: # If you're bored enough to read this, go see a video of boxed cats +# # Features: # @cmd-feat1: a feature # @cmd-feat2: another feature +# # Example: # # -> in diff --git a/tests/qapi-schema/doc-invalid-return.err b/tests/qapi-schema/doc-invalid-return.err index bc5826d..3d9e71c 100644 --- a/tests/qapi-schema/doc-invalid-return.err +++ b/tests/qapi-schema/doc-invalid-return.err @@ -1 +1 @@ -doc-invalid-return.json:5: 'Returns:' is only valid for commands +doc-invalid-return.json:6: 'Returns:' is only valid for commands diff --git a/tests/qapi-schema/doc-invalid-return.json b/tests/qapi-schema/doc-invalid-return.json index 95e7583..1aabef3 100644 --- a/tests/qapi-schema/doc-invalid-return.json +++ b/tests/qapi-schema/doc-invalid-return.json @@ -2,6 +2,7 @@ ## # @FOO: +# # Returns: blah ## { 'event': 'FOO' } -- cgit v1.1 From 0b82a7440c22056745a925d0b1c070e18534aa0e Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:37 +0100 Subject: qapi: Merge adjacent untagged sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The parser mostly doesn't create adjacent untagged sections, and merging the ones it does create is hardly worth the bother. I'm doing it to avoid behavioral change in the next commit. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-14-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-empty-features.out | 2 -- 1 file changed, 2 deletions(-) (limited to 'tests') diff --git a/tests/qapi-schema/doc-empty-features.out b/tests/qapi-schema/doc-empty-features.out index 0f85623..473f595 100644 --- a/tests/qapi-schema/doc-empty-features.out +++ b/tests/qapi-schema/doc-empty-features.out @@ -14,6 +14,4 @@ command foo None -> None gen=True success_response=True boxed=False oob=False preconfig=False doc symbol=foo body= - - section=None not a description -- cgit v1.1 From 629c5075aa6fb853855256cd7d380903e9b7ffbc Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:39 +0100 Subject: qapi: Reject multiple and empty feature descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The parser recognizes only the first "Features:" line. Any subsequent ones are treated as ordinary text, as visible in test case doc-duplicate-features. Recognize "Features:" lines anywhere. A second one is an error. A 'Features:' line without any features is useless, but not an error. Make it an error. This makes detecting a second "Features:" line easier. qapi/run-state.json actually has an instance of this since commit fe17522d854 (qapi: Remove deprecated 'singlestep' member of StatusInfo). Clean it up. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-16-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-duplicate-features.err | 1 + tests/qapi-schema/doc-duplicate-features.out | 22 ---------------------- tests/qapi-schema/doc-empty-features.err | 1 + tests/qapi-schema/doc-empty-features.out | 17 ----------------- 4 files changed, 2 insertions(+), 39 deletions(-) (limited to 'tests') diff --git a/tests/qapi-schema/doc-duplicate-features.err b/tests/qapi-schema/doc-duplicate-features.err index e69de29..cadb295 100644 --- a/tests/qapi-schema/doc-duplicate-features.err +++ b/tests/qapi-schema/doc-duplicate-features.err @@ -0,0 +1 @@ +doc-duplicate-features.json:9:1: duplicated 'Features:' line diff --git a/tests/qapi-schema/doc-duplicate-features.out b/tests/qapi-schema/doc-duplicate-features.out index 43bfe10..e69de29 100644 --- a/tests/qapi-schema/doc-duplicate-features.out +++ b/tests/qapi-schema/doc-duplicate-features.out @@ -1,22 +0,0 @@ -module ./builtin -object q_empty -enum QType - prefix QTYPE - member none - member qnull - member qnum - member qstring - member qdict - member qlist - member qbool -module doc-duplicate-features.json -command foo None -> None - gen=True success_response=True boxed=False oob=False preconfig=False - feature feat -doc symbol=foo - body= - - feature=feat -mumble - section=None -Features: diff --git a/tests/qapi-schema/doc-empty-features.err b/tests/qapi-schema/doc-empty-features.err index e69de29..2709a18 100644 --- a/tests/qapi-schema/doc-empty-features.err +++ b/tests/qapi-schema/doc-empty-features.err @@ -0,0 +1 @@ +doc-empty-features.json:8:1: feature descriptions expected diff --git a/tests/qapi-schema/doc-empty-features.out b/tests/qapi-schema/doc-empty-features.out index 473f595..e69de29 100644 --- a/tests/qapi-schema/doc-empty-features.out +++ b/tests/qapi-schema/doc-empty-features.out @@ -1,17 +0,0 @@ -module ./builtin -object q_empty -enum QType - prefix QTYPE - member none - member qnull - member qnum - member qstring - member qdict - member qlist - member qbool -module doc-empty-features.json -command foo None -> None - gen=True success_response=True boxed=False oob=False preconfig=False -doc symbol=foo - body= -not a description -- cgit v1.1 From adb0193b90bd1fecd7d6dda70fc1c2d2e45ceae0 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 16 Feb 2024 15:58:40 +0100 Subject: qapi: Divorce QAPIDoc from QAPIParseError MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit QAPIDoc stores a reference to QAPIParser just to pass it to QAPIParseError. The resulting error position depends on the state of the parser. It happens to be the current comment line. Servicable, but action at a distance. The commit before previous moved most uses of QAPIParseError from QAPIDoc to QAPIParser. There are just three left. Convert them to QAPISemError. This involves passing info to a few methods. Then drop the reference to QAPIParser. The three errors lose the column number. Not really interesting here: it's the comment line's indentation. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-17-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-duplicated-arg.err | 2 +- tests/qapi-schema/doc-duplicated-return.err | 2 +- tests/qapi-schema/doc-duplicated-since.err | 2 +- tests/qapi-schema/doc-empty-arg.err | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) (limited to 'tests') diff --git a/tests/qapi-schema/doc-duplicated-arg.err b/tests/qapi-schema/doc-duplicated-arg.err index 0d0d777..d876312 100644 --- a/tests/qapi-schema/doc-duplicated-arg.err +++ b/tests/qapi-schema/doc-duplicated-arg.err @@ -1 +1 @@ -doc-duplicated-arg.json:6:1: 'a' parameter name duplicated +doc-duplicated-arg.json:6: 'a' parameter name duplicated diff --git a/tests/qapi-schema/doc-duplicated-return.err b/tests/qapi-schema/doc-duplicated-return.err index f19a2b8..503b916 100644 --- a/tests/qapi-schema/doc-duplicated-return.err +++ b/tests/qapi-schema/doc-duplicated-return.err @@ -1 +1 @@ -doc-duplicated-return.json:8:1: duplicated 'Returns' section +doc-duplicated-return.json:8: duplicated 'Returns' section diff --git a/tests/qapi-schema/doc-duplicated-since.err b/tests/qapi-schema/doc-duplicated-since.err index 565b753..a9b60c0 100644 --- a/tests/qapi-schema/doc-duplicated-since.err +++ b/tests/qapi-schema/doc-duplicated-since.err @@ -1 +1 @@ -doc-duplicated-since.json:8:1: duplicated 'Since' section +doc-duplicated-since.json:8: duplicated 'Since' section diff --git a/tests/qapi-schema/doc-empty-arg.err b/tests/qapi-schema/doc-empty-arg.err index 2d0f35f..83f4fc6 100644 --- a/tests/qapi-schema/doc-empty-arg.err +++ b/tests/qapi-schema/doc-empty-arg.err @@ -1 +1 @@ -doc-empty-arg.json:5:1: invalid parameter name +doc-empty-arg.json:5: invalid parameter name -- cgit v1.1