[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [RFC PATCH 26/32] qapi2texi: Include command line options i
From: |
Markus Armbruster |
Subject: |
[Qemu-devel] [RFC PATCH 26/32] qapi2texi: Include command line options information |
Date: |
Mon, 2 Oct 2017 17:25:46 +0200 |
Make generated QEMU QMP reference cover command line options in
addition to QMP commands and events. Simple, but pushes the QMP
reference beyond QMP. Perhaps options documentation should be
separate. Perhaps not for the same reason QMP and command line are
defined in the same schema: they share many types.
Signed-off-by: Markus Armbruster <address@hidden>
---
scripts/qapi2texi.py | 15 ++++++++++++++
tests/qapi-schema/doc-good.json | 24 ++++++++++++++++++++++
tests/qapi-schema/doc-good.out | 45 +++++++++++++++++++++++++++++++++++++++++
tests/qapi-schema/doc-good.texi | 45 +++++++++++++++++++++++++++++++++++++++++
4 files changed, 129 insertions(+)
diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py
index 0e099ebaa2..c638b82631 100755
--- a/scripts/qapi2texi.py
+++ b/scripts/qapi2texi.py
@@ -253,6 +253,21 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):
name=doc.symbol,
body=texi_entity(doc, 'Arguments'))
+ def visit_option(self, name, info, arg_type, short, implied_key,
+ boxed, help):
+ doc = self.cur_doc
+ if self.out:
+ self.out += '\n'
+ if boxed:
+ body = texi_body(doc)
+ body += 'address@hidden:} the members of @code{%s}' % arg_type.name
+ body += texi_sections(doc)
+ else:
+ body = texi_entity(doc, 'Arguments')
+ self.out += MSG_FMT(type='Option',
+ name=doc.symbol,
+ body=body)
+
def symbol(self, doc, entity):
if self.out:
self.out += '\n'
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index d3ddf828ef..eba8acd50d 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -151,3 +151,27 @@
##
{ 'command': 'cmd-boxed', 'boxed': true,
'data': 'Object' }
+
+##
+# @--help:
+# Display help and exit.
+##
+{ 'option': '--help', 'short': 'h' , 'help': null }
+
+##
+# @--opt-arg-str:
+# TODO support documenting simple option argument
+##
+{ 'option': '--opt-arg-str', 'data': 'str' , 'help': null }
+
+##
+# @--opt-arg-struct:
+# @s: a string
+# @i: an integer
+##
+{ 'option': '--opt-arg-struct', 'data': { 's': 'str', '*i': 'int' } , 'help':
null }
+
+##
+# @--opt-arg-boxed:
+##
+{ 'option': '--opt-arg-boxed', 'data': 'Base', 'boxed': true , 'help': null }
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index f609c5d5f5..bb4ffa0918 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -1,3 +1,20 @@
+option --help None
+ short=h
+ boxed=False
+ help=
+
+option --opt-arg-boxed Base
+ boxed=True
+ help=
+
+option --opt-arg-str str
+ boxed=False
+ help=
+
+option --opt-arg-struct q_obj_opt-arg-struct-optarg
+ boxed=False
+ help=
+
object Base
member base1: Enum optional=False
enum Enum ['one', 'two']
@@ -6,6 +23,15 @@ object Object
tag base1
case one: Variant1
case two: Variant2
+object QAPIOption
+ member type: QAPIOptionKind optional=False
+ member idx: int32 optional=False
+ member cnt: int32 optional=False
+ tag type
+ case opt-arg-boxed: Base
+ case opt-arg-str: q_obj_str-wrapper
+ case opt-arg-struct: q_obj_opt-arg-struct-optarg
+enum QAPIOptionKind ['help', 'opt-arg-boxed', 'opt-arg-str', 'opt-arg-struct']
object SugaredUnion
member type: SugaredUnionKind optional=False
tag type
@@ -27,6 +53,9 @@ object q_obj_cmd-arg
member arg1: int optional=False
member arg2: str optional=True
member arg3: bool optional=False
+object q_obj_opt-arg-struct-optarg
+ member s: str optional=False
+ member i: int optional=True
doc freeform
body=
= Section
@@ -161,3 +190,19 @@ If you're bored enough to read this, go see a video of
boxed cats
-> in
<- out
+doc symbol=--help
+ body=
+Display help and exit.
+doc symbol=--opt-arg-str
+ body=
+TODO support documenting simple option argument
+doc symbol=--opt-arg-struct
+ body=
+
+ arg=s
+a string
+ arg=i
+an integer
+doc symbol=--opt-arg-boxed
+ body=
+
diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi
index 4a9162c2a2..fd46358008 100644
--- a/tests/qapi-schema/doc-good.texi
+++ b/tests/qapi-schema/doc-good.texi
@@ -241,3 +241,48 @@ If you're bored enough to read this, go see a video of
boxed cats
@end deftypefn
+
+
address@hidden Option {} --help
+
+Display help and exit.
+
address@hidden deftypefn
+
+
+
+
address@hidden Option {} --opt-arg-str
+
+TODO support documenting simple option argument
+
address@hidden deftypefn
+
+
+
+
address@hidden Option {} --opt-arg-struct
+
+
+
address@hidden:}
address@hidden @asis
address@hidden @code{s: string}
+a string
address@hidden @code{i: int} (optional)
+an integer
address@hidden table
+
address@hidden deftypefn
+
+
+
+
address@hidden Option {} --opt-arg-boxed
+
+
+
address@hidden:} the members of @code{Base}
address@hidden deftypefn
+
+
--
2.13.6
- Re: [Qemu-devel] [RFC PATCH 17/32] qapi: Fix simple union lowering with multiple schemas, (continued)
- [Qemu-devel] [RFC PATCH 15/32] tests/qapi-schema: Improve simple union coverage, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 11/32] qapi: Drop the options to generate only .c or .h, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 07/32] qapi: Drop superfluous allow_optional=True, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 03/32] qapi2texi: Fix for examples containing '@', Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 26/32] qapi2texi: Include command line options information,
Markus Armbruster <=
- [Qemu-devel] [RFC PATCH 27/32] os-posix: Drop misleading comment, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 14/32] qapi: Rework generated code for built-in types, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 28/32] vl: QAPIfy command line option definition, Markus Armbruster, 2017/10/02