Features will be documented in a new part introduced by a "Features:"
line, after arguments and before named sections.
Signed-off-by: Kevin Wolf <kw...@redhat.com>
---
scripts/qapi/common.py | 42 ++++++++++++++++++++++++++++++++++++++----
scripts/qapi/doc.py | 12 ++++++++++++
2 files changed, 50 insertions(+), 4 deletions(-)
diff --git a/scripts/qapi/common.py b/scripts/qapi/common.py
index 55ccd216cf..bc09e7d358 100644
--- a/scripts/qapi/common.py
+++ b/scripts/qapi/common.py
@@ -127,6 +127,7 @@ class QAPIDoc(object):
optional overview
* an ARGS part: description of each argument (for commands and
events) or member (for structs, unions and alternates),
+ * a FEATURES part: description of each feature,
* a VARIOUS part: optional tagged sections.
Free-form documentation blocks consist only of a BODY part.
@@ -134,7 +135,8 @@ class QAPIDoc(object):
# TODO Make it a subclass of Enum when Python 2 support is removed
BODY = 1
ARGS = 2
- VARIOUS = 3
+ FEATURES = 3
+ VARIOUS = 4
def __init__(self, parser, info):
# self._parser is used to report errors with QAPIParseError. The
@@ -147,6 +149,7 @@ class QAPIDoc(object):
self.body = QAPIDoc.Section()
# dict mapping parameter name to ArgSection
self.args = OrderedDict()
+ self.features = OrderedDict()
# a list of Section
self.sections = []
# the current section
@@ -192,6 +195,8 @@ class QAPIDoc(object):
self._append_body_line(line)
elif self._part == QAPIDoc.DocPart.ARGS:
self._append_args_line(line)
+ elif self._part == QAPIDoc.DocPart.FEATURES:
+ self._append_features_line(line)
elif self._part == QAPIDoc.DocPart.VARIOUS:
self._append_various_line(line)
else:
@@ -226,6 +231,8 @@ class QAPIDoc(object):
if name.startswith('@') and name.endswith(':'):
self._part = QAPIDoc.DocPart.ARGS
self._append_args_line(line)
+ elif line == 'Features:':
+ self._part = QAPIDoc.DocPart.FEATURES
elif self.symbol and self._check_named_section(name):
self._append_various_line(line)
else:
@@ -243,6 +250,27 @@ class QAPIDoc(object):
elif self._check_named_section(name):
self._append_various_line(line)
return
+ elif (self._section.text.endswith('\n\n')
+ and line and not line[0].isspace()):
+ if line == 'Features:':
+ self._part = QAPIDoc.DocPart.FEATURES
+ else:
+ self._start_section()
+ self._part = QAPIDoc.DocPart.VARIOUS
+ self._append_various_line(line)
+ return
+
+ self._append_freeform(line.strip())
+
+ def _append_features_line(self, line):
+ name = line.split(' ', 1)[0]
+
+ if name.startswith('@') and name.endswith(':'):
+ line = line[len(name)+1:]
+ self._start_features_section(name[1:-1])
+ elif self._check_named_section(name):
+ self._append_various_line(line)
+ return
elif (self._section.text.endswith('\n\n')
and line and not line[0].isspace()):
self._start_section()
@@ -269,17 +297,23 @@ class QAPIDoc(object):
self._append_freeform(line)
- def _start_args_section(self, name):
+ def _start_symbol_section(self, symbols_dict, name):
# FIXME invalid names other than the empty string aren't flagged
if not name:
raise QAPIParseError(self._parser, "Invalid parameter name")
- if name in self.args:
+ if name in symbols_dict:
raise QAPIParseError(self._parser,
"'%s' parameter name duplicated" % name)
assert not self.sections
self._end_section()
self._section = QAPIDoc.ArgSection(name)
- self.args[name] = self._section
+ symbols_dict[name] = self._section
+
+ def _start_args_section(self, name):
+ self._start_symbol_section(self.args, name)
+
+ def _start_features_section(self, name):
+ self._start_symbol_section(self.features, name)
def _start_section(self, name=None):
if name in ('Returns', 'Since') and self.has_section(name):
diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py
index 433e9fcbfb..5fc0fc7e06 100755
--- a/scripts/qapi/doc.py
+++ b/scripts/qapi/doc.py
@@ -182,6 +182,17 @@ def texi_members(doc, what, base, variants, member_func):
return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items)
+def texi_features(doc):
+ """Format the table of features"""
+ items = ''
+ for section in doc.features.values():
+ desc = texi_format(section.text)
+ items += '@item @code{%s}\n%s' % (section.name, desc)
+ if not items:
+ return ''
+ return '\n@b{Features:}\n@table @asis\n%s@end table\n' % (items)
+
+
def texi_sections(doc, ifcond):
"""Format additional sections following arguments"""
body = ''
@@ -201,6 +212,7 @@ def texi_entity(doc, what, ifcond, base=None, variants=None,
member_func=texi_member):
return (texi_body(doc)
+ texi_members(doc, what, base, variants, member_func)
+ + texi_features(doc)
+ texi_sections(doc, ifcond))
--
2.20.1
