From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 063E8C282D1 for ; Thu, 6 Mar 2025 04:04:19 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tq2Sp-0002Vq-Eu; Wed, 05 Mar 2025 23:04:03 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tq2Sm-0002Uk-Kx for qemu-devel@nongnu.org; Wed, 05 Mar 2025 23:04:00 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tq2Sh-0006Ps-RY for qemu-devel@nongnu.org; Wed, 05 Mar 2025 23:04:00 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741233832; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=yomA8dkBuU/zl2/2Si2KpYrHafQTVHRbEc6uc2XweHM=; b=M8zDGTU3DSSwQEibr3lnPSBn4oNa9SsogO12PgpH8ZAtCZZ7qitc4TikQDDTDrHwk93SLZ Wqlu4QvVZOh6ce/K5H0iTOC8TWJVLcV+Zft16wOzkygk0vtDkb5ojzH2RnsEOQE52XPnAf mWa4ZTCMC3Ft0nW/hP+f+8NKytryL1I= Received: from mail-pj1-f69.google.com (mail-pj1-f69.google.com [209.85.216.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-556-tPpSwzScMfmmPp2b7q7U6g-1; Wed, 05 Mar 2025 23:03:50 -0500 X-MC-Unique: tPpSwzScMfmmPp2b7q7U6g-1 X-Mimecast-MFC-AGG-ID: tPpSwzScMfmmPp2b7q7U6g_1741233829 Received: by mail-pj1-f69.google.com with SMTP id 98e67ed59e1d1-2ff581215a0so947758a91.0 for ; Wed, 05 Mar 2025 20:03:50 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1741233829; x=1741838629; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=yomA8dkBuU/zl2/2Si2KpYrHafQTVHRbEc6uc2XweHM=; b=htwZX3fMLIYietae63E2i962bof2qjUvf4lZMG0p28MHbh5mmHvTVL43rDBbAL7uNA hNUZQ56pZCyU+gBRCyQByH52cksUdHgRTjdIv8rC7e+As6csVsKLQioUDrW6dPJhEXYN lHpJmBLHSVqwQWhngjqB6WwPekeC4ie5aTWVTr7Qp4dQbLzGx8sihe0+mpWUfEDEfcIC KaM0rxWZxMAtvPIxE4ZTjpr4w5oClmfhetY8DblLWEB9441aF7zNZgtKLloLGm5kP6vt S+JZafQBmH8XLRwsIuOpuZ607Yj+RB34Dy59Gd9wKTVfZS8ftMy/PnJANF6tOMdcKw0I r+vw== X-Gm-Message-State: AOJu0YwEYqkqjktybbOkKz5YeGZeoWXVnSohD7+ZjBI2UDKP6OnVFtjx h5pFJDz2CEl0KAPjFY+eZvs3Nhl6xf8bo84YKWtkrU/474PL4EVE7Ry342/+Q3mx+dFOq3mwSeT 2ds8to0dtza2kSMJwOhhu43k9gu0L4G712lZ5MQet62seOXQY9957sFKYJFnyoLqS5k4yx/T0tj Ax6It9mAzk4e63HgupiVVW+iP89RQ= X-Gm-Gg: ASbGncuB02K/0zsbnPu0+31Y/ZZ8vs61QUw6L22M5+n1I3M7yxD2ptHJeI3SCwXijTI rQkEbjCqn9gu7iilfqVMDDsZGjw+AkxaDyh6rbJwJkHUZXI9UJgM7QlyTPfwN4xoNN/vEney0Rh hVMquDo1vqIpidCEUzX9R+bb47DsK1 X-Received: by 2002:a17:90b:4a10:b0:2ff:6af3:b5fa with SMTP id 98e67ed59e1d1-2ff6af3b6b6mr376325a91.22.1741233510619; Wed, 05 Mar 2025 19:58:30 -0800 (PST) X-Google-Smtp-Source: AGHT+IEAZpkl8tcL7i+MwSgehiztK204eKoxpTICN/j/B7H51JBsfIbcU5nlfSVQ7gp94wD3gYWNA07gwI3ixbfp+So= X-Received: by 2002:a17:90b:4a10:b0:2ff:6af3:b5fa with SMTP id 98e67ed59e1d1-2ff6af3b6b6mr376244a91.22.1741233509072; Wed, 05 Mar 2025 19:58:29 -0800 (PST) MIME-Version: 1.0 References: <20250305034610.960147-1-jsnow@redhat.com> <20250305034610.960147-32-jsnow@redhat.com> <875xknok8w.fsf@pond.sub.org> In-Reply-To: <875xknok8w.fsf@pond.sub.org> From: John Snow Date: Wed, 5 Mar 2025 22:58:14 -0500 X-Gm-Features: AQ5f1JpbRweRf6G7wh3fMofIEJpBxJxkf4jtCt_r6kHJ6PYhrvbyZEaywpam05w Message-ID: Subject: Re: [PATCH 31/57] qapi: expand tags to all doc sections To: Markus Armbruster Cc: qemu-devel@nongnu.org, Michael Roth , =?UTF-8?B?QWxleCBCZW5uw6ll?= , =?UTF-8?Q?Philippe_Mathieu=2DDaud=C3=A9?= , Peter Maydell , Thomas Huth , =?UTF-8?Q?Daniel_P=2E_Berrang=C3=A9?= Content-Type: multipart/alternative; boundary="000000000000c7a377062fa4845d" Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org --000000000000c7a377062fa4845d Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Wed, Mar 5, 2025 at 5:16=E2=80=AFAM Markus Armbruster wrote: > Replaying review of a previous posting for your convenience... > > John Snow 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.) > > I'm not sure what the parenthesis is trying to convey. > The old qapidoc.py doesn't actually use the name field, so there's nothing to adjust for old callers. > > Before the patch, we have: > > type tag > untagged Section None > @foo: ArgSection 'foo' > Returns: Section 'Returns' > Errors: Section 'Errors' > Since: Section 'Since' > TODO: Section 'TODO' > > Afterwards, I believe: > > 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 > > So, .tag is replaced by .kind and .name, member vs. feature vs. other > tags is now obvious from .kind alone, i.e. there's no need to account > for context or type. > > Fine print: why do we need to account for type before the patch? > Consider @Since: ... > I'm not sure I follow... > > > 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 > > --- > > docs/sphinx/qapidoc.py | 7 ++- > > scripts/qapi/parser.py | 109 ++++++++++++++++++++++++--------- > > tests/qapi-schema/doc-good.out | 10 +-- > > tests/qapi-schema/test-qapi.py | 2 +- > > 4 files changed, 90 insertions(+), 38 deletions(-) > > > > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py > > index 61997fd21af..d622398f1da 100644 > > --- a/docs/sphinx/qapidoc.py > > +++ b/docs/sphinx/qapidoc.py > > @@ -35,6 +35,7 @@ > > from docutils.statemachine import ViewList > > from qapi.error import QAPIError, QAPISemError > > from qapi.gen import QAPISchemaVisitor > > +from qapi.parser import QAPIDoc > > from qapi.schema import QAPISchema > > > > from sphinx import addnodes > > @@ -258,11 +259,11 @@ def _nodes_for_sections(self, doc): > > """Return list of doctree nodes for additional sections""" > > nodelist =3D [] > > for section in doc.sections: > > - if section.tag and section.tag =3D=3D 'TODO': > > + if section.kind =3D=3D QAPIDoc.Kind.TODO: > > # Hide TODO: sections > > continue > > > > - if not section.tag: > > + if section.kind =3D=3D QAPIDoc.Kind.PLAIN: > > # Sphinx cannot handle sectionless titles; > > # Instead, just append the results to the prior sectio= n. > > container =3D nodes.container() > > @@ -270,7 +271,7 @@ def _nodes_for_sections(self, doc): > > nodelist +=3D container.children > > continue > > > > - snode =3D self._make_section(section.tag) > > + snode =3D self._make_section(section.kind.name.title()) > > self._parse_text_into_node(dedent(section.text), snode) > > nodelist.append(snode) > > return nodelist > > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py > > index 36cb64a677a..c3004aa70c6 100644 > > --- a/scripts/qapi/parser.py > > +++ b/scripts/qapi/parser.py > > @@ -15,6 +15,7 @@ > > # See the COPYING file in the top-level directory. > > > > from collections import OrderedDict > > +import enum > > import os > > import re > > from typing import ( > > @@ -575,7 +576,10 @@ def get_doc(self) -> 'QAPIDoc': > > ) > > raise QAPIParseError(self, emsg) > > > > - doc.new_tagged_section(self.info, match.group(1)) > > + doc.new_tagged_section( > > + self.info, > > + QAPIDoc.Kind.from_string(match.group(1)) > > + ) > > text =3D line[match.end():] > > if text: > > doc.append_line(text) > > @@ -586,7 +590,7 @@ def get_doc(self) -> 'QAPIDoc': > > self, > > "unexpected '=3D' markup in definition > documentation") > > else: > > - # tag-less paragraph > > + # plain paragraph(s) > > We're parsing a single pargraph here. The plain section we add it to > may have any number of paragraphs. But for me, the comment is about > what's being parsed. Mind to drop (s)? > Anguish. I can't keep this straight in my head. OK. It wasn't obvious at a glance where the break is if we get an empty newline ... > > > doc.ensure_untagged_section(self.info) > > doc.append_line(line) > > line =3D self.get_doc_paragraph(doc) > > @@ -635,14 +639,37 @@ class QAPIDoc: > > Free-form documentation blocks consist only of a body section. > > """ > > > > + class Kind(enum.Enum): > > + PLAIN =3D 0 > > + MEMBER =3D 1 > > + FEATURE =3D 2 > > + RETURNS =3D 3 > > + ERRORS =3D 4 > > + SINCE =3D 5 > > + TODO =3D 6 > > + > > + @staticmethod > > + def from_string(kind: str) -> 'QAPIDoc.Kind': > > Remind me, why do we need to quote the type here? > It doesn't exist yet; it's a forward reference, basically. While we are in the context of defining the class, we don't have access to variables scoped within the class :) > > > + return QAPIDoc.Kind[kind.upper()] > > + > > + def text_required(self) -> bool: > > + # Only "plain" sections can be empty > > + return self.value not in (0,) > > Rather roundabout way to check for PLAIN, isn't it? > Vestigial from intro/details split. It can be removed here for now. > > There's just one caller (see below). I doubt the method is worth its > keep. > Vestigial again. Whether it's worth it once there are multiple such sections, who knows. I thought it made the code read nicer in context. We don't need it right now anyway... > > > + > > + def __str__(self) -> str: > > + return self.name.title() > > + > > I wonder whether a simple StrEnum without methods would do. Oh, StrEnum > is new in 3.11. Nevermind. > > Hmm. > > >>> Kind =3D Enum('Kind', [('PLAIN', 'Plain'), ('TODO, 'TODO)]) > >>> kind=3DKind('Plain') > >>> kind.value > 'Plain' > > What do you think? > Maybe, lemme play with it and see if it makes something else worse, I don't know right away. > > > class Section: > > # pylint: disable=3Dtoo-few-public-methods > > - def __init__(self, info: QAPISourceInfo, > > - tag: Optional[str] =3D None): > > + def __init__( > > + self, > > + info: QAPISourceInfo, > > + kind: 'QAPIDoc.Kind', > > + ): > > # section source info, i.e. where it begins > > self.info =3D info > > - # section tag, if any ('Returns', '@name', ...) > > - self.tag =3D tag > > + # section kind > > + self.kind =3D kind > > # section text without tag > > self.text =3D '' > > > > @@ -650,8 +677,14 @@ def append_line(self, line: str) -> None: > > self.text +=3D line + '\n' > > > > class ArgSection(Section): > > - def __init__(self, info: QAPISourceInfo, tag: str): > > - super().__init__(info, tag) > > + def __init__( > > + self, > > + info: QAPISourceInfo, > > + kind: 'QAPIDoc.Kind', > > + name: str > > + ): > > + super().__init__(info, kind) > > + self.name =3D name > > self.member: Optional['QAPISchemaMember'] =3D None > > Before the patch, use of a separate type for members, arguments and > features was necessary to distinguish between '@TAG:' and 'TAG:' for the > various TAGs. This is no longer the case. Fold ArgSection into > Section? Not sure. If yes, separate patch to keep this one as > mechanical as possible. > Possibly the case. I'll play with it. Do you want it in this series? (It's pretty long as is...!) > > > > > def connect(self, member: 'QAPISchemaMember') -> None: > > @@ -663,7 +696,9 @@ def __init__(self, info: QAPISourceInfo, symbol: > Optional[str] =3D None): > > # definition doc's symbol, None for free-form doc > > self.symbol: Optional[str] =3D symbol > > # the sections in textual order > > - self.all_sections: List[QAPIDoc.Section] =3D > [QAPIDoc.Section(info)] > > + self.all_sections: List[QAPIDoc.Section] =3D [ > > + QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN) > > + ] > > # the body section > > self.body: Optional[QAPIDoc.Section] =3D self.all_sections[0] > > # dicts mapping parameter/feature names to their description > > @@ -680,12 +715,17 @@ def __init__(self, info: QAPISourceInfo, symbol: > Optional[str] =3D None): > > def end(self) -> None: > > for section in self.all_sections: > > section.text =3D section.text.strip('\n') > > - if section.tag is not None and section.text =3D=3D '': > > + if section.kind.text_required() and section.text =3D=3D ''= : > > This is the only use of .text_required(). I believe checking for PLAIN > would be clearer. > > > raise QAPISemError( > > - section.info, "text required after '%s:'" % > section.tag) > > + section.info, "text required after '%s:'" % > section.kind) > > > > - def ensure_untagged_section(self, info: QAPISourceInfo) -> None: > > - if self.all_sections and not self.all_sections[-1].tag: > > + def ensure_untagged_section( > > + self, > > + info: QAPISourceInfo, > > + ) -> None: > > Accidental line breaking? > Something something something black autoformatter. I wonder why it did this, though... I'll see if I can undo it. > > > + kind =3D QAPIDoc.Kind.PLAIN > > + > > + if self.all_sections and self.all_sections[-1].kind =3D=3D kin= d: > > I'd prefer not to hide PLAIN behind a variable, but I'd also prefer > the condition to fit on a line. Hmm. > Also somewhat vestigial from when I had intro/details. When that split comes, kind =3D becomes a conditional ternary. > > > # extend current section > > section =3D self.all_sections[-1] > > if not section.text: > > Maybe > > section =3D self.all_sections[-1] if self.all_sections else No= ne > > if second and section.kind =3D QAPIDoc.Kind.Plain: > # extend current section > if not section.text: > Could, but it's going to get rewritten when the inliner comes anyway, ... > > > @@ -693,46 +733,56 @@ def ensure_untagged_section(self, info: > QAPISourceInfo) -> None: > > section.info =3D info > > section.text +=3D '\n' > > return > > + > > # start new section > > - section =3D self.Section(info) > > + section =3D self.Section(info, kind) > > self.sections.append(section) > > self.all_sections.append(section) > > > > - def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> > None: > > - section =3D self.Section(info, tag) > > - if tag =3D=3D 'Returns': > > + def new_tagged_section( > > + self, > > + info: QAPISourceInfo, > > + kind: 'QAPIDoc.Kind', > > + ) -> None: > > + section =3D self.Section(info, kind) > > + if kind =3D=3D QAPIDoc.Kind.RETURNS: > > if self.returns: > > raise QAPISemError( > > - info, "duplicated '%s' section" % tag) > > + info, "duplicated '%s' section" % kind) > > self.returns =3D section > > - elif tag =3D=3D 'Errors': > > + elif kind =3D=3D QAPIDoc.Kind.ERRORS: > > if self.errors: > > raise QAPISemError( > > - info, "duplicated '%s' section" % tag) > > + info, "duplicated '%s' section" % kind) > > self.errors =3D section > > - elif tag =3D=3D 'Since': > > + elif kind =3D=3D QAPIDoc.Kind.SINCE: > > if self.since: > > raise QAPISemError( > > - info, "duplicated '%s' section" % tag) > > + info, "duplicated '%s' section" % kind) > > self.since =3D section > > self.sections.append(section) > > self.all_sections.append(section) > > > > - def _new_description(self, info: QAPISourceInfo, name: str, > > - desc: Dict[str, ArgSection]) -> None: > > + def _new_description( > > + self, > > + info: QAPISourceInfo, > > + name: str, > > + kind: 'QAPIDoc.Kind', > > + desc: Dict[str, ArgSection] > > + ) -> None: > > if not name: > > raise QAPISemError(info, "invalid parameter name") > > if name in desc: > > raise QAPISemError(info, "'%s' parameter name duplicated" = % > name) > > - section =3D self.ArgSection(info, '@' + name) > > + section =3D self.ArgSection(info, kind, name) > > self.all_sections.append(section) > > desc[name] =3D section > > > > def new_argument(self, info: QAPISourceInfo, name: str) -> None: > > - self._new_description(info, name, self.args) > > + self._new_description(info, name, QAPIDoc.Kind.MEMBER, > self.args) > > > > def new_feature(self, info: QAPISourceInfo, name: str) -> None: > > - self._new_description(info, name, self.features) > > + self._new_description(info, name, QAPIDoc.Kind.FEATURE, > self.features) > > QAPIDoc.Kind.FOO is a mouthful, and it tends to result in long lines, > like here. Can't see an easy and clean way to reduce the verbosity. > Yeah... > > > > > def append_line(self, line: str) -> None: > > self.all_sections[-1].append_line(line) > > @@ -744,8 +794,9 @@ def connect_member(self, member: 'QAPISchemaMember'= ) > -> None: > > raise QAPISemError(member.info, > > "%s '%s' lacks documentation" > > % (member.role, member.name)) > > - self.args[member.name] =3D QAPIDoc.ArgSection( > > - self.info, '@' + member.name) > > + section =3D QAPIDoc.ArgSection( > > + self.info, QAPIDoc.Kind.MEMBER, member.name) > > + self.args[member.name] =3D section > > Why the extra variable? > Wish I remembered. I can undo it and see if anything barks. > > > self.args[member.name].connect(member) > > > > def connect_feature(self, feature: 'QAPISchemaFeature') -> None: > > diff --git a/tests/qapi-schema/doc-good.out > b/tests/qapi-schema/doc-good.out > > index 0a9da3efdeb..5773f1dd6d6 100644 > > --- a/tests/qapi-schema/doc-good.out > > +++ b/tests/qapi-schema/doc-good.out > > @@ -113,7 +113,7 @@ The _one_ {and only}, description on the same line > > Also _one_ {and only} > > feature=3Denum-member-feat > > a member feature > > - section=3DNone > > + section=3DPlain > > @two is undocumented > > doc symbol=3DBase > > body=3D > > @@ -171,15 +171,15 @@ description starts on the same line > > a feature > > feature=3Dcmd-feat2 > > another feature > > - section=3DNone > > + section=3DPlain > > .. note:: @arg3 is undocumented > > section=3DReturns > > @Object > > section=3DErrors > > some > > - section=3DTODO > > + section=3DTodo > > With the method-less Enum I suggested, this hunk would go away. Not > that it matters :) > > > frobnicate > > - section=3DNone > > + section=3DPlain > > .. admonition:: Notes > > > > - Lorem ipsum dolor sit amet > > @@ -212,7 +212,7 @@ If you're bored enough to read this, go see a video > of boxed cats > > a feature > > feature=3Dcmd-feat2 > > another feature > > - section=3DNone > > + section=3DPlain > > .. qmp-example:: > > > > -> "this example" > > diff --git a/tests/qapi-schema/test-qapi.py > b/tests/qapi-schema/test-qapi.py > > index 7e3f9f4aa1f..bca924309be 100755 > > --- a/tests/qapi-schema/test-qapi.py > > +++ b/tests/qapi-schema/test-qapi.py > > @@ -131,7 +131,7 @@ def test_frontend(fname): > > for feat, section in doc.features.items(): > > print(' feature=3D%s\n%s' % (feat, section.text)) > > for section in doc.sections: > > - print(' section=3D%s\n%s' % (section.tag, section.text)= ) > > + print(' section=3D%s\n%s' % (section.kind, section.text= )) > > > > > > def open_test_result(dir_name, file_name, update): > > --000000000000c7a377062fa4845d Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


