From patchwork Mon Oct 2 15:25:46 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 820580 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=gnu.org (client-ip=2001:4830:134:3::11; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@gnu.org; receiver=) Received: from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3y5RG02c5kz9t6m for ; Tue, 3 Oct 2017 02:40:56 +1100 (AEDT) Received: from localhost ([::1]:52880 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dz2py-0003Eq-90 for incoming@patchwork.ozlabs.org; Mon, 02 Oct 2017 11:40:54 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:38947) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dz2bj-00084G-0h for qemu-devel@nongnu.org; Mon, 02 Oct 2017 11:26:12 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dz2bf-00080z-20 for qemu-devel@nongnu.org; Mon, 02 Oct 2017 11:26:11 -0400 Received: from mx1.redhat.com ([209.132.183.28]:38356) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dz2be-0007zy-Pz for qemu-devel@nongnu.org; Mon, 02 Oct 2017 11:26:06 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id D476D820F6; Mon, 2 Oct 2017 15:26:05 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com D476D820F6 Authentication-Results: ext-mx02.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx02.extmail.prod.ext.phx2.redhat.com; spf=fail smtp.mailfrom=armbru@redhat.com Received: from blackfin.pond.sub.org (ovpn-116-91.ams2.redhat.com [10.36.116.91]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2A542841C1; Mon, 2 Oct 2017 15:26:02 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id CF54611562ED; Mon, 2 Oct 2017 17:25:52 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Date: Mon, 2 Oct 2017 17:25:46 +0200 Message-Id: <20171002152552.27999-27-armbru@redhat.com> In-Reply-To: <20171002152552.27999-1-armbru@redhat.com> References: <20171002152552.27999-1-armbru@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.26]); Mon, 02 Oct 2017 15:26:06 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [RFC PATCH 26/32] qapi2texi: Include command line options information X-BeenThere: qemu-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: marcandre.lureau@redhat.com, mdroth@linux.vnet.ibm.com Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@gnu.org Sender: "Qemu-devel" 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 --- 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 += '\n@b{Arguments:} 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 + + +@deftypefn Option {} --help + +Display help and exit. + +@end deftypefn + + + + +@deftypefn Option {} --opt-arg-str + +TODO support documenting simple option argument + +@end deftypefn + + + + +@deftypefn Option {} --opt-arg-struct + + + +@b{Arguments:} +@table @asis +@item @code{s: string} +a string +@item @code{i: int} (optional) +an integer +@end table + +@end deftypefn + + + + +@deftypefn Option {} --opt-arg-boxed + + + +@b{Arguments:} the members of @code{Base} +@end deftypefn + +