Re: [PATCH v2 33/62] qapi: expand tags to all doc sections

[Markus Armbruster <armbru@redhat.com>]

Markus Armbruster <armbru@redhat.com> writes:

> John Snow <jsnow@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 <jsnow@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.