History log of /qemu/tests/qapi-schema/doc-invalid-section.out (Results 1 – 1 of 1)
Revision (<<< Hide revision tags) (Show revision tags >>>) Date Author Comments
Revision tags: v7.0.0, v7.0.0-rc4, v7.0.0-rc3, v7.0.0-rc2, v7.0.0-rc1, v7.0.0-rc0, v6.1.1, v6.2.0, v6.2.0-rc4, v6.2.0-rc3, v6.2.0-rc2, v6.2.0-rc1, v6.2.0-rc0, v6.0.1, v6.1.0, v6.1.0-rc4, v6.1.0-rc3, v6.1.0-rc2, v6.1.0-rc1, v6.1.0-rc0, v6.0.0, v6.0.0-rc5, v6.0.0-rc4, v6.0.0-rc3, v6.0.0-rc2, v6.0.0-rc1, v6.0.0-rc0, v5.2.0, v5.2.0-rc4, v5.2.0-rc3, v5.2.0-rc2, v5.2.0-rc1, v5.2.0-rc0, v5.0.1, v5.1.0, v5.1.0-rc3, v5.1.0-rc2, v5.1.0-rc1, v5.1.0-rc0, v4.2.1, v5.0.0, v5.0.0-rc4, v5.0.0-rc3, v5.0.0-rc2, v5.0.0-rc1, v5.0.0-rc0, v4.2.0, v4.2.0-rc5, v4.2.0-rc4, v4.2.0-rc3, v4.2.0-rc2, v4.1.1, v4.2.0-rc1, v4.2.0-rc0, v4.0.1, v3.1.1.1, v4.1.0, v4.1.0-rc5, v4.1.0-rc4, v3.1.1, v4.1.0-rc3, v4.1.0-rc2, v4.1.0-rc1, v4.1.0-rc0, v4.0.0, v4.0.0-rc4, v3.0.1, v4.0.0-rc3, v4.0.0-rc2, v4.0.0-rc1, v4.0.0-rc0, v3.1.0, v3.1.0-rc5, v3.1.0-rc4, v3.1.0-rc3, v3.1.0-rc2, v3.1.0-rc1, v3.1.0-rc0, v3.0.0, v3.0.0-rc4, v2.12.1, v3.0.0-rc3, v3.0.0-rc2, v3.0.0-rc1, v3.0.0-rc0, v2.11.2, v2.12.0, v2.12.0-rc4, v2.12.0-rc3, v2.12.0-rc2, v2.12.0-rc1, v2.12.0-rc0, v2.11.1, v2.10.2, v2.11.0, v2.11.0-rc5, v2.11.0-rc4, v2.11.0-rc3, v2.11.0-rc2, v2.11.0-rc1, v2.11.0-rc0, v2.10.1, v2.9.1, v2.10.0, v2.10.0-rc4, v2.10.0-rc3, v2.10.0-rc2, v2.10.0-rc1, v2.10.0-rc0, v2.8.1.1, v2.9.0, v2.9.0-rc5, v2.9.0-rc4, v2.9.0-rc3, v2.8.1, v2.9.0-rc2, v2.9.0-rc1, v2.9.0-rc0
# 3313b612 13-Jan-2017 Marc-André Lureau <marcandre.lureau@redhat.com>

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

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>

show more ...