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 DE5F0C2BA1A for ; Thu, 20 Jun 2024 15:40:39 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sKJtH-0000QM-At; Thu, 20 Jun 2024 11:39:59 -0400 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 1sKJtF-0000PV-Mw for qemu-devel@nongnu.org; Thu, 20 Jun 2024 11:39:57 -0400 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 1sKJtA-0002pY-Ll for qemu-devel@nongnu.org; Thu, 20 Jun 2024 11:39:56 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1718897991; 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=cbOqVbTycNjZyeGv5WvJWOarMSHPZdrqMQjU1gXziEU=; b=ivI0ruci4OgbUXMu29YEuG21yzsup3VAy/VbpVDgr+XD9hzaUwffs+ES+mfmdHyTgQRd6t aL2rJICZkI7Izp6TD0ec1h46ogKxmi9jHh74qYTdWDDeFLHQs/QiVvoh2QwpvFHU6RVHrJ UvDxOPdzmj/llC+/M63xvjxaNK/2ToM= 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-398-WlA0PsYRP16pAH7LKhx1Rw-1; Thu, 20 Jun 2024 11:39:49 -0400 X-MC-Unique: WlA0PsYRP16pAH7LKhx1Rw-1 Received: by mail-pj1-f69.google.com with SMTP id 98e67ed59e1d1-2c7a6ce23c2so1156339a91.3 for ; Thu, 20 Jun 2024 08:39:49 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1718897988; x=1719502788; 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=cbOqVbTycNjZyeGv5WvJWOarMSHPZdrqMQjU1gXziEU=; b=tZxQM/PIbWR53ooNzyEi0HDWYqXjNxzU/yI5oUmOeLPpks4f2ytdniUboN0gvXZHuP dYAzvMUGMJu6FlM3T0PB0F7vIY4LlcWnUbScHWIDe3oQMxKSbKnpnBh6FEKrPfQOdYKG Se3xBayX+jV2+4PXlutznqOGjoJaMb18aBYon9CKe+1sfPvgmzh3zc61D+X04p1H5gqp lqxuouCFlpLhuKq/y/m6Tl3ZljZgSKCS0mNV5lEzKJCzxxSKXcIpbUFquAC5mM04V3w+ gi9WTfaBEWrk3PGKNSRXR6EMGuqwoiVMhYnwuqt2I6oIpmxHmUcCaV2EF9LaWndFznjJ mUrw== X-Gm-Message-State: AOJu0YwACdgvds1zbvsCeQKWRnWnJrSwV2UNY6YyNaq9wtLmtTAo1EUx S0xdfxMJ30QhowwnKXA5w0dMeuzCApYZ9gdYjZK+RAjjFM7zgv9FB+XDyl53tTbXn1myi04FNUP gncBTTmosEtTf3EVglixnfvD/Te3qUbywWgtNh17/B2HnmuH3wkVoBqXf6DR4DvCg0KqAXM31Hz fZumULAwt9OcEtlREeto8tpOSe9mw= X-Received: by 2002:a17:90a:1281:b0:2c8:7ea:8f45 with SMTP id 98e67ed59e1d1-2c807ea8fc3mr913455a91.35.1718897988466; Thu, 20 Jun 2024 08:39:48 -0700 (PDT) X-Google-Smtp-Source: AGHT+IHzpz1FluVltnFauwLqKzfOCxunJJuZBCTH5RMxfFRkgve9DRJkXjtDA8oDJPaDRmWX9zhjL5EqaJQcNClWBpM= X-Received: by 2002:a17:90a:1281:b0:2c8:7ea:8f45 with SMTP id 98e67ed59e1d1-2c807ea8fc3mr913408a91.35.1718897987950; Thu, 20 Jun 2024 08:39:47 -0700 (PDT) MIME-Version: 1.0 References: <20240619003012.1753577-1-jsnow@redhat.com> <20240619003012.1753577-10-jsnow@redhat.com> <87wmmlyu64.fsf@pond.sub.org> In-Reply-To: <87wmmlyu64.fsf@pond.sub.org> From: John Snow Date: Thu, 20 Jun 2024 11:39:35 -0400 Message-ID: Subject: Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST To: Markus Armbruster Cc: qemu-devel , Stefan Hajnoczi , Hanna Reitz , Michael Roth , =?UTF-8?Q?Philippe_Mathieu=2DDaud=C3=A9?= , Victor Toso de Carvalho , "Michael S. Tsirkin" , Konstantin Kostiuk , Yanan Wang , Pavel Dovgalyuk , =?UTF-8?B?TWFyYy1BbmRyw6kgTHVyZWF1?= , Marcel Apfelbaum , Fabiano Rosas , Lukas Straub , Eduardo Habkost , Mads Ynddal , =?UTF-8?Q?Daniel_P=2E_Berrang=C3=A9?= , Gerd Hoffmann , Stefan Berger , Peter Xu , Igor Mammedov , =?UTF-8?Q?C=C3=A9dric_Le_Goater?= , Jason Wang , Ani Sinha , Paolo Bonzini , Peter Maydell , Qemu-block , Jiri Pirko , Alex Williamson , Kevin Wolf , Eric Blake Content-Type: multipart/alternative; boundary="000000000000fa2e3d061b541f93" 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.152, 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_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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 --000000000000fa2e3d061b541f93 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Wed, Jun 19, 2024, 8:49=E2=80=AFAM Markus Armbruster = wrote: > John Snow writes: > > > We do not need a dedicated section for notes. By eliminating a speciall= y > > parsed section, these notes can be treated as normal rST paragraphs in > > the new QMP reference manual, and can be placed and styled much more > > flexibly. > > > > Convert all existing "Note" and "Notes" sections to pure rST. As part o= f > > the conversion, capitalize the first letter of each sentence and add > > trailing punctuation where appropriate to ensure notes look sensible an= d > > consistent in rendered HTML documentation. > > > > Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and ..= . > > > > ... Update the QAPI parser to prohibit "Note" sections while suggesting > > Scratch "... ..." and downcase "Update"? > > > a new syntax. The exact formatting to use is a matter of taste, but a > > good candidate is simply: > > > > .. note:: lorem ipsum ... > > > > ... but there are other choices, too. The Sphinx readthedocs theme > > offers theming for the following forms (capitalization unimportant); al= l > > are adorned with a (!) symbol in the title bar for rendered HTML docs. > > > > See > > > https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admoniti= ons > > for examples of each directive/admonition in use. > > > > These are rendered in orange: > > > > .. Attention:: ... > > .. Caution:: ... > > .. WARNING:: ... > > > > These are rendered in red: > > > > .. DANGER:: ... > > .. Error:: ... > > > > These are rendered in green: > > > > .. Hint:: ... > > .. Important:: ... > > .. Tip:: ... > > > > These are rendered in blue: > > > > .. Note:: ... > > .. admonition:: custom title > > > > admonition body text > > > > This patch uses ".. note::" almost everywhere, with just two "caution" > > directives. ".. admonition:: notes" is used in a few places where we ha= d > > an ordered list of multiple notes that would not make sense as > > standalone/separate admonitions. > > > > Signed-off-by: John Snow > > Acked-by: Stefan Hajnoczi [for block*.json] > > [...] > > > diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json > > index b3de1fb6b3a..57598331c5c 100644 > > --- a/qga/qapi-schema.json > > +++ b/qga/qapi-schema.json > > @@ -422,8 +422,9 @@ > > # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined > > # below) > > # > > -# Note: This may fail to properly report the current state as a result > > -# of some other guest processes having issued an fs freeze/thaw. > > +# .. note:: This may fail to properly report the current state as a > > +# result of some other guest processes having issued an fs > > +# freeze/thaw. > > # > > # Since: 0.15.0 > > ## > > @@ -443,9 +444,9 @@ > > # > > # Returns: Number of file systems currently frozen. > > # > > -# Note: On Windows, the command is implemented with the help of a > > -# Volume Shadow-copy Service DLL helper. The frozen state is > > -# limited for up to 10 seconds by VSS. > > +# .. note:: On Windows, the command is implemented with the help of a > > +# Volume Shadow-copy Service DLL helper. The frozen state is limit= ed > > +# for up to 10 seconds by VSS. > > # > > # Since: 0.15.0 > > ## > > @@ -479,10 +480,10 @@ > > # > > # Returns: Number of file systems thawed by this call > > # > > -# Note: if return value does not match the previous call to > > -# guest-fsfreeze-freeze, this likely means some freezable > > -# filesystems were unfrozen before this call, and that the > > -# filesystem state may have changed before issuing this command. > > +# .. note:: If return value does not match the previous call to > > +# guest-fsfreeze-freeze, this likely means some freezable filesyste= ms > > +# were unfrozen before this call, and that the filesystem state may > > +# have changed before issuing this command. > > # > > # Since: 0.15.0 > > ## > > @@ -560,8 +561,8 @@ > > # Errors: > > # - If suspend to disk is not supported, Unsupported > > # > > -# Notes: It's strongly recommended to issue the guest-sync command > > -# before sending commands when the guest resumes > > +# .. note:: It's strongly recommended to issue the guest-sync command > > +# before sending commands when the guest resumes. > > # > > # Since: 1.1 > > ## > > @@ -596,8 +597,8 @@ > > # Errors: > > # - If suspend to ram is not supported, Unsupported > > # > > -# Notes: It's strongly recommended to issue the guest-sync command > > -# before sending commands when the guest resumes > > +# .. note:: It's strongly recommended to issue the guest-sync command > > +# before sending commands when the guest resumes. > > # > > # Since: 1.1 > > ## > > @@ -631,8 +632,8 @@ > > # Errors: > > # - If hybrid suspend is not supported, Unsupported > > # > > -# Notes: It's strongly recommended to issue the guest-sync command > > -# before sending commands when the guest resumes > > +# .. note:: It's strongly recommended to issue the guest-sync command > > +# before sending commands when the guest resumes. > > # > > # Since: 1.1 > > ## > > @@ -1461,16 +1462,15 @@ > > # * POSIX: as defined by os-release(5) > > # * Windows: contains string "server" or "client" > > # > > -# Notes: On POSIX systems the fields @id, @name, @pretty-name, > > -# @version, @version-id, @variant and @variant-id follow the > > -# definition specified in os-release(5). Refer to the manual page > > -# for exact description of the fields. Their values are taken > > -# from the os-release file. If the file is not present in the > > -# system, or the values are not present in the file, the fields > > -# are not included. > > +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, > > +# @version, @version-id, @variant and @variant-id follow the > > +# definition specified in os-release(5). Refer to the manual page f= or > > +# exact description of the fields. Their values are taken from the > > +# os-release file. If the file is not present in the system, or th= e > > +# values are not present in the file, the fields are not included. > > # > > -# On Windows the values are filled from information gathered from > > -# the system. > > +# On Windows the values are filled from information gathered from > > +# the system. > > Please don't change the indentation here. I get the same output with > > @@ -1461,7 +1462,7 @@ > # * POSIX: as defined by os-release(5) > # * Windows: contains string "server" or "client" > # > -# Notes: On POSIX systems the fields @id, @name, @pretty-name, > +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, > # @version, @version-id, @variant and @variant-id follow the > # definition specified in os-release(5). Refer to the manual page > # for exact description of the fields. Their values are taken > > > > # > > # Since: 2.10 > > ## > > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py > > index dfd6a6c5bee..53b06a94508 100644 > > --- a/scripts/qapi/parser.py > > +++ b/scripts/qapi/parser.py > > @@ -548,6 +548,21 @@ def get_doc(self) -> 'QAPIDoc': > > r'(Returns|Errors|Since|Notes?|Examples?|TODO)= : > *', > > line): > > # tagged section > > + > > + # TODO: Remove this error sometime in 2025 or so > > + # after we've fully transitioned to the new qapido= c > > + # generator. > > + > > + # See commit message for more markup suggestions > O:-) > > + if 'Note' in match.group(1): > > + emsg =3D ( > > + f"The '{match.group(1)}' section is no > longer " > > + "supported. Please use rST's '.. note::' o= r > " > > + "'.. admonition:: notes' directives, or > another " > > + "suitable admonition instead." > > + ) > > + raise QAPIParseError(self, emsg) > > + > > doc.new_tagged_section(self.info, match.group(1)) > > text =3D line[match.end():] > > if text: > > diff --git a/tests/qapi-schema/doc-empty-section.err > b/tests/qapi-schema/doc-empty-section.err > > index 5f03a6d733f..711a0d629c2 100644 > > --- a/tests/qapi-schema/doc-empty-section.err > > +++ b/tests/qapi-schema/doc-empty-section.err > > @@ -1 +1 @@ > > -doc-empty-section.json:6: text required after 'Note:' > > +doc-empty-section.json:6: text required after 'Errors:' > > diff --git a/tests/qapi-schema/doc-empty-section.json > b/tests/qapi-schema/doc-empty-section.json > > index f3384e9a3bb..f179d3eff6d 100644 > > --- a/tests/qapi-schema/doc-empty-section.json > > +++ b/tests/qapi-schema/doc-empty-section.json > > @@ -3,6 +3,6 @@ > > ## > > # @foo: > > # > > -# Note: > > +# Errors: > > ## > > { 'command': 'foo', 'data': {'a': 'int'} } > > diff --git a/tests/qapi-schema/doc-good.json > b/tests/qapi-schema/doc-good.json > > index 8b39eb946af..4b338cc0186 100644 > > --- a/tests/qapi-schema/doc-good.json > > +++ b/tests/qapi-schema/doc-good.json > > @@ -29,7 +29,7 @@ > > # - Second list > > # Note: still in list > > # > > -# Note: not in list > > +# .. note:: not in list > > Uh... see [*] below. > > > # > > # 1. Third list > > # is numbered > > @@ -157,7 +157,7 @@ > > # @cmd-feat1: a feature > > # @cmd-feat2: another feature > > # > > -# Note: @arg3 is undocumented > > +# .. note:: @arg3 is undocumented > > # > > # Returns: @Object > > # > > @@ -165,7 +165,7 @@ > > # > > # TODO: frobnicate > > # > > -# Notes: > > +# .. admonition:: Notes > > # > > # - Lorem ipsum dolor sit amet > > # - Ut enim ad minim veniam > > diff --git a/tests/qapi-schema/doc-good.out > b/tests/qapi-schema/doc-good.out > > index 435f6e6d768..2c9b4e419cb 100644 > > --- a/tests/qapi-schema/doc-good.out > > +++ b/tests/qapi-schema/doc-good.out > > @@ -76,7 +76,7 @@ Not in list > > - Second list > > Note: still in list > > > > -Note: not in list > > [*] This demonstrates the "Note: ..." is *not* recognized as a "Note" > section before the patch (compare to the change we get for recognized > sections below). > > Obscure fact: the doc parser recognizes tagged sections *only* in > definition documentation. Arguably a misfeature. > > Your series makes the misfeature even more obscure, because afterwards, > the only tagged section left that could make sense in a free-form doc > comment is "TODO". Let's not worry about the misfeature now. > Right, it's gonna go away or be heavily reduced. A fish for another fry. > Two sensible solutions: > > 1. Since the patch converts tagged sections, and this isn't, don't touch > it. If you feel you want to mention this in the commit message, go > ahead. > Oh, uh. Alright. I wonder why I changed it then. I thought I was playing error message whackamole with this one, but maybe I did do a regexp at some point. I'll leave it be if I can. If I can't, for some reason, then ... > 2. Touch it anyway. Do mention it in the commit message then. > ... This, with why I couldn't leave it be. > > +.. note:: not in list > > > > 1. Third list > > is numbered > > @@ -169,15 +169,17 @@ description starts on the same line > > a feature > > feature=3Dcmd-feat2 > > another feature > > - section=3DNote > > -@arg3 is undocumented > > + section=3DNone > > +.. note:: @arg3 is undocumented > > section=3DReturns > > @Object > > section=3DErrors > > some > > section=3DTODO > > frobnicate > > - section=3DNotes > > + section=3DNone > > +.. admonition:: Notes > > + > > - Lorem ipsum dolor sit amet > > - Ut enim ad minim veniam > > > > diff --git a/tests/qapi-schema/doc-good.txt > b/tests/qapi-schema/doc-good.txt > > index 847db70412d..b89f35d5476 100644 > > --- a/tests/qapi-schema/doc-good.txt > > +++ b/tests/qapi-schema/doc-good.txt > > @@ -17,7 +17,9 @@ Not in list > > > > * Second list Note: still in list > > > > -Note: not in list > > +Note: > > + > > + not in list > > > > 1. Third list is numbered > > > > @@ -193,11 +195,9 @@ Features > > "cmd-feat2" > > another feature > > > > +Note: > > > > -Note > > -~~~~ > > - > > -"arg3" is undocumented > > + "arg3" is undocumented > > > > > > Returns > > @@ -211,9 +211,7 @@ Errors > > > > some > > > > - > > -Notes > > -~~~~~ > > +Notes: > > > > * Lorem ipsum dolor sit amet > > > > diff --git a/tests/qapi-schema/doc-interleaved-section.json > b/tests/qapi-schema/doc-interleaved-section.json > > index adb29e98daa..b26bc0bbb79 100644 > > --- a/tests/qapi-schema/doc-interleaved-section.json > > +++ b/tests/qapi-schema/doc-interleaved-section.json > > @@ -10,7 +10,7 @@ > > # > > # bao > > # > > -# Note: a section. > > +# Returns: a section. > > # > > # @foobar: catch this > > # > > "Returns:" is only valid for commands, and this is a struct. Let's use > "TODO:" instead. > Weird that it didn't prohibit it. Bug? --js > --000000000000fa2e3d061b541f93 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


