Markus Armbruster <arm...@redhat.com> writes:
> John Snow <js...@redhat.com> writes:
>
>> This patch adds an explicit section "kind" to all QAPIDoc
>> sections. Members/Features are now explicitly marked as such, with the
>> name now being stored in a dedicated "name" field (which qapidoc.py was
>> not actually using anyway.)
>>
>> The qapi-schema tests are updated to account for the new section names;
>> mostly "TODO" becomes "Todo" and `None` becomes "Plain".
>>
>> Signed-off-by: John Snow <js...@redhat.com>
>
> I think the commit message could be clearer. But I'm too tired for
> wordsmithing. I intend to have another look at it tomorrow.
qapi: Clean up encoding of section kinds
We have several kinds of sections, and to tell them apart, we use
Section attribute @tag and also the section object's Python type:
type @tag
untagged Section None
@foo: ArgSection 'foo'
Returns: Section 'Returns'
Errors: Section 'Errors'
Since: Section 'Since'
TODO: Section 'TODO'
Note:
* @foo can be a member or a feature description, depending on context.
* tag == 'Since' can be a Since: section or a member or feature
description. If it's a Section, it's the former, and if it's an
ArgSection, it's the latter.
Clean this up as follows. Move the member or feature name to new
ArgSection attribute @name, and replace @tag by enum @kind like this:
type kind name
untagged Section PLAIN
@foo: ArgSection MEMBER 'foo' if member or argument
ArgSection FEATURE 'foo' if feature
Returns: Section RETURNS
Errors: Section ERRORS
Since: Section SINCE
TODO: Section TODO
The qapi-schema tests are updated to account for the new section names;
"TODO" becomes "Todo" and `None` becomes "Plain" there.