On Wed, Mar 5, = 2025 at 5:16=E2=80=AFAM Markus Armbruster <armbru@redhat.com> wrote:
Replaying review of a previous posting for your co= nvenience...

John Snow <jsnow@r= edhat.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 qap= idoc.py was
> not actually using anyway.)

I'm not sure what the parenthesis is trying to convey.
=

The old qapidoc.py doesn't actually use the name fi= eld, so there's nothing to adjust for old callers.
=C2=A0
=

Before the patch, we have:

=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 type=C2=A0 =C2=A0 =C2=A0 = =C2=A0 tag
=C2=A0 =C2=A0 untagged=C2=A0 Section=C2=A0 =C2=A0 =C2=A0None
=C2=A0 =C2=A0 @foo:=C2=A0 =C2=A0 =C2=A0ArgSection=C2=A0 'foo'
=C2=A0 =C2=A0 Returns:=C2=A0 Section=C2=A0 =C2=A0 =C2=A0'Returns' =C2=A0 =C2=A0 Errors:=C2=A0 =C2=A0Section=C2=A0 =C2=A0 =C2=A0'Errors= 9;
=C2=A0 =C2=A0 Since:=C2=A0 =C2=A0 Section=C2=A0 =C2=A0 =C2=A0'Since'= ;
=C2=A0 =C2=A0 TODO:=C2=A0 =C2=A0 =C2=A0Section=C2=A0 =C2=A0 =C2=A0'TODO= '