On Wed, Jun 19, 2024, 8:49=E2=80=AFAM Markus Armbruste= r <armbru@redhat.com> wrote:=
John Snow <jsnow@redhat.com&g= t; writes:

> We do not need a dedicated section for notes. By eliminating a special= ly
> parsed section, these notes can be treated as normal rST paragraphs in=
> the new QMP reference manual, and can be placed and styled much more > flexibly.
>
> Convert all existing "Note" and "Notes" sections t= o pure rST. As part of
> the conversion, capitalize the first letter of each sentence and add > trailing punctuation where appropriate to ensure notes look sensible a= nd
> consistent in rendered HTML documentation.
>
> Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and .= ..
>
> ... Update the QAPI parser to prohibit "Note" sections while= suggesting

Scratch "... ..." and downcase "Update"?

> a new syntax. The exact formatting to use is a matter of taste, but a<= br> > good candidate is simply:
>
> .. note:: lorem ipsum ...
>
> ... but there are other choices, too. The Sphinx readthedocs theme
> offers theming for the following forms (capitalization unimportant); a= ll
> are adorned with a (!) symbol in the title bar for rendered HTML docs.=
>
> See
> https://= sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions > for examples of each directive/admonition in use.
>
> These are rendered in orange:
>
> .. Attention:: ...
> .. Caution:: ...
> .. WARNING:: ...
>
> These are rendered in red:
>
> .. DANGER:: ...
> .. Error:: ...
>
> These are rendered in green:
>
> .. Hint:: ...
> .. Important:: ...
> .. Tip:: ...
>
> These are rendered in blue:
>
> .. Note:: ...
> .. admonition:: custom title
>
>=C2=A0 =C2=A0 admonition body text
>
> This patch uses ".. note::" almost everywhere, with just two= "caution"
> directives. ".. admonition:: notes" is used in a few places = where we had
> an ordered list of multiple notes that would not make sense as
> standalone/separate admonitions.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*= .json]

