mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

qapi: Make section headings start a new doc comment block

Browse Source 
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>
This commit is contained in:
Markus Armbruster 2020-03-20 10:18:05 +01:00
parent d98884b75d
commit dcdc07a97c
2 changed files with 15 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
scripts/qapi/parser.py
View File

@ -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):

3
tests/qapi-schema/doc-good.out
View File

@ -69,7 +69,8 @@ event EVT-BOXED Object
doc freeform
body=
= Section
doc freeform
body=
== Subsection
*strong* _with emphasis_