mirror of
https://github.com/xemu-project/xemu.git
synced 2024-11-24 03:59:52 +00:00
3313b6124b
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> |
||
---|---|---|
.. | ||
specs | ||
aio_notify_accept.promela | ||
aio_notify_bug.promela | ||
aio_notify.promela | ||
atomics.txt | ||
bitmaps.md | ||
blkdebug.txt | ||
blkverify.txt | ||
block-replication.txt | ||
bootindex.txt | ||
build-system.txt | ||
ccid.txt | ||
COLO-FT.txt | ||
colo-proxy.txt | ||
generic-loader.txt | ||
ich9-ehci-uhci.cfg | ||
igd-assign.txt | ||
image-fuzzer.txt | ||
live-block-ops.txt | ||
memory-hotplug.txt | ||
memory.txt | ||
migration.txt | ||
multi-thread-compression.txt | ||
multiple-iothreads.txt | ||
multiseat.txt | ||
pci_expander_bridge.txt | ||
pcie.txt | ||
q35-chipset.cfg | ||
qapi-code-gen.txt | ||
qcow2-cache.txt | ||
qdev-device-use.txt | ||
qemu-ga-ref.texi | ||
qemu-qmp-ref.texi | ||
qemupciserial.inf | ||
qmp-intro.txt | ||
qmp-spec.txt | ||
rcu.txt | ||
rdma.txt | ||
replay.txt | ||
spice-port-fqdn.txt | ||
tcg-exclusive.promela | ||
throttle.txt | ||
tracing.txt | ||
usb2.txt | ||
usb-storage.txt | ||
virtio-balloon-stats.txt | ||
virtio-migration.txt | ||
vnc-ledstate-Pseudo-encoding.txt | ||
win32-qemu-event.promela | ||
writing-qmp-commands.txt | ||
xbzrle.txt | ||
xen-save-devices-state.txt |