[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 2/5] qapi: Make section headings start a new doc comment block
From: |
Markus Armbruster |
Subject: |
[PULL 2/5] qapi: Make section headings start a new doc comment block |
Date: |
Tue, 8 Sep 2020 08:54:14 +0200 |
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(-)
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index f12c67d7d2..165925ca72 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -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):
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 6757dd26a2..d78a424cd9 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -69,7 +69,8 @@ event EVT-BOXED Object
doc freeform
body=
= Section
-
+doc freeform
+ body=
== Subsection
*strong* _with emphasis_
--
2.26.2
- [PULL 0/5] QAPI patches patches for 2020-09-08, Markus Armbruster, 2020/09/08
- [PULL 3/5] qapi/migration.json: Fix indentation, Markus Armbruster, 2020/09/08
- [PULL 5/5] qapi/block-core.json: Fix nbd-server-start docs, Markus Armbruster, 2020/09/08
- [PULL 1/5] qapi: Reject section markup in definition documentation, Markus Armbruster, 2020/09/08
- [PULL 4/5] qapi: Fix indentation, again, Markus Armbruster, 2020/09/08
- [PULL 2/5] qapi: Make section headings start a new doc comment block,
Markus Armbruster <=
- Re: [PULL 0/5] QAPI patches patches for 2020-09-08, Peter Maydell, 2020/09/08