[...]

> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
> index b3de1fb6b3a..57598331c5c 100644
> --- a/qga/qapi-schema.json
> +++ b/qga/qapi-schema.json
> @@ -422,8 +422,9 @@
>=C2=A0 # Returns: GuestFsfreezeStatus ("thawed", "frozen= ", etc., as defined
>=C2=A0 #=C2=A0 =C2=A0 =C2=A0below)
>=C2=A0 #
> -# Note: This may fail to properly report the current state as a resul= t
> -#=C2=A0 =C2=A0 =C2=A0of some other guest processes having issued an f= s freeze/thaw.
> +# .. note:: This may fail to properly report the current state as a > +#=C2=A0 =C2=A0 result of some other guest processes having issued an = fs
> +#=C2=A0 =C2=A0 freeze/thaw.
>=C2=A0 #
>=C2=A0 # Since: 0.15.0
>=C2=A0 ##
> @@ -443,9 +444,9 @@
>=C2=A0 #
>=C2=A0 # Returns: Number of file systems currently frozen.
>=C2=A0 #
> -# Note: On Windows, the command is implemented with the help of a
> -#=C2=A0 =C2=A0 =C2=A0Volume Shadow-copy Service DLL helper.=C2=A0 The= frozen state is
> -#=C2=A0 =C2=A0 =C2=A0limited for up to 10 seconds by VSS.
> +# .. note:: On Windows, the command is implemented with the help of a=
> +#=C2=A0 =C2=A0 Volume Shadow-copy Service DLL helper.=C2=A0 The froze= n state is limited
> +#=C2=A0 =C2=A0 for up to 10 seconds by VSS.
>=C2=A0 #
>=C2=A0 # Since: 0.15.0
>=C2=A0 ##
> @@ -479,10 +480,10 @@
>=C2=A0 #
>=C2=A0 # Returns: Number of file systems thawed by this call
>=C2=A0 #
> -# Note: if return value does not match the previous call to
> -#=C2=A0 =C2=A0 =C2=A0guest-fsfreeze-freeze, this likely means some fr= eezable
> -#=C2=A0 =C2=A0 =C2=A0filesystems were unfrozen before this call, and = that the
> -#=C2=A0 =C2=A0 =C2=A0filesystem state may have changed before issuing= this command.
> +# .. note:: If return value does not match the previous call to
> +#=C2=A0 =C2=A0 guest-fsfreeze-freeze, this likely means some freezabl= e filesystems
> +#=C2=A0 =C2=A0 were unfrozen before this call, and that the filesyste= m state may
> +#=C2=A0 =C2=A0 have changed before issuing this command.
>=C2=A0 #
>=C2=A0 # Since: 0.15.0
>=C2=A0 ##
> @@ -560,8 +561,8 @@
>=C2=A0 # Errors:
>=C2=A0 #=C2=A0 =C2=A0 =C2=A0- If suspend to disk is not supported, Unsu= pported
>=C2=A0 #
> -# Notes: It's strongly recommended to issue the guest-sync comman= d
> -#=C2=A0 =C2=A0 =C2=A0before sending commands when the guest resumes > +# .. note:: It's strongly recommended to issue the guest-sync com= mand
> +#=C2=A0 =C2=A0 before sending commands when the guest resumes.
>=C2=A0 #
>=C2=A0 # Since: 1.1
>=C2=A0 ##
> @@ -596,8 +597,8 @@
>=C2=A0 # Errors:
>=C2=A0 #=C2=A0 =C2=A0 =C2=A0- If suspend to ram is not supported, Unsup= ported
>=C2=A0 #
> -# Notes: It's strongly recommended to issue the guest-sync comman= d
> -#=C2=A0 =C2=A0 =C2=A0before sending commands when the guest resumes > +# .. note:: It's strongly recommended to issue the guest-sync com= mand
> +#=C2=A0 =C2=A0 before sending commands when the guest resumes.
>=C2=A0 #
>=C2=A0 # Since: 1.1
>=C2=A0 ##
> @@ -631,8 +632,8 @@
>=C2=A0 # Errors:
>=C2=A0 #=C2=A0 =C2=A0 =C2=A0- If hybrid suspend is not supported, Unsup= ported
>=C2=A0 #
> -# Notes: It's strongly recommended to issue the guest-sync comman= d
> -#=C2=A0 =C2=A0 =C2=A0before sending commands when the guest resumes > +# .. note:: It's strongly recommended to issue the guest-sync com= mand
> +#=C2=A0 =C2=A0 before sending commands when the guest resumes.
>=C2=A0 #
>=C2=A0 # Since: 1.1
>=C2=A0 ##
> @@ -1461,16 +1462,15 @@
>=C2=A0 #=C2=A0 =C2=A0 =C2=A0* POSIX: as defined by os-release(5)
>=C2=A0 #=C2=A0 =C2=A0 =C2=A0* Windows: contains string "server&quo= t; or "client"
>=C2=A0 #
> -# Notes: On POSIX systems the fields @id, @name, @pretty-name,
> -#=C2=A0 =C2=A0 =C2=A0@version, @version-id, @variant and @variant-id = follow the
> -#=C2=A0 =C2=A0 =C2=A0definition specified in os-release(5). Refer to = the manual page
> -#=C2=A0 =C2=A0 =C2=A0for exact description of the fields.=C2=A0 Their= values are taken
> -#=C2=A0 =C2=A0 =C2=A0from the os-release file.=C2=A0 If the file is n= ot present in the
> -#=C2=A0 =C2=A0 =C2=A0system, or the values are not present in the fil= e, the fields
> -#=C2=A0 =C2=A0 =C2=A0are not included.
> +# .. note:: On POSIX systems the fields @id, @name, @pretty-name,
> +#=C2=A0 =C2=A0 @version, @version-id, @variant and @variant-id follow= the
> +#=C2=A0 =C2=A0 definition specified in os-release(5). Refer to the ma= nual page for
> +#=C2=A0 =C2=A0 exact description of the fields.=C2=A0 Their values ar= e taken from the
> +#=C2=A0 =C2=A0 os-release file.=C2=A0 If the file is not present in t= he system, or the
> +#=C2=A0 =C2=A0 values are not present in the file, the fields are not= included.
>=C2=A0 #
> -#=C2=A0 =C2=A0 =C2=A0On Windows the values are filled from informatio= n gathered from
> -#=C2=A0 =C2=A0 =C2=A0the system.
> +#=C2=A0 =C2=A0 On Windows the values are filled from information gath= ered from
> +#=C2=A0 =C2=A0 the system.

