[PULL 1/5] qapi: Reject section markup in definition documentation

[Markus Armbruster <armbru@redhat.com>]

Section markup in definition documentation makes no sense and can
produce invalid Texinfo.  Reject.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20200320091805.5585-2-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 docs/devel/qapi-code-gen.txt           |  2 ++
 scripts/qapi/parser.py                 |  5 +++++
 tests/qapi-schema/doc-bad-section.err  |  1 +
 tests/qapi-schema/doc-bad-section.json |  3 +--
 tests/qapi-schema/doc-bad-section.out  | 24 ------------------------
 5 files changed, 9 insertions(+), 26 deletions(-)

diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index f3e7ced212..9eede44350 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -835,6 +835,8 @@ Double the '=' for a subsection title:
 
     # == Subsection title
 
+Both are only permitted in free-form documentation.
+
 '|' denotes examples:
 
     # | Text of the example, may span
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index abadacbb0e..f12c67d7d2 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -282,6 +282,11 @@ class QAPISchemaParser:
                 doc.end_comment()
                 self.accept()
                 return doc
+            if self.val.startswith('# ='):
+                if doc.symbol:
+                    raise QAPIParseError(
+                        self,
+                        "unexpected '=' markup in definition documentation")
             doc.append(self.val)
             self.accept(False)
 
diff --git a/tests/qapi-schema/doc-bad-section.err b/tests/qapi-schema/doc-bad-section.err
index e69de29bb2..785cacc08c 100644
--- a/tests/qapi-schema/doc-bad-section.err
+++ b/tests/qapi-schema/doc-bad-section.err
@@ -0,0 +1 @@
+doc-bad-section.json:5:1: unexpected '=' markup in definition documentation
diff --git a/tests/qapi-schema/doc-bad-section.json b/tests/qapi-schema/doc-bad-section.json
index 560df4b087..8175d95867 100644
--- a/tests/qapi-schema/doc-bad-section.json
+++ b/tests/qapi-schema/doc-bad-section.json
@@ -1,9 +1,8 @@
 # = section within an expression comment
-# BUG: not rejected
 
 ##
 # @Enum:
-# == Produces *invalid* texinfo
+# == No good here
 # @one: The _one_ {and only}
 #
 # @two is undocumented
diff --git a/tests/qapi-schema/doc-bad-section.out b/tests/qapi-schema/doc-bad-section.out
index 367e2a1c3e..e69de29bb2 100644
--- a/tests/qapi-schema/doc-bad-section.out
+++ b/tests/qapi-schema/doc-bad-section.out
@@ -1,24 +0,0 @@
-module None
-object q_empty
-enum QType
-    prefix QTYPE
-    member none
-    member qnull
-    member qnum
-    member qstring
-    member qdict
-    member qlist
-    member qbool
-module doc-bad-section.json
-enum Enum
-    member one
-    member two
-doc symbol=Enum
-    body=
-== Produces *invalid* texinfo
-    arg=one
-The _one_ {and only}
-    arg=two
-
-    section=None
-@two is undocumented
-- 
2.26.2