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

qapi: Reject section heading in the middle of a doc comment

Browse Source 
docs/devel/qapi-code-gen.txt claims "A heading line must be the first
line of the documentation comment block" since commit
55ec69f8b1 (docs/devel/qapi-code-gen.txt: Update to new rST backend
conventions).  Not true, we have code to make it work anywhere in a
free-form doc comment: commit dcdc07a97c (qapi: Make section headings
start a new doc comment block).

Make it true, for simplicity's sake.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240216145841.2099240-10-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
This commit is contained in:
Markus Armbruster 2024-02-16 15:58:33 +01:00
parent 31c54b92ad
commit 56c64dd60a
5 changed files with 13 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
scripts/qapi/parser.py
View File

@ -440,9 +440,9 @@ class QAPISchemaParser:
self, self,
"unexpected '=' markup in definition documentation") "unexpected '=' markup in definition documentation")
if cur_doc.body.text: if cur_doc.body.text:
cur_doc.end_comment() raise QAPIParseError(
docs.append(cur_doc) self,
cur_doc = QAPIDoc(self, info) "'=' heading must come first in a comment block")
cur_doc.append(self.val) cur_doc.append(self.val)
self.accept(False) self.accept(False)

4
tests/qapi-schema/doc-good.json
View File

@ -9,7 +9,9 @@
## ##
# = Section # = Section
# ##
##
# == Subsection # == Subsection
# #
# *with emphasis* # *with emphasis*

1
tests/qapi-schema/doc-non-first-section.err Normal file
View File

@ -0,0 +1 @@
doc-non-first-section.json:5:1: '=' heading must come first in a comment block

6
tests/qapi-schema/doc-non-first-section.json Normal file
View File

@ -0,0 +1,6 @@
# = section must be first line
##
#
# = Not first
##

0
tests/qapi-schema/doc-non-first-section.out Normal file
View File