[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v8 15/21] qapi: add qapi2texi script
From: |
Markus Armbruster |
Subject: |
Re: [Qemu-devel] [PATCH v8 15/21] qapi: add qapi2texi script |
Date: |
Mon, 16 Jan 2017 10:37:12 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux) |
Marc-André Lureau <address@hidden> writes:
> 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 <address@hidden>
Squashing in the appended patch along with updates to expected output to
avoid git complaining about trailing blank lines like this:
tests/qapi-schema/comments.out:7: new blank line at EOF.
tests/qapi-schema/event-case.out:8: new blank line at EOF.
tests/qapi-schema/ident-with-escape.out:10: new blank line at EOF.
tests/qapi-schema/include-relpath.out:7: new blank line at EOF.
tests/qapi-schema/include-repetition.out:7: new blank line at EOF.
tests/qapi-schema/include-simple.out:7: new blank line at EOF.
tests/qapi-schema/indented-expr.out:13: new blank line at EOF.
tests/qapi-schema/qapi-schema-test.out:446: new blank line at EOF.
diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py
index 39b55b9..b4cde4f 100644
--- a/tests/qapi-schema/test-qapi.py
+++ b/tests/qapi-schema/test-qapi.py
@@ -66,4 +66,6 @@ for doc in schema.docs:
print ' arg=%s\n%s' % (arg, section)
for section in doc.sections:
print ' section=%s\n%s' % (section.name, section)
- print ' body=\n%s' % doc.body
+ body = str(doc.body)
+ if body:
+ print ' body=\n%s' % body
- Re: [Qemu-devel] [PATCH v8 12/21] qapi.py: fix line break before binary operator pep8, (continued)
- [Qemu-devel] [PATCH v8 11/21] qapi: rework qapi Exception, Marc-André Lureau, 2017/01/13
- [Qemu-devel] [PATCH v8 13/21] texi2pod: learn quotation, deftp and deftypefn, Marc-André Lureau, 2017/01/13
- [Qemu-devel] [PATCH v8 17/21] build-sys: use --no-split for info, Marc-André Lureau, 2017/01/13
- [Qemu-devel] [PATCH v8 16/21] docs: add qemu logo to pdf, Marc-André Lureau, 2017/01/13
- [Qemu-devel] [PATCH v8 18/21] build-sys: remove dvi doc generation, Marc-André Lureau, 2017/01/13
- [Qemu-devel] [PATCH v8 19/21] build-sys: use a generic TEXI2MAN rule, Marc-André Lureau, 2017/01/13
- [Qemu-devel] [PATCH v8 20/21] build-sys: add txt documentation rules, Marc-André Lureau, 2017/01/13
- [Qemu-devel] [PATCH v8 21/21] build-sys: add qapi doc generation targets, Marc-André Lureau, 2017/01/13
- [Qemu-devel] [PATCH v8 15/21] qapi: add qapi2texi script, Marc-André Lureau, 2017/01/13
- Re: [Qemu-devel] [PATCH v8 15/21] qapi: add qapi2texi script,
Markus Armbruster <=
- [Qemu-devel] [PATCH v8 14/21] (SQUASHED) move doc to schema, Marc-André Lureau, 2017/01/13