| Message ID | 20200320091805.5585-3-armbru@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | qapi: A section heading bug fix, and maybe an improvement | expand |
On Fri, 20 Mar 2020 at 09:18, Markus Armbruster <armbru@redhat.com> wrote: > > 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. I think this does make things easier for rST generation (which now can say "if the first line in the freeform doc is a section heading, do section heading stuff, discard that line, process rest of freeform doc as normal"), so on that basis I like it. I do kind of think it would be overall nicer to go further and say "section headings are special and not part of free-form doc comments at all" (both for the doc-comment author by mandating that they be standalone, and for the consumer of parsed info by separating section headings out from free-form doc comment rather than requiring the consumer to say "is this line heading syntax?"), but that would be more change, so pragmatically I'm happy if we just do what this patch suggests. thanks -- PMM
Peter Maydell <peter.maydell@linaro.org> writes: > On Fri, 20 Mar 2020 at 09:18, Markus Armbruster <armbru@redhat.com> wrote: >> >> 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. > > I think this does make things easier for rST generation > (which now can say "if the first line in the freeform doc > is a section heading, do section heading stuff, discard that > line, process rest of freeform doc as normal"), so on > that basis I like it. Good. > I do kind of think it would be overall nicer to go further and > say "section headings are special and not part of free-form doc > comments at all" (both for the doc-comment author by mandating > that they be standalone, and for the consumer of parsed info > by separating section headings out from free-form doc comment > rather than requiring the consumer to say "is this line heading > syntax?"), but that would be more change, so pragmatically > I'm happy if we just do what this patch suggests. I think there are two separate issues: doc comment syntax and internal representation. Our internal representation reflects the input's flat structure: one comment block after the other. I wish it reflected the document's tree structure instead, but I can't justify the effort to rework it. What to put into syntax and what to leave to style is often debatable. Putting headings into their own block makes them stand out even more, which may be useful. Baking that into the syntax feels a bit oppressive to me. Sometimes a bit of oppression can buy enough consistency to be worth it. Thanks!
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_
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> --- scripts/qapi/parser.py | 21 +++++++++++++-------- tests/qapi-schema/doc-good.out | 3 ++- 2 files changed, 15 insertions(+), 9 deletions(-)