qapi/parser: remove FIXME comment from _append_body_line
commitcd87c14cde5db42a2f13bfdbba1f3cbeb347a411
authorJohn Snow <jsnow@redhat.com>
Thu, 30 Sep 2021 20:57:08 +0000 (30 16:57 -0400)
committerMarkus Armbruster <armbru@redhat.com>
Sat, 2 Oct 2021 05:33:42 +0000 (2 07:33 +0200)
treed8f01e07068c9d926f828f90da7ea6144c0b731f
parenta9e2eb06ed061f37c3ba6ad52722eef20afd713a
qapi/parser: remove FIXME comment from _append_body_line

True, we do not check the validity of this symbol -- but we don't check
the validity of definition names during parse, either -- that happens
later, during the expr check. I don't want to introduce a dependency on
expr.py:check_name_str here and introduce a cycle.

Instead, rest assured that a documentation block is required for each
definition. This requirement uses the names of each section to ensure
that we fulfilled this requirement.

e.g., let's say that block-core.json has a comment block for
"Snapshot!Info" by accident. We'll see this error message:

In file included from ../../qapi/block.json:8:
../../qapi/block-core.json: In struct 'SnapshotInfo':
../../qapi/block-core.json:38: documentation comment is for 'Snapshot!Info'

That's a pretty decent error message.

Now, let's say that we actually mangle it twice, identically:

../../qapi/block-core.json: In struct 'Snapshot!Info':
../../qapi/block-core.json:38: struct has an invalid name

That's also pretty decent. If we forget to fix it in both places, we'll
just be back to the first error.

Therefore, let's just drop this FIXME and adjust the error message to
not imply a more thorough check than is actually performed.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-Id: <20210930205716.1148693-6-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
scripts/qapi/parser.py
tests/qapi-schema/doc-empty-symbol.err