qemu-e2k/scripts
Marc-André Lureau 3313b6124b 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-16 10:10:35 +01:00
..
coccinelle
kvm
modules
qemu-guest-agent
qemugdb
qmp
tracetool trace: Fix 'char **' compilation error in simple backend 2016-10-27 19:24:15 +01:00
analyse-9p-simpletrace.py
analyze-inclusions Move target-* CPU file into a target/ folder 2016-12-20 21:52:12 +01:00
analyze-migration.py
check-qerror.sh
checkpatch.pl checkpatch: allow spaces before parenthesis for 'coroutine_fn' 2016-11-02 09:28:56 +01:00
clean-header-guards.pl
clean-includes scripts/clean-includes: added duplicate #include check 2016-10-28 18:17:23 +03:00
cleanup-trace-events.pl
cocci-macro-file.h
coverity-model.c
create_config
disas-objdump.pl
dump-guest-memory.py
extract-vsssdk-headers
feature_to_c.sh
get_maintainer.pl
gtester-cat
hxtool scripts/hxtool: fix undefined behavour of echo 2016-10-28 18:17:23 +03:00
make_device_config.sh
make-release
ordereddict.py
qapi2texi.py qapi: add qapi2texi script 2017-01-16 10:10:35 +01:00
qapi-commands.py qapi: rename QmpOutputVisitor to QObjectOutputVisitor 2016-10-25 16:25:54 +02:00
qapi-event.py qapi: rename QmpOutputVisitor to QObjectOutputVisitor 2016-10-25 16:25:54 +02:00
qapi-introspect.py
qapi-types.py
qapi-visit.py
qapi.py qapi: add qapi2texi script 2017-01-16 10:10:35 +01:00
qemu-binfmt-conf.sh
qemu-gdb.py
qemu.py
qtest.py
refresh-pxe-roms.sh
shaderinclude.pl
show-fixed-bugs.sh
signrom.py
simpletrace.py trace: rename _read_events to read_events 2016-10-12 09:54:52 +02:00
switch-timer-api
texi2pod.pl texi2pod: learn quotation, deftp and deftypefn 2017-01-16 09:15:25 +01:00
tracetool.py trace: fix generated code build break 2016-11-18 11:09:58 +00:00
update-linux-headers.sh
vmstate-static-checker.py