[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH v2 for-2.9 15/47] qapi: Conjure up QAPIDoc.ArgSectio
From: |
Markus Armbruster |
Subject: |
[Qemu-devel] [PATCH v2 for-2.9 15/47] qapi: Conjure up QAPIDoc.ArgSection for undocumented members |
Date: |
Wed, 15 Mar 2017 13:57:04 +0100 |
qapi2texi.py already conjures up ArgSections for undocumented
enumeration values, in texi_enum. Drop that, and conjure them up for
all kinds of "arguments" (enumeration values, object and alternate
type members) in qapi.py instead.
Take care to keep generated documentation exactly the same for now.
Signed-off-by: Markus Armbruster <address@hidden>
Reviewed-by: Eric Blake <address@hidden>
---
scripts/qapi.py | 5 ++---
scripts/qapi2texi.py | 31 ++++++++++++++++---------------
2 files changed, 18 insertions(+), 18 deletions(-)
diff --git a/scripts/qapi.py b/scripts/qapi.py
index c1e0bed..f4c8eac 100644
--- a/scripts/qapi.py
+++ b/scripts/qapi.py
@@ -224,9 +224,8 @@ class QAPIDoc(object):
def connect_member(self, member):
if member.name not in self.args:
# Undocumented TODO outlaw
- pass
- else:
- self.args[member.name].connect(member)
+ self.args[member.name] = QAPIDoc.ArgSection(member.name)
+ self.args[member.name].connect(member)
class QAPISchemaParser(object):
diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py
index 0aaf45c..299dcf9 100755
--- a/scripts/qapi2texi.py
+++ b/scripts/qapi2texi.py
@@ -123,7 +123,7 @@ def texi_format(doc):
return "\n".join(lines)
-def texi_body(doc):
+def texi_body(doc, only_documented=False):
"""
Format the body of a symbol documentation:
- main body
@@ -131,17 +131,21 @@ def texi_body(doc):
- followed by "Returns/Notes/Since/Example" sections
"""
body = texi_format(str(doc.body)) + "\n"
- if doc.args:
+
+ args = ''
+ for name, section in doc.args.iteritems():
+ if not section.content and not only_documented:
+ continue # Undocumented TODO require doc and drop
+ desc = str(section)
+ opt = ''
+ if section.optional:
+ desc = re.sub(r'^ *#optional *\n?|\n? *#optional *$|#optional',
+ '', desc)
+ opt = ' (optional)'
+ args += "@item @code{'%s'}%s\n%s\n" % (name, opt, texi_format(desc))
+ if args:
body += "@table @asis\n"
- for arg, section in doc.args.iteritems():
- desc = str(section)
- opt = ''
- if section.optional:
- desc = re.sub(r'^ *#optional *\n?|\n? *#optional *$|#optional',
- '', desc)
- opt = ' (optional)'
- body += "@item @code{'%s'}%s\n%s\n" % (arg, opt,
- texi_format(desc))
+ body += args
body += "@end table\n"
for section in doc.sections:
@@ -183,10 +187,7 @@ def texi_union(expr, doc):
def texi_enum(expr, doc):
"""Format an enum to texi"""
- for i in expr['data']:
- if i not in doc.args:
- doc.args[i] = qapi.QAPIDoc.ArgSection(i)
- body = texi_body(doc)
+ body = texi_body(doc, True)
return TYPE_FMT(type="Enum",
name=doc.symbol,
body=body)
--
2.7.4
- [Qemu-devel] [PATCH v2 for-2.9 00/47] qapi: Put type information back into QMP documentation, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 01/47] qapi: Factor QAPISchemaParser._include() out of .__init__(), Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 10/47] qapi2texi: Fix up output around #optional, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 08/47] tests/qapi-schema: Cover empty union base, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 09/47] qapi: Fix to reject empty union base gracefully, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 13/47] qapi: Fix QAPISchemaEnumType.is_implicit() for 'QType', Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 06/47] qapi: Have each QAPI schema declare its name rule violations, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 04/47] docs/qapi-code-gen.txt: Drop confusing reference to 'gen', Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 12/47] qapi/rocker: Fix up doc comment notes on optional members, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 23/47] qapi2texi: Don't hide undocumented members and arguments, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 15/47] qapi: Conjure up QAPIDoc.ArgSection for undocumented members,
Markus Armbruster <=
- [Qemu-devel] [PATCH v2 for-2.9 16/47] qapi2texi: Convert to QAPISchemaVisitor, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 32/47] qapi: Move detection of doc / expression name mismatch, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 22/47] qapi2texi: Explain enum value undocumentedness more clearly, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 34/47] qapi: Move empty doc section checking to doc parser, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 14/47] qapi: Prepare for requiring more complete documentation, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 42/47] qapi: enum_types is a list used like a dict, make it one, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 07/47] qapi: Clean up build of generated documentation, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 20/47] qapi2texi: Plainer enum value and member name formatting, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 11/47] qapi: Avoid unwanted blank lines in QAPIDoc, Markus Armbruster, 2017/03/15
- [Qemu-devel] [PATCH v2 for-2.9 02/47] qapi: Make doc comments optional where we don't need them, Markus Armbruster, 2017/03/15