Afterwards, I believe:

=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 type=C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0kind=C2=A0 =C2=A0 =C2=A0name
=C2=A0 =C2=A0 untagged=C2=A0 Section=C2=A0 =C2=A0 =C2=A0 PLAIN
=C2=A0 =C2=A0 @foo:=C2=A0 =C2=A0 =C2=A0ArgSection=C2=A0 =C2=A0MEMBER=C2=A0 = =C2=A0'foo'=C2=A0 =C2=A0if member or argument
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 ArgSection=C2=A0 =C2=A0FEA= TURE=C2=A0 'foo'=C2=A0 =C2=A0if feature
=C2=A0 =C2=A0 Returns:=C2=A0 Section=C2=A0 =C2=A0 =C2=A0 RETURNS
=C2=A0 =C2=A0 Errors:=C2=A0 =C2=A0Section=C2=A0 =C2=A0 =C2=A0 ERRORS
=C2=A0 =C2=A0 Since:=C2=A0 =C2=A0 Section=C2=A0 =C2=A0 =C2=A0 SINCE
=C2=A0 =C2=A0 TODO:=C2=A0 =C2=A0 =C2=A0Section=C2=A0 =C2=A0 =C2=A0 TODO

So, .tag is replaced by .kind and .name, member vs. feature vs. other
tags is now obvious from .kind alone, i.e. there's no need to account for context or type.

