@@ -52,8 +52,8 @@ class QAPISchemaParser:
info = self.info
if self.tok == '#':
self.reject_expr_doc(cur_doc)
- cur_doc = self.get_doc(info)
- self.docs.append(cur_doc)
+ for cur_doc in self.get_doc(info):
+ self.docs.append(cur_doc)
continue
expr = self.get_expr(False)
@@ -270,7 +270,8 @@ class QAPISchemaParser:
raise QAPIParseError(
self, "junk after '##' at start of documentation comment")
- doc = QAPIDoc(self, info)
+ docs = []
+ cur_doc = QAPIDoc(self, info)
self.accept(False)
while self.tok == '#':
if self.val.startswith('##'):
@@ -279,15 +280,20 @@ class QAPISchemaParser:
raise QAPIParseError(
self,
"junk after '##' at end of documentation comment")
- doc.end_comment()
+ cur_doc.end_comment()
+ docs.append(cur_doc)
self.accept()
- return doc
+ return docs
if self.val.startswith('# ='):
- if doc.symbol:
+ if cur_doc.symbol:
raise QAPIParseError(
self,
"unexpected '=' markup in definition documentation")
- doc.append(self.val)
+ if cur_doc.body.text:
+ cur_doc.end_comment()
+ docs.append(cur_doc)
+ cur_doc = QAPIDoc(self, info)
+ cur_doc.append(self.val)
self.accept(False)
raise QAPIParseError(self, "documentation comment must end with '##'")
@@ -316,7 +322,6 @@ class QAPIDoc:
def __init__(self, name=None):
# optional section name (argument/member or section name)
self.name = name
- # the list of lines for this section
self.text = ''
def append(self, line):
@@ -69,7 +69,8 @@ event EVT-BOXED Object
doc freeform
body=
= Section
-
+doc freeform
+ body=
== Subsection
*strong* _with emphasis_
Our current QAPI doc-comment markup allows section headers (introduced with a leading '=' or '==') anywhere in a free-form documentation comment. This works for Texinfo because the generator simply prints a Texinfo section command at that point in the output stream. For rST generation, since we're assembling a tree of docutils nodes, this is awkward because a new section implies starting a new section node at the top level of the tree and generating text into there. Make section headers start a new free-form documentation block, so the future rST document generator doesn't have to look at every line in free-form blocks and handle headings in odd places. This change makes no difference to the generated Texinfo. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200320091805.5585-3-armbru@redhat.com> --- scripts/qapi/parser.py | 21 +++++++++++++-------- tests/qapi-schema/doc-good.out | 3 ++- 2 files changed, 15 insertions(+), 9 deletions(-)