From nobody Tue Feb 10 16:22:43 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@gnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@gnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1506958933570539.574918533134; Mon, 2 Oct 2017 08:42:13 -0700 (PDT) Received: from localhost ([::1]:52888 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dz2r4-0004Pz-0k for importer@patchew.org; Mon, 02 Oct 2017 11:42:02 -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) 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) 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 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+importer=patchew.org@gnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" 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=3Ddoc.symbol, body=3Dtexi_entity(doc, 'Arguments')) =20 + def visit_option(self, name, info, arg_type, short, implied_key, + boxed, help): + doc =3D self.cur_doc + if self.out: + self.out +=3D '\n' + if boxed: + body =3D texi_body(doc) + body +=3D '\n@b{Arguments:} the members of @code{%s}' % arg_ty= pe.name + body +=3D texi_sections(doc) + else: + body =3D texi_entity(doc, 'Arguments') + self.out +=3D MSG_FMT(type=3D'Option', + name=3Ddoc.symbol, + body=3Dbody) + def symbol(self, doc, entity): if self.out: self.out +=3D '\n' diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.j= son 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' } , 'hel= p': null } + +## +# @--opt-arg-boxed: +## +{ 'option': '--opt-arg-boxed', 'data': 'Base', 'boxed': true , 'help': nul= l } 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=3Dh + boxed=3DFalse + help=3D + +option --opt-arg-boxed Base + boxed=3DTrue + help=3D + +option --opt-arg-str str + boxed=3DFalse + help=3D + +option --opt-arg-struct q_obj_opt-arg-struct-optarg + boxed=3DFalse + help=3D + object Base member base1: Enum optional=3DFalse enum Enum ['one', 'two'] @@ -6,6 +23,15 @@ object Object tag base1 case one: Variant1 case two: Variant2 +object QAPIOption + member type: QAPIOptionKind optional=3DFalse + member idx: int32 optional=3DFalse + member cnt: int32 optional=3DFalse + 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-stru= ct'] object SugaredUnion member type: SugaredUnionKind optional=3DFalse tag type @@ -27,6 +53,9 @@ object q_obj_cmd-arg member arg1: int optional=3DFalse member arg2: str optional=3DTrue member arg3: bool optional=3DFalse +object q_obj_opt-arg-struct-optarg + member s: str optional=3DFalse + member i: int optional=3DTrue doc freeform body=3D =3D Section @@ -161,3 +190,19 @@ If you're bored enough to read this, go see a video of= boxed cats -> in =20 <- out +doc symbol=3D--help + body=3D +Display help and exit. +doc symbol=3D--opt-arg-str + body=3D +TODO support documenting simple option argument +doc symbol=3D--opt-arg-struct + body=3D + + arg=3Ds +a string + arg=3Di +an integer +doc symbol=3D--opt-arg-boxed + body=3D + diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.t= exi 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 =20 =20 + + +@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 + + --=20 2.13.6