[{"id":1821490,"web_url":"http://patchwork.ozlabs.org/comment/1821490/","msgid":"<87fu8eerg3.fsf@dusky.pond.sub.org>","list_archive_url":null,"date":"2017-12-13T12:35:24","subject":"Re: [Qemu-devel] [PATCH v3 32/50] qapi2texi: add 'If:' section to\n\tgenerated documentation","submitter":{"id":2645,"url":"http://patchwork.ozlabs.org/api/people/2645/","name":"Markus Armbruster","email":"armbru@redhat.com"},"content":"Cc: Eric for an additional pair of eyeballs.\n\nMarc-André Lureau writes:\n\n> The documentation is generated only once, and doesn't know C\n> pre-conditions. Add 'If:' sections for top-level entities.\n\nIs this what we want?\n\nQMP also exists only once. Should the generated qemu-qmp-ref.* document\nthat instance of QMP, or should it document all potential instances of\nQMP?\n\n> Signed-off-by: Marc-André Lureau \n> ---\n> scripts/qapi2texi.py | 24 +++++++++++++-----------\n> 1 file changed, 13 insertions(+), 11 deletions(-)\n>\n> diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py\n> index e72e7cfe0b..150e7045d2 100755\n> --- a/scripts/qapi2texi.py\n> +++ b/scripts/qapi2texi.py\n> @@ -132,7 +132,6 @@ def texi_enum_value(value):\n> \"\"\"Format a table of members item for an enumeration value\"\"\"\n> return '@item @code{%s}\\n' % value.name\n> \n> -\n> def texi_member(member, suffix=''):\n> \"\"\"Format a table of members item for an object type member\"\"\"\n> typ = member.type.doc_type()\n\nSpurious whitespace change. PEP8 wants the original spacing here.\n\n> @@ -175,7 +174,7 @@ def texi_members(doc, what, base, variants, member_func):\n> return '\\n@b{%s:}\\n@table @asis\\n%s@end table\\n' % (what, items)\n> \n> \n> -def texi_sections(doc):\n> +def texi_sections(doc, ifcond):\n> \"\"\"Format additional sections following arguments\"\"\"\n> body = ''\n> for section in doc.sections:\n> @@ -189,14 +188,16 @@ def texi_sections(doc):\n> body += '\\n\\n@b{%s:}\\n' % name\n> \n> body += func(doc)\n> + if ifcond:\n> + body += '\\n\\n@b{If:} @code{%s}' % ifcond\n> return body\n> \n> \n> -def texi_entity(doc, what, base=None, variants=None,\n> +def texi_entity(doc, what, ifcond, base=None, variants=None,\n> member_func=texi_member):\n> return (texi_body(doc)\n> + texi_members(doc, what, base, variants, member_func)\n> - + texi_sections(doc))\n> + + texi_sections(doc, ifcond))\n> \n> \n> class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):\n> @@ -213,7 +214,7 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):\n> self.out += '\\n'\n> self.out += TYPE_FMT(type='Enum',\n> name=doc.symbol,\n> - body=texi_entity(doc, 'Values',\n> + body=texi_entity(doc, 'Values', ifcond,\n> member_func=texi_enum_value))\n> \n> def visit_object_type(self, name, info, ifcond, base, members, variants):\n> @@ -224,7 +225,8 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):\n> self.out += '\\n'\n> self.out += TYPE_FMT(type='Object',\n> name=doc.symbol,\n> - body=texi_entity(doc, 'Members', base, variants))\n> + body=texi_entity(doc, 'Members', ifcond,\n> + base, variants))\n> \n> def visit_alternate_type(self, name, info, ifcond, variants):\n> doc = self.cur_doc\n> @@ -232,7 +234,7 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):\n> self.out += '\\n'\n> self.out += TYPE_FMT(type='Alternate',\n> name=doc.symbol,\n> - body=texi_entity(doc, 'Members'))\n> + body=texi_entity(doc, 'Members', ifcond))\n> \n> def visit_command(self, name, info, ifcond, arg_type, ret_type,\n> gen, success_response, boxed):\n> @@ -242,9 +244,9 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):\n> if boxed:\n> body = texi_body(doc)\n> body += '\\n@b{Arguments:} the members of @code{%s}' % arg_type.name\n> - body += texi_sections(doc)\n> + body += texi_sections(doc, ifcond)\n> else:\n> - body = texi_entity(doc, 'Arguments')\n> + body = texi_entity(doc, 'Arguments', ifcond)\n> self.out += MSG_FMT(type='Command',\n> name=doc.symbol,\n> body=body)\n> @@ -255,7 +257,7 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):\n> self.out += '\\n'\n> self.out += MSG_FMT(type='Event',\n> name=doc.symbol,\n> - body=texi_entity(doc, 'Arguments'))\n> + body=texi_entity(doc, 'Arguments', ifcond))\n> \n> def symbol(self, doc, entity):\n> self.cur_doc = doc\n> @@ -266,7 +268,7 @@ class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):\n> assert not doc.args\n> if self.out:\n> self.out += '\\n'\n> - self.out += texi_body(doc) + texi_sections(doc)\n> + self.out += texi_body(doc) + texi_sections(doc, None)\n> \n> \n> def texi_schema(schema):\n\nMissing: coverage in tests/qapi-schema/doc-good.json.","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=pass (mailfrom) smtp.mailfrom=nongnu.org\n\t(client-ip=2001:4830:134:3::11; helo=lists.gnu.org;\n\tenvelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n\treceiver=)","Received":["from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11])\n\t(using TLSv1 with cipher AES256-SHA (256/256 bits))\n\t(No client certificate requested)\n\tby ozlabs.org (Postfix) with ESMTPS id 3yxblg5V2mz9s9Y\n\tfor ;\n\tWed, 13 Dec 2017 23:36:15 +1100 (AEDT)","from localhost ([::1]:35138 helo=lists.gnu.org)\n\tby lists.gnu.org with esmtp (Exim 4.71) (envelope-from\n\t)\n\tid 1eP6Gj-0000NK-Qx\n\tfor incoming@patchwork.ozlabs.org; Wed, 13 Dec 2017 07:36:13 -0500","from eggs.gnu.org ([2001:4830:134:3::10]:60824)\n\tby lists.gnu.org with esmtp (Exim 4.71)\n\t(envelope-from ) id 1eP6G9-0000Ln-Ft\n\tfor qemu-devel@nongnu.org; Wed, 13 Dec 2017 07:35:38 -0500","from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)\n\t(envelope-from ) id 1eP6G4-0002JV-Rs\n\tfor qemu-devel@nongnu.org; Wed, 13 Dec 2017 07:35:37 -0500","from mx1.redhat.com ([209.132.183.28]:35928)\n\tby eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32)\n\t(Exim 4.71) (envelope-from ) id 1eP6G4-0002J1-J1\n\tfor qemu-devel@nongnu.org; Wed, 13 Dec 2017 07:35:32 -0500","from smtp.corp.redhat.com\n\t(int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12])\n\t(using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits))\n\t(No client certificate requested)\n\tby mx1.redhat.com (Postfix) with ESMTPS id 89CE237E74;\n\tWed, 13 Dec 2017 12:35:31 +0000 (UTC)","from blackfin.pond.sub.org (ovpn-116-74.ams2.redhat.com\n\t[10.36.116.74])\n\tby smtp.corp.redhat.com (Postfix) with ESMTPS id B9A8577D54;\n\tWed, 13 Dec 2017 12:35:25 +0000 (UTC)","by blackfin.pond.sub.org (Postfix, from userid 1000)\n\tid 43AF71138658; Wed, 13 Dec 2017 13:35:24 +0100 (CET)"],"From":"Markus Armbruster ","To":"=?utf-8?q?Marc-Andr=C3=A9?= Lureau ","References":"<20170911110623.24981-1-marcandre.lureau@redhat.com>\n\t<20170911110623.24981-33-marcandre.lureau@redhat.com>","Date":"Wed, 13 Dec 2017 13:35:24 +0100","In-Reply-To":"<20170911110623.24981-33-marcandre.lureau@redhat.com> (\n\t=?utf-8?b?Ik1hcmMtQW5kcsOp?= Lureau\"'s message of \"Mon,\n\t11 Sep 2017 \t13:06:05 +0200\")","Message-ID":"<87fu8eerg3.fsf@dusky.pond.sub.org>","User-Agent":"Gnus/5.13 (Gnus v5.13) Emacs/25.3 (gnu/linux)","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Transfer-Encoding":"quoted-printable","X-Scanned-By":"MIMEDefang 2.79 on 10.5.11.12","X-Greylist":"Sender IP whitelisted, not delayed by milter-greylist-4.5.16\n\t(mx1.redhat.com [10.5.110.29]);\n\tWed, 13 Dec 2017 12:35:31 +0000 (UTC)","X-detected-operating-system":"by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic]\n\t[fuzzy]","X-Received-From":"209.132.183.28","Subject":"Re: [Qemu-devel] [PATCH v3 32/50] qapi2texi: add 'If:' section to\n\tgenerated documentation","X-BeenThere":"qemu-devel@nongnu.org","X-Mailman-Version":"2.1.21","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Cc":"qemu-devel@nongnu.org, Michael Roth ","Errors-To":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org","Sender":"\"Qemu-devel\"\n\t"}},{"id":1821804,"web_url":"http://patchwork.ozlabs.org/comment/1821804/","msgid":"","list_archive_url":null,"date":"2017-12-13T19:54:07","subject":"Re: [Qemu-devel] [PATCH v3 32/50] qapi2texi: add 'If:' section to\n\tgenerated documentation","submitter":{"id":6591,"url":"http://patchwork.ozlabs.org/api/people/6591/","name":"Eric Blake","email":"eblake@redhat.com"},"content":"On 12/13/2017 06:35 AM, Markus Armbruster wrote:\n> Cc: Eric for an additional pair of eyeballs.\n> \n> Marc-André Lureau writes:\n> \n>> The documentation is generated only once, and doesn't know C\n>> pre-conditions. Add 'If:' sections for top-level entities.\n> \n> Is this what we want?\n> \n> QMP also exists only once. Should the generated qemu-qmp-ref.* document\n> that instance of QMP, or should it document all potential instances of\n> QMP?\n> \n\nI can go either way; it's nice to know that the binary that this copy of\ndocumentation was bundled with only understands these terms (the binary\nwas compiled without HAVE_FOO, so any code guarded by HAVE_FOO doesn't\nneed to be documented); but that limits the usability of that\ndocumentation to just that binary. It's also useful to have\nfully-generic documentation hosted on the website, where everything is\ndocumented (the documentation describes all possible builds of qemu\n2.12, not just the one you installed), while mentioning the conditional\nnature of the documented feature (\"qemu in general knows about these\nthings; but check your particular binary by doing XYZ to learn if that\nsupport was compiled in to your binary\").\n\nSo having typed that, I think I'm leaning slightly towards documenting\neverything, including conditionals, rather than trimming the document to\nmatch the current build conditions.","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":"ozlabs.org;\n\tspf=pass (mailfrom) smtp.mailfrom=nongnu.org\n\t(client-ip=2001:4830:134:3::11; helo=lists.gnu.org;\n\tenvelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n\treceiver=)","Received":["from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11])\n\t(using TLSv1 with cipher AES256-SHA (256/256 bits))\n\t(No client certificate requested)\n\tby ozlabs.org (Postfix) with ESMTPS id 3yxnTk2ZTnz9s74\n\tfor ;\n\tThu, 14 Dec 2017 06:54:50 +1100 (AEDT)","from localhost ([::1]:37318 helo=lists.gnu.org)\n\tby lists.gnu.org with esmtp (Exim 4.71) (envelope-from\n\t)\n\tid 1ePD79-0001H7-F8\n\tfor incoming@patchwork.ozlabs.org; Wed, 13 Dec 2017 14:54:47 -0500","from eggs.gnu.org ([2001:4830:134:3::10]:56491)\n\tby lists.gnu.org with esmtp (Exim 4.71)\n\t(envelope-from ) id 1ePD6d-0001FN-Mj\n\tfor qemu-devel@nongnu.org; Wed, 13 Dec 2017 14:54:16 -0500","from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)\n\t(envelope-from ) id 1ePD6a-0001lP-If\n\tfor qemu-devel@nongnu.org; Wed, 13 Dec 2017 14:54:15 -0500","from mx1.redhat.com ([209.132.183.28]:57988)\n\tby eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32)\n\t(Exim 4.71) (envelope-from ) id 1ePD6a-0001ka-9f\n\tfor qemu-devel@nongnu.org; Wed, 13 Dec 2017 14:54:12 -0500","from smtp.corp.redhat.com\n\t(int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13])\n\t(using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits))\n\t(No client certificate requested)\n\tby mx1.redhat.com (Postfix) with ESMTPS id 3D6D4C047B67;\n\tWed, 13 Dec 2017 19:54:11 +0000 (UTC)","from [10.10.120.204] (ovpn-120-204.rdu2.redhat.com [10.10.120.204])\n\tby smtp.corp.redhat.com (Postfix) with ESMTP id 8EE197D908;\n\tWed, 13 Dec 2017 19:54:08 +0000 (UTC)"],"To":"Markus Armbruster , =?utf-8?q?Marc-Andr=C3=A9_Lurea?=\n\t=?utf-8?q?u?= ","References":"<20170911110623.24981-1-marcandre.lureau@redhat.com>\n\t<20170911110623.24981-33-marcandre.lureau@redhat.com>\n\t<87fu8eerg3.fsf@dusky.pond.sub.org>","From":"Eric Blake ","Openpgp":"url=http://people.redhat.com/eblake/eblake.gpg","Organization":"Red Hat, Inc.","Message-ID":"","Date":"Wed, 13 Dec 2017 13:54:07 -0600","User-Agent":"Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101\n\tThunderbird/52.5.0","MIME-Version":"1.0","In-Reply-To":"<87fu8eerg3.fsf@dusky.pond.sub.org>","Content-Type":"multipart/signed; micalg=pgp-sha256;\n\tprotocol=\"application/pgp-signature\";\n\tboundary=\"N53aoMJxvxH3XMt1ro0frP6XFx0AQrFNc\"","X-Scanned-By":"MIMEDefang 2.79 on 10.5.11.13","X-Greylist":"Sender IP whitelisted, not delayed by milter-greylist-4.5.16\n\t(mx1.redhat.com [10.5.110.31]);\n\tWed, 13 Dec 2017 19:54:11 +0000 (UTC)","X-detected-operating-system":"by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic]\n\t[fuzzy]","X-Received-From":"209.132.183.28","X-Content-Filtered-By":"Mailman/MimeDel 2.1.21","Subject":"Re: [Qemu-devel] [PATCH v3 32/50] qapi2texi: add 'If:' section to\n\tgenerated documentation","X-BeenThere":"qemu-devel@nongnu.org","X-Mailman-Version":"2.1.21","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Cc":"qemu-devel@nongnu.org, Michael Roth ","Errors-To":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org","Sender":"\"Qemu-devel\"\n\t"}}]