On Wed, Feb 12, 2025 at 4:37 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes:
>
> > This clarifies sections that are mistaken by the parser as "intro"
> > sections to be "details" sections instead.
>
> Impact on output? See notes inline.
>
It's very possible that there is none; in cases where the text is not
inlined, it won't make any visual difference. The occurrences in this patch
were identified with a warning from the generator that I didn't actually
submit as part of this patch series.
I was obeying an unseen master.
>
> >
> > Signed-off-by: John Snow <js...@redhat.com>
> > ---
> > qapi/machine.json | 2 ++
> > qapi/migration.json | 4 ++++
> > qapi/qom.json | 4 ++++
> > qapi/yank.json | 2 ++
> > scripts/qapi/parser.py | 8 ++++++++
> > 5 files changed, 20 insertions(+)
> >
> > diff --git a/qapi/machine.json b/qapi/machine.json
> > index a6b8795b09e..3c1b397f6cc 100644
> > --- a/qapi/machine.json
> > +++ b/qapi/machine.json
> > @@ -1301,6 +1301,8 @@
> > # Return the amount of initially allocated and present hotpluggable
> > # (if enabled) memory in bytes.
> > #
> > +# Details:
> > +#
> > # .. qmp-example::
> > #
> > # -> { "execute": "query-memory-size-summary" }
>
> Output unchanged in my testing. Same for the other hunks unless
> otherwise noted.
>
> > diff --git a/qapi/migration.json b/qapi/migration.json
> > index 43babd1df41..9070a91e655 100644
> > --- a/qapi/migration.json
> > +++ b/qapi/migration.json
> > @@ -1920,6 +1920,8 @@
> > #
> > # Xen uses this command to notify replication to trigger a checkpoint.
> > #
> > +# Details:
> > +#
> > # .. qmp-example::
> > #
> > # -> { "execute": "xen-colo-do-checkpoint" }
> > @@ -1993,6 +1995,8 @@
> > #
> > # Pause a migration. Currently it only supports postcopy.
> > #
> > +# Details:
> > +#
> > # .. qmp-example::
> > #
> > # -> { "execute": "migrate-pause" }
> > diff --git a/qapi/qom.json b/qapi/qom.json
> > index 11277d1f84c..5d285ef9239 100644
> > --- a/qapi/qom.json
> > +++ b/qapi/qom.json
> > @@ -729,6 +729,8 @@
> > #
> > # Properties for memory-backend-shm objects.
> > #
> > +# Details:
> > +#
> > # This memory backend supports only shared memory, which is the
> > # default.
> > #
>
> The paragraphs moves from above to below the auto-generated member
> documentation, like this:
>
> @@ -25908,13 +25908,13 @@ If
>
> Properties for memory-backend-shm objects.
>
> -This memory backend supports only shared memory, which is the default.
> -
>
> Members
> ~~~~~~~
>
> The members of "MemoryBackendProperties"
> +This memory backend supports only shared memory, which is the default.
> +
>
> Since
> ~~~~~
>
> This is sphinx-build -b text. I don't understand why there is no blank
> line between "The members of ... " and the moved paragraph.
>
... Me either! I'll investigate.
>
> > @@ -744,6 +746,8 @@
> > #
> > # Properties for memory-backend-epc objects.
> > #
> > +# Details:
> > +#
> > # The @merge boolean option is false by default with epc
> > #
> > # The @dump boolean option is false by default with epc
>
> Likewise.
>
> > diff --git a/qapi/yank.json b/qapi/yank.json
> > index 30f46c97c98..4d36d21e76a 100644
> > --- a/qapi/yank.json
> > +++ b/qapi/yank.json
> > @@ -104,6 +104,8 @@
> > #
> > # Returns: list of @YankInstance
> > #
> > +# Details:
> > +#
> > # .. qmp-example::
> > #
> > # -> { "execute": "query-yank" }
> > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> > index c5d2b950a82..5890a13b5ba 100644
> > --- a/scripts/qapi/parser.py
> > +++ b/scripts/qapi/parser.py
> > @@ -544,6 +544,14 @@ def _tag_check(what: str) -> None:
> > raise QAPIParseError(
> > self, 'feature descriptions expected')
> > have_tagged = True
> > + elif line == 'Details:':
> > + _tag_check("Details")
> > + self.accept(False)
> > + line = self.get_doc_line()
> > + while line == '':
> > + self.accept(False)
> > + line = self.get_doc_line()
> > + have_tagged = True
> > elif match := self._match_at_name_colon(line):
> > # description
> > if have_tagged:
>
>
