qemu/tests/qapi-schema/args-alternate.json

# we do not allow alternate arguments

##
# @Alt:
##
{ 'alternate': 'Alt', 'data': { 'case1': 'int', 'case2': 'str' } }

##
# @oops:
##
{ 'command': 'oops', 'data': 'Alt' }
qapi-tests: New tests for union, alternate command arguments A command's 'data' must be a struct type, given either as a dictionary, or as struct type name. Existing test case data-int.json covers simple type 'int'. Add test cases for type names referring to union and alternate types. The latter is caught (good), but the former is not (bug). Events have the same problem, but since they get checked by the same code, we don't bother to duplicate the tests. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> 2015-07-01 10:54:11 +03:00			`# we do not allow alternate arguments`
qapi: add qapi2texi script As the name suggests, the qapi2texi script converts JSON QAPI description into a texi file suitable for different target formats (info/man/txt/pdf/html...). It parses the following kind of blocks: Free-form: ## # = Section # == Subsection # # Some text foo with emphasis # 1. with a list # 2. like that # # And some code: # \| $ echo foo # \| -> do this # \| <- get that # ## Symbol description: ## # @symbol: # # Symbol body ditto ergo sum. Foo bar # baz ding. # # @param1: the frob to frobnicate # @param2: #optional how hard to frobnicate # # Returns: the frobnicated frob. # If frob isn't frobnicatable, GenericError. # # Since: version # Notes: notes, comments can have # - itemized list # - like this # # Example: # # -> { "execute": "quit" } # <- { "return": {} } # ## That's roughly following the following EBNF grammar: api_comment = "##\n" comment "##\n" comment = freeform_comment \| symbol_comment freeform_comment = { "# " text "\n" \| "#\n" } symbol_comment = "# @" name ":\n" { member \| tag_section \| freeform_comment } member = "# @" name ':' [ text ] "\n" freeform_comment tag_section = "# " ( "Returns:", "Since:", "Note:", "Notes:", "Example:", "Examples:" ) [ text ] "\n" freeform_comment text = free text with markup Note that the grammar is ambiguous: a line "# @foo:\n" can be parsed both as freeform_comment and as symbol_comment. The actual parser recognizes symbol_comment. See docs/qapi-code-gen.txt for more details. Deficiencies and limitations: - the generated QMP documentation includes internal types - union type support is lacking - type information is lacking in generated documentation - doc comment error message positions are imprecise, they point to the beginning of the comment. - a few minor issues, all marked TODO/FIXME in the code Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20170113144135.5150-16-marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [test-qapi.py tweaked to avoid trailing empty lines in .out] Signed-off-by: Markus Armbruster <armbru@redhat.com> 2017-01-13 17:41:29 +03:00
			`##`
			`# @Alt:`
			`##`
qapi-tests: New tests for union, alternate command arguments A command's 'data' must be a struct type, given either as a dictionary, or as struct type name. Existing test case data-int.json covers simple type 'int'. Add test cases for type names referring to union and alternate types. The latter is caught (good), but the former is not (bug). Events have the same problem, but since they get checked by the same code, we don't bother to duplicate the tests. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> 2015-07-01 10:54:11 +03:00			`{ 'alternate': 'Alt', 'data': { 'case1': 'int', 'case2': 'str' } }`
qapi: add qapi2texi script As the name suggests, the qapi2texi script converts JSON QAPI description into a texi file suitable for different target formats (info/man/txt/pdf/html...). It parses the following kind of blocks: Free-form: ## # = Section # == Subsection # # Some text foo with emphasis # 1. with a list # 2. like that # # And some code: # \| $ echo foo # \| -> do this # \| <- get that # ## Symbol description: ## # @symbol: # # Symbol body ditto ergo sum. Foo bar # baz ding. # # @param1: the frob to frobnicate # @param2: #optional how hard to frobnicate # # Returns: the frobnicated frob. # If frob isn't frobnicatable, GenericError. # # Since: version # Notes: notes, comments can have # - itemized list # - like this # # Example: # # -> { "execute": "quit" } # <- { "return": {} } # ## That's roughly following the following EBNF grammar: api_comment = "##\n" comment "##\n" comment = freeform_comment \| symbol_comment freeform_comment = { "# " text "\n" \| "#\n" } symbol_comment = "# @" name ":\n" { member \| tag_section \| freeform_comment } member = "# @" name ':' [ text ] "\n" freeform_comment tag_section = "# " ( "Returns:", "Since:", "Note:", "Notes:", "Example:", "Examples:" ) [ text ] "\n" freeform_comment text = free text with markup Note that the grammar is ambiguous: a line "# @foo:\n" can be parsed both as freeform_comment and as symbol_comment. The actual parser recognizes symbol_comment. See docs/qapi-code-gen.txt for more details. Deficiencies and limitations: - the generated QMP documentation includes internal types - union type support is lacking - type information is lacking in generated documentation - doc comment error message positions are imprecise, they point to the beginning of the comment. - a few minor issues, all marked TODO/FIXME in the code Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20170113144135.5150-16-marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [test-qapi.py tweaked to avoid trailing empty lines in .out] Signed-off-by: Markus Armbruster <armbru@redhat.com> 2017-01-13 17:41:29 +03:00
			`##`
			`# @oops:`
			`##`
qapi-tests: New tests for union, alternate command arguments A command's 'data' must be a struct type, given either as a dictionary, or as struct type name. Existing test case data-int.json covers simple type 'int'. Add test cases for type names referring to union and alternate types. The latter is caught (good), but the former is not (bug). Events have the same problem, but since they get checked by the same code, we don't bother to duplicate the tests. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> 2015-07-01 10:54:11 +03:00			`{ 'command': 'oops', 'data': 'Alt' }`