diff options
| author | Markus Armbruster <armbru@redhat.com> | 2024-02-16 15:58:33 +0100 |
|---|---|---|
| committer | Markus Armbruster <armbru@redhat.com> | 2024-02-26 10:43:56 +0100 |
| commit | 56c64dd60aebb9c856ab63de74c9e81acd079436 (patch) | |
| tree | d7b98825495c13fad60afb087a49566c98504ff6 | |
| parent | 31c54b92ad0816ab1c4eddaf4b60c0b17a75dfc9 (diff) | |
| download | qemu-56c64dd60aebb9c856ab63de74c9e81acd079436.zip qemu-56c64dd60aebb9c856ab63de74c9e81acd079436.tar.gz qemu-56c64dd60aebb9c856ab63de74c9e81acd079436.tar.bz2 | |
qapi: Reject section heading in the middle of a doc comment
docs/devel/qapi-code-gen.txt claims "A heading line must be the first
line of the documentation comment block" since commit
55ec69f8b16 (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 dcdc07a97cb (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>
| -rw-r--r-- | scripts/qapi/parser.py | 6 | ||||
| -rw-r--r-- | tests/qapi-schema/doc-good.json | 4 | ||||
| -rw-r--r-- | tests/qapi-schema/doc-non-first-section.err | 1 | ||||
| -rw-r--r-- | tests/qapi-schema/doc-non-first-section.json | 6 | ||||
| -rw-r--r-- | tests/qapi-schema/doc-non-first-section.out | 0 |
5 files changed, 13 insertions, 4 deletions
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index cc69f4f..3aefec1 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -440,9 +440,9 @@ class QAPISchemaParser: self, "unexpected '=' markup in definition documentation") if cur_doc.body.text: - cur_doc.end_comment() - docs.append(cur_doc) - cur_doc = QAPIDoc(self, info) + raise QAPIParseError( + self, + "'=' heading must come first in a comment block") cur_doc.append(self.val) self.accept(False) diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 24a84fe..0479d16 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -9,7 +9,9 @@ ## # = Section -# +## + +## # == Subsection # # *with emphasis* diff --git a/tests/qapi-schema/doc-non-first-section.err b/tests/qapi-schema/doc-non-first-section.err new file mode 100644 index 0000000..eeced2b --- /dev/null +++ b/tests/qapi-schema/doc-non-first-section.err @@ -0,0 +1 @@ +doc-non-first-section.json:5:1: '=' heading must come first in a comment block diff --git a/tests/qapi-schema/doc-non-first-section.json b/tests/qapi-schema/doc-non-first-section.json new file mode 100644 index 0000000..1590876 --- /dev/null +++ b/tests/qapi-schema/doc-non-first-section.json @@ -0,0 +1,6 @@ +# = section must be first line + +## +# +# = Not first +## diff --git a/tests/qapi-schema/doc-non-first-section.out b/tests/qapi-schema/doc-non-first-section.out new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tests/qapi-schema/doc-non-first-section.out |