Fine print: why do we need to account for type before the patch?
Consider @Since: ...

I'm not sure I= follow...
=C2=A0

> The qapi-schema tests are updated to account for the new section names= ;
> mostly "TODO" becomes "Todo" and `None` becomes &q= uot;Plain".
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>=C2=A0 docs/sphinx/qapidoc.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|=C2=A0 = =C2=A07 ++-
>=C2=A0 scripts/qapi/parser.py=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0| 109 ++= ++++++++++++++++++++++---------
>=C2=A0 tests/qapi-schema/doc-good.out |=C2=A0 10 +--
>=C2=A0 tests/qapi-schema/test-qapi.py |=C2=A0 =C2=A02 +-
>=C2=A0 4 files changed, 90 insertions(+), 38 deletions(-)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index 61997fd21af..d622398f1da 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -35,6 +35,7 @@
>=C2=A0 from docutils.statemachine import ViewList
>=C2=A0 from qapi.error import QAPIError, QAPISemError
>=C2=A0 from qapi.gen import QAPISchemaVisitor
> +from qapi.parser import QAPIDoc
>=C2=A0 from qapi.schema import QAPISchema
>=C2=A0
>=C2=A0 from sphinx import addnodes
> @@ -258,11 +259,11 @@ def _nodes_for_sections(self, doc):
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 """Return list of doc= tree nodes for additional sections"""
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 nodelist =3D []
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 for section in doc.sections:
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 if section.tag and section.= tag =3D=3D 'TODO':
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 if section.kind =3D=3D QAPI= Doc.Kind.TODO:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # Hide T= ODO: sections
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 continue=
>=C2=A0
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 if not section.tag:
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 if section.kind =3D=3D QAPI= Doc.Kind.PLAIN:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # Sphinx= cannot handle sectionless titles;
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # Instea= d, just append the results to the prior section.
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 containe= r =3D nodes.container()
> @@ -270,7 +271,7 @@ def _nodes_for_sections(self, doc):
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 nodelist= +=3D container.children
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 continue=
>=C2=A0
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 snode =3D self._make_sectio= n(section.tag)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 snode =3D self._make_sectio= n(section.kind.name.title())
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self._parse_text_into_= node(dedent(section.text), snode)
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 nodelist.append(snode)=
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 return nodelist
> diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> index 36cb64a677a..c3004aa70c6 100644
> --- a/scripts/qapi/parser.py
> +++ b/scripts/qapi/parser.py
> @@ -15,6 +15,7 @@
>=C2=A0 # See the COPYING file in the top-level directory.
>=C2=A0
>=C2=A0 from collections import OrderedDict
> +import enum
>=C2=A0 import os
>=C2=A0 import re
>=C2=A0 from typing import (
> @@ -575,7 +576,10 @@ def get_doc(self) -> 'QAPIDoc':
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 )
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 raise QAPIParseError(self, emsg)
>=C2=A0
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= doc.new_tagged_section(self.info, match.group(1))
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= doc.new_tagged_section(
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= =C2=A0 =C2=A0 self.info,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= =C2=A0 =C2=A0 QAPIDoc.Kind.from_string(match.group(1))
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= )
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 text =3D line[match.end():]
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 if text:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 doc.append_line(text)
> @@ -586,7 +590,7 @@ def get_doc(self) -> 'QAPIDoc':
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 self,
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 "unexpected '=3D' markup in definition do= cumentation")
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 else: > -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= # tag-less paragraph
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= # plain paragraph(s)

