mirror of
https://github.com/Motorhead1991/qemu.git
synced 2026-03-03 00:24:37 -07: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.promela | ||
| aio_notify_accept.promela | ||
| aio_notify_bug.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 | ||
| usb-storage.txt | ||
| usb2.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 | ||