Please don't change the indentation here.=C2=A0 I get the same output w= ith

=C2=A0 @@ -1461,7 +1462,7 @@
=C2=A0 =C2=A0#=C2=A0 =C2=A0 =C2=A0* POSIX: as defined by os-release(5)
=C2=A0 =C2=A0#=C2=A0 =C2=A0 =C2=A0* Windows: contains string "server&q= uot; or "client"
=C2=A0 =C2=A0#
=C2=A0 -# Notes: On POSIX systems the fields @id, @name, @pretty-name,
=C2=A0 +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, =C2=A0 =C2=A0#=C2=A0 =C2=A0 =C2=A0@version, @version-id, @variant and @vari= ant-id follow the
=C2=A0 =C2=A0#=C2=A0 =C2=A0 =C2=A0definition specified in os-release(5). Re= fer to the manual page
=C2=A0 =C2=A0#=C2=A0 =C2=A0 =C2=A0for exact description of the fields.=C2= =A0 Their values are taken


>=C2=A0 #
>=C2=A0 # Since: 2.10
>=C2=A0 ##
> diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> index dfd6a6c5bee..53b06a94508 100644
> --- a/scripts/qapi/parser.py
> +++ b/scripts/qapi/parser.py
> @@ -548,6 +548,21 @@ 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 r'(Returns|Errors|Since|Notes?|Examples?|TODO): *&= #39;,
>=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 line):
>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 # tagged section
> +
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= # TODO: Remove this error sometime in 2025 or so
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= # after we've fully transitioned to the new qapidoc
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= # generator.
> +
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= # See commit message for more markup suggestions O:-)
> +=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0= if 'Note' in 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 emsg =3D (
> +=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 f"The '{match.group(1)}' section = is no longer "
> +=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 "supported. Please use rST's '.. = note::' or "
> +=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 "'.. admonition:: notes' directiv= es, or another "
> +=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 "suitable admonition instead."
> +=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 = =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:
> diff --git a/tests/qapi-schema/doc-empty-section.err b/tests/qapi-sche= ma/doc-empty-section.err
> index 5f03a6d733f..711a0d629c2 100644
> --- a/tests/qapi-schema/doc-empty-section.err
> +++ b/tests/qapi-schema/doc-empty-section.err
> @@ -1 +1 @@
> -doc-empty-section.json:6: text required after 'Note:'
> +doc-empty-section.json:6: text required after 'Errors:'
> diff --git a/tests/qapi-schema/doc-empty-section.json b/tests/qapi-sch= ema/doc-empty-section.json
> index f3384e9a3bb..f179d3eff6d 100644
> --- a/tests/qapi-schema/doc-empty-section.json
> +++ b/tests/qapi-schema/doc-empty-section.json
> @@ -3,6 +3,6 @@
>=C2=A0 ##
>=C2=A0 # @foo:
>=C2=A0 #
> -# Note:
> +# Errors:
>=C2=A0 ##
>=C2=A0 { 'command': 'foo', 'data': {'a'= : 'int'} }
> diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-g= ood.json
> index 8b39eb946af..4b338cc0186 100644
> --- a/tests/qapi-schema/doc-good.json
> +++ b/tests/qapi-schema/doc-good.json
> @@ -29,7 +29,7 @@
>=C2=A0 # - Second list
>=C2=A0 #=C2=A0 =C2=A0Note: still in list
>=C2=A0 #
> -# Note: not in list
> +# .. note:: not in list

Uh...=C2=A0 see [*] below.

>=C2=A0 #
>=C2=A0 # 1. Third list
>=C2=A0 #=C2=A0 =C2=A0 is numbered
> @@ -157,7 +157,7 @@
>=C2=A0 # @cmd-feat1: a feature
>=C2=A0 # @cmd-feat2: another feature
>=C2=A0 #
> -# Note: @arg3 is undocumented
> +# .. note:: @arg3 is undocumented
>=C2=A0 #
>=C2=A0 # Returns: @Object
>=C2=A0 #
> @@ -165,7 +165,7 @@
>=C2=A0 #
>=C2=A0 # TODO: frobnicate
>=C2=A0 #
> -# Notes:
> +# .. admonition:: Notes
>=C2=A0 #
>=C2=A0 #=C2=A0 - Lorem ipsum dolor sit amet
>=C2=A0 #=C2=A0 - Ut enim ad minim veniam
> diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-go= od.out
> index 435f6e6d768..2c9b4e419cb 100644
> --- a/tests/qapi-schema/doc-good.out
> +++ b/tests/qapi-schema/doc-good.out
> @@ -76,7 +76,7 @@ Not in list
>=C2=A0 - Second list
>=C2=A0 =C2=A0 Note: still in list
>=C2=A0
> -Note: not in list

[*] This demonstrates the "Note: ..." is *not* recognized as a &q= uot;Note"
section before the patch (compare to the change we get for recognized
sections below).

Obscure fact: the doc parser recognizes tagged sections *only* in
definition documentation.=C2=A0 Arguably a misfeature.

Your series makes the misfeature even more obscure, because afterwards,
the only tagged section left that could make sense in a free-form doc
comment is "TODO".=C2=A0 Let's not worry about the misfeature= now.

Right, it's gonna go away or be heavily reduced. A fish for anothe= r fry.


Two sensible solutions:

1. Since the patch converts tagged sections, and this isn't, don't = touch
it.=C2=A0 If you feel you want to mention this in the commit message, go ahead.

Oh, uh. Alright. I wonder why I changed it then. I thought I was play= ing error message whackamole with this one, but maybe I did do a regexp at = some point.

I'll lea= ve it be if I can. If I can't, for some reason, then ...


2. Touch it anyway.=C2=A0 Do mention it in the commit message then.

... This= , with why I couldn't leave it be.


> +.. note:: not in list
>=C2=A0
>=C2=A0 1. Third list
>=C2=A0 =C2=A0 =C2=A0is numbered
> @@ -169,15 +169,17 @@ 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=3DNote
> -@arg3 is undocumented
> +=C2=A0 =C2=A0 section=3DNone
> +.. 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 =C2=A0 section=3DTODO
>=C2=A0 frobnicate
> -=C2=A0 =C2=A0 section=3DNotes
> +=C2=A0 =C2=A0 section=3DNone
> +.. admonition:: Notes
> +
>=C2=A0 =C2=A0- Lorem ipsum dolor sit amet
>=C2=A0 =C2=A0- Ut enim ad minim veniam
>=C2=A0
> diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-go= od.txt
> index 847db70412d..b89f35d5476 100644
> --- a/tests/qapi-schema/doc-good.txt
> +++ b/tests/qapi-schema/doc-good.txt
> @@ -17,7 +17,9 @@ Not in list
>=C2=A0
>=C2=A0 * Second list Note: still in list
>=C2=A0
> -Note: not in list
> +Note:
> +
> +=C2=A0 not in list
>=C2=A0
>=C2=A0 1. Third list is numbered
>=C2=A0
> @@ -193,11 +195,9 @@ Features
>=C2=A0 "cmd-feat2"
>=C2=A0 =C2=A0 =C2=A0another feature
>=C2=A0
> +Note:
>=C2=A0
> -Note
> -~~~~
> -
> -"arg3" is undocumented
> +=C2=A0 "arg3" is undocumented
>=C2=A0
>=C2=A0
>=C2=A0 Returns
> @@ -211,9 +211,7 @@ Errors
>=C2=A0
>=C2=A0 some
>=C2=A0
> -
> -Notes
> -~~~~~
> +Notes:
>=C2=A0
>=C2=A0 * Lorem ipsum dolor sit amet
>=C2=A0
> diff --git a/tests/qapi-schema/doc-interleaved-section.json b/tests/qa= pi-schema/doc-interleaved-section.json
> index adb29e98daa..b26bc0bbb79 100644
> --- a/tests/qapi-schema/doc-interleaved-section.json
> +++ b/tests/qapi-schema/doc-interleaved-section.json
> @@ -10,7 +10,7 @@
>=C2=A0 #
>=C2=A0 #=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0bao
>=C2=A0 #
> -# Note: a section.
> +# Returns: a section.
>=C2=A0 #
>=C2=A0 # @foobar: catch this
>=C2=A0 #

"Returns:" is only valid for commands, and this is a struct.=C2= =A0 Let's use
"TODO:" instead.
Weird that it didn't prohibit it. Bug?
<= div dir=3D"auto">
--js
--000000000000fa2e3d061b541f93--