We're parsing a single pargraph here.=C2=A0 The plain section we add it= to
may have any number of paragraphs.=C2=A0 But for me, the comment is about what's being parsed.=C2=A0 Mind to drop (s)?

<= /div>
Anguish. I can't keep this straight in my head. OK. It wasn&#= 39;t obvious at a glance where the break is if we get an empty newline ...<= /div>
=C2=A0

>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 doc.ensure_untagged_section(self.info)
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 doc.append_line(line)
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 line =3D self.get_doc_paragraph(doc)
> @@ -635,14 +639,37 @@ class QAPIDoc:
>=C2=A0 =C2=A0 =C2=A0 Free-form documentation blocks consist only of a b= ody section.
>=C2=A0 =C2=A0 =C2=A0 """
>=C2=A0
> +=C2=A0 =C2=A0 class Kind(enum.Enum):
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 PLAIN =3D 0
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 MEMBER =3D 1
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 FEATURE =3D 2
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 RETURNS =3D 3
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 ERRORS =3D 4
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 SINCE =3D 5
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 TODO =3D 6
> +
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 @staticmethod
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 def from_string(kind: str) -> 'QAP= IDoc.Kind':

Remind me, why do we need to quote the type here?

=
It doesn't exist yet; it's a forward reference, basicall= y. While we are in the context of defining the class, we don't have acc= ess to variables scoped within the class :)
=C2=A0

> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 return QAPIDoc.Kind[kind.up= per()]
> +
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 def text_required(self) -> bool:
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # Only "plain" se= ctions can be empty
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 return self.value not in (0= ,)

Rather roundabout way to check for PLAIN, isn't it?

Vestigial from intro/details split. It can be removed here= for now.
=C2=A0

There's just one caller (see below).=C2=A0 I doubt the method is worth = its
keep.

Vestigial again. Whether it's= worth it once there are multiple such sections, who knows. I thought it ma= de the code read nicer in context. We don't need it right now anyway...=
=C2=A0

> +
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 def __str__(self) -> str:
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 return self.name.title() > +

I wonder whether a simple StrEnum without methods would do.=C2=A0 Oh, StrEn= um
is new in 3.11.=C2=A0 Nevermind.

Hmm.

=C2=A0 =C2=A0 >>> Kind =3D Enum('Kind', [('PLAIN',= 'Plain'), ('TODO, 'TODO)])
=C2=A0 =C2=A0 >>> kind=3DKind('Plain')
=C2=A0 =C2=A0 >>> kind.value
=C2=A0 =C2=A0 'Plain'

What do you think?

Maybe, lemme play wi= th it and see if it makes something else worse, I don't know right away= .
=C2=A0

>=C2=A0 =C2=A0 =C2=A0 class Section:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # pylint: disable=3Dtoo-few-public-m= ethods
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 def __init__(self, info: QAPISourceInfo,<= br> > -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= =C2=A0tag: Optional[str] =3D None):
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 def __init__(
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 info: QAPISourceInfo,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 kind: 'QAPIDoc.Kind'= ;,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 ):
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # section source info,= i.e. where it begins
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.info =3D info
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # section tag, if any ('= ;Returns', '@name', ...)
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.tag =3D tag
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # section kind
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.kind =3D kind
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # section text without= tag
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.text =3D '= 9;
>=C2=A0
> @@ -650,8 +677,14 @@ def append_line(self, line: str) -> None:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.text +=3D line + = '\n'
>=C2=A0
>=C2=A0 =C2=A0 =C2=A0 class ArgSection(Section):
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 def __init__(self, info: QAPISourceInfo, = tag: str):
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 super().__init__(info, tag)=
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 def __init__(
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 info: QAPISourceInfo,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 kind: 'QAPIDoc.Kind'= ;,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 name: str
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 ):
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 super().__init__(info, kind= )
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.name =3D name
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.member: Optional[= 'QAPISchemaMember'] =3D None

Before the patch, use of a separate type for members, arguments and
features was necessary to distinguish between '@TAG:' and 'TAG:= ' for the
various TAGs.=C2=A0 This is no longer the case.=C2=A0 Fold ArgSection into<= br> Section?=C2=A0 Not sure.=C2=A0 If yes, separate patch to keep this one as mechanical as possible.

Possibly the ca= se. I'll play with it. Do you want it in this series? (It's pretty = long as is...!)
=C2=A0

>=C2=A0
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 def connect(self, member: 'QAPIS= chemaMember') -> None:
> @@ -663,7 +696,9 @@ def __init__(self, info: QAPISourceInfo, symbol: O= ptional[str] =3D None):
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # definition doc's symbol, None = for free-form doc
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.symbol: Optional[str] =3D symbo= l
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # the sections in textual order
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 self.all_sections: List[QAPIDoc.Section] = =3D [QAPIDoc.Section(info)]
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 self.all_sections: List[QAPIDoc.Section] = =3D [
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 QAPIDoc.Section(info, QAPID= oc.Kind.PLAIN)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 ]
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # the body section
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.body: Optional[QAPIDoc.Section]= =3D self.all_sections[0]
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # dicts mapping parameter/feature na= mes to their description
> @@ -680,12 +715,17 @@ def __init__(self, info: QAPISourceInfo, symbol:= Optional[str] =3D None):
>=C2=A0 =C2=A0 =C2=A0 def end(self) -> None:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 for section in self.all_sections: >=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 section.text =3D secti= on.text.strip('\n')
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 if section.tag is not None = and section.text =3D=3D '':
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 if section.kind.text_requir= ed() and section.text =3D=3D '':

This is the only use of .text_required().=C2=A0 I believe checking for PLAI= N
would be clearer.

>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 raise QA= PISemError(
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= secti= on.info, "text required after '%s:'" % section.tag) > +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= secti= on.info, "text required after '%s:'" % section.kind)<= br> >=C2=A0
> -=C2=A0 =C2=A0 def ensure_untagged_section(self, info: QAPISourceInfo)= -> None:
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 if self.all_sections and not self.all_sec= tions[-1].tag:
> +=C2=A0 =C2=A0 def ensure_untagged_section(
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 self,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 info: QAPISourceInfo,
> +=C2=A0 =C2=A0 ) -> None:

Accidental line breaking?

Something som= ething something black autoformatter. I wonder why it did this, though... I= 'll see if I can undo it.
=C2=A0

> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 kind =3D QAPIDoc.Kind.PLAIN
> +
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 if self.all_sections and self.all_section= s[-1].kind =3D=3D kind:

I'd prefer not to hide PLAIN behind a variable, but I'd also prefer=
the condition to fit on a line.=C2=A0 Hmm.

<= div>Also somewhat vestigial from when I had intro/details. When that split = comes, kind =3D becomes a conditional ternary.
=C2=A0

>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # extend current secti= on
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 section =3D self.all_s= ections[-1]
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 if not section.text:
Maybe

=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0section =3D self.all_sections[-1] = if self.all_sections else None

=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0if second and section.kind =3D QAP= IDoc.Kind.Plain:
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0# extend current sec= tion
=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0if not section.text:=

Could, but it's going to get rewri= tten when the inliner comes anyway, ...
=C2=A0

> @@ -693,46 +733,56 @@ def ensure_untagged_section(self, info: QAPISour= ceInfo) -> None:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 section.info<= /a> =3D info
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 section.text +=3D '= ;\n'
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 return
> +
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 # start new section
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 section =3D self.Section(info)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 section =3D self.Section(info, kind)
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.sections.append(section)
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.all_sections.append(section) >=C2=A0
> -=C2=A0 =C2=A0 def new_tagged_section(self, info: QAPISourceInfo, tag:= str) -> None:
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 section =3D self.Section(info, tag)
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 if tag =3D=3D 'Returns':
> +=C2=A0 =C2=A0 def new_tagged_section(
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 self,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 info: QAPISourceInfo,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 kind: 'QAPIDoc.Kind',
> +=C2=A0 =C2=A0 ) -> None:
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 section =3D self.Section(info, kind)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 if kind =3D=3D QAPIDoc.Kind.RETURNS:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 if self.returns:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 raise QA= PISemError(
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= info, "duplicated '%s' section" % tag)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= info, "duplicated '%s' section" % kind)
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.returns =3D secti= on
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 elif tag =3D=3D 'Errors':
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 elif kind =3D=3D QAPIDoc.Kind.ERRORS:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 if self.errors:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 raise QA= PISemError(
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= info, "duplicated '%s' section" % tag)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= info, "duplicated '%s' section" % kind)
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.errors =3D sectio= n
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 elif tag =3D=3D 'Since':
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 elif kind =3D=3D QAPIDoc.Kind.SINCE:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 if self.since:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 raise QA= PISemError(
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= info, "duplicated '%s' section" % tag)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= info, "duplicated '%s' section" % kind)
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.since =3D section=
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.sections.append(section)
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.all_sections.append(section) >=C2=A0
> -=C2=A0 =C2=A0 def _new_description(self, info: QAPISourceInfo, name: = str,
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= =C2=A0 =C2=A0 =C2=A0desc: Dict[str, ArgSection]) -> None:
> +=C2=A0 =C2=A0 def _new_description(
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 self,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 info: QAPISourceInfo,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 name: str,
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 kind: 'QAPIDoc.Kind',
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 desc: Dict[str, ArgSection]
> +=C2=A0 =C2=A0 ) -> None:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 if not name:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 raise QAPISemError(inf= o, "invalid parameter name")
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 if name in desc:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 raise QAPISemError(inf= o, "'%s' parameter name duplicated" % name)
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 section =3D self.ArgSection(info, '@&= #39; + name)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 section =3D self.ArgSection(info, kind, n= ame)
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.all_sections.append(section) >=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 desc[name] =3D section
>=C2=A0
>=C2=A0 =C2=A0 =C2=A0 def new_argument(self, info: QAPISourceInfo, name:= str) -> None:
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 self._new_description(info, name, self.ar= gs)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 self._new_description(info, name, QAPIDoc= .Kind.MEMBER, self.args)
>=C2=A0
>=C2=A0 =C2=A0 =C2=A0 def new_feature(self, info: QAPISourceInfo, name: = str) -> None:
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 self._new_description(info, name, self.fe= atures)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 self._new_description(info, name, QAPIDoc= .Kind.FEATURE, self.features)

QAPIDoc.Kind.FOO is a mouthful, and it tends to result in long lines,
like here.=C2=A0 Can't see an easy and clean way to reduce the verbosit= y.


>=C2=A0
>=C2=A0 =C2=A0 =C2=A0 def append_line(self, line: str) -> None:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.all_sections[-1].append_line(li= ne)
> @@ -744,8 +794,9 @@ def connect_member(self, member: 'QAPISchemaMe= mber') -> None:
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 raise QA= PISemError(member.info,
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0"%s '= ;%s' lacks documentation"
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0% (member.rol= e, memb= er.name))
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.args[member.name] =3D QAP= IDoc.ArgSection(
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.info, '@&= #39; + = member.name)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 section =3D QAPIDoc.ArgSect= ion(
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.info, QAPIDoc= .Kind.MEMBER, member.name)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.args[member.name] =3D sec= tion

Why the extra variable?

Wish I remember= ed. I can undo it and see if anything barks.
=C2=A0

>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 self.args[member.name].connect(member)<= br> >=C2=A0
>=C2=A0 =C2=A0 =C2=A0 def connect_feature(self, feature: 'QAPISchema= Feature') -> None:
> diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-go= od.out
> index 0a9da3efdeb..5773f1dd6d6 100644
> --- a/tests/qapi-schema/doc-good.out
> +++ b/tests/qapi-schema/doc-good.out
> @@ -113,7 +113,7 @@ The _one_ {and only}, description on the same line=
>=C2=A0 Also _one_ {and only}
>=C2=A0 =C2=A0 =C2=A0 feature=3Denum-member-feat
>=C2=A0 a member feature
> -=C2=A0 =C2=A0 section=3DNone
> +=C2=A0 =C2=A0 section=3DPlain
>=C2=A0 @two is undocumented
>=C2=A0 doc symbol=3DBase
>=C2=A0 =C2=A0 =C2=A0 body=3D
> @@ -171,15 +171,15 @@ description starts on the same line
>=C2=A0 a feature
>=C2=A0 =C2=A0 =C2=A0 feature=3Dcmd-feat2
>=C2=A0 another feature
> -=C2=A0 =C2=A0 section=3DNone
> +=C2=A0 =C2=A0 section=3DPlain
>=C2=A0 .. note:: @arg3 is undocumented
>=C2=A0 =C2=A0 =C2=A0 section=3DReturns
>=C2=A0 @Object
>=C2=A0 =C2=A0 =C2=A0 section=3DErrors
>=C2=A0 some
> -=C2=A0 =C2=A0 section=3DTODO
> +=C2=A0 =C2=A0 section=3DTodo

With the method-less Enum I suggested, this hunk would go away.=C2=A0 Not that it matters :)

>=C2=A0 frobnicate
> -=C2=A0 =C2=A0 section=3DNone
> +=C2=A0 =C2=A0 section=3DPlain
>=C2=A0 .. admonition:: Notes
>=C2=A0
>=C2=A0 =C2=A0- Lorem ipsum dolor sit amet
> @@ -212,7 +212,7 @@ If you're bored enough to read this, go see a = video of boxed cats
>=C2=A0 a feature
>=C2=A0 =C2=A0 =C2=A0 feature=3Dcmd-feat2
>=C2=A0 another feature
> -=C2=A0 =C2=A0 section=3DNone
> +=C2=A0 =C2=A0 section=3DPlain
>=C2=A0 .. qmp-example::
>=C2=A0
>=C2=A0 =C2=A0 =C2=A0-> "this example"
> diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-q= api.py
> index 7e3f9f4aa1f..bca924309be 100755
> --- a/tests/qapi-schema/test-qapi.py
> +++ b/tests/qapi-schema/test-qapi.py
> @@ -131,7 +131,7 @@ def test_frontend(fname):
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 for feat, section in doc.features.it= ems():
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 print('=C2=A0 =C2= =A0 feature=3D%s\n%s' % (feat, section.text))
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 for section in doc.sections:
> -=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 print('=C2=A0 =C2=A0 se= ction=3D%s\n%s' % (section.tag, section.text))
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 print('=C2=A0 =C2=A0 se= ction=3D%s\n%s' % (section.kind, section.text))
>=C2=A0
>=C2=A0
>=C2=A0 def open_test_result(dir_name, file_name, update):

--000000000000c7a377062fa4845d--