summaryrefslogtreecommitdiffstats
path: root/tests/qapi-schema/alternate-empty.json
Commit message (Collapse)AuthorAgeFilesLines
* qapi: Back out doc comments added just to please qapi.pyMarkus Armbruster2017-03-161-4/+0Star
| | | | | | | | | | | | | | | This reverts commit 3313b61's changes to tests/qapi-schema/, except for tests/qapi-schema/doc-*. We could keep some of these doc comments to serve as positive test cases. However, they don't actually add to what we get from doc comment use in actual schemas, as we we don't test output matches expectations, and don't systematically cover doc comment features. Proper positive test coverage would be nice. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-4-git-send-email-armbru@redhat.com>
* qapi: add qapi2texi scriptMarc-André Lureau2017-01-161-0/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* qapi: Forbid empty unions and useless alternatesEric Blake2016-02-191-1/+1
| | | | | | | | | | | | | | | | | | | | | | Empty unions serve no purpose, and while we compile with gcc which permits them, strict C99 forbids them. We happen to inject a dummy 'void *data' member into the C unions that represent QAPI unions and alternates, but we want to get rid of that member (it pollutes the namespace for no good reason), which would leave us with an empty union if the user didn't provide any branches. While empty structs make sense in QAPI, empty unions don't add any expressiveness to the QMP language. So prohibit them at parse time. Update the documentation and testsuite to match. Note that the documentation already mentioned that alternates should have "two or more JSON data types"; so this also fixes the code to enforce that. However, we have existing uses of a union type with only one branch, so the 2-or-more strictness is intentionally limited to alternates. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1455778109-6278-3-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Add tests for empty unionsEric Blake2015-10-121-0/+2
The documentation claims that alternates are useful for allowing two or more types, although nothing enforces this. Meanwhile, it is silent on whether empty unions are allowed. In practice, the generated code will compile, in part because we have a 'void *data' branch; but attempting to visit such a type will cause an abort(). While there's no technical reason that a degenerate union could not be made to work, it's harder to justify the time spent in chasing known (the current abort() during visit) and unknown corner cases, than it would be to just outlaw them. A future patch will probably take the approach of forbidding them; in the meantime, we can at least add testsuite coverage to make it obvious where things stand. In addition to adding tests to expose the problems, we also need to adjust existing tests that are meant to test something else, but which could fail for the wrong reason if we reject degenerate alternates/unions. Note that empty structs are explicitly supported (for example, right now they are the only way to specify that one branch of a flat union adds no additional members), and empty enums are covered by the testsuite as working (even if they do not seem to have much use). Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1443565276-4535-8-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>