Re: [PATCH 01/14] qapi: BlockExportRemoveMode: move comments to TODO

[Victor Toso <victortoso@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 3659 bytes --]

Hi,

Many thanks for the quick review!

On Thu, Mar 24, 2022 at 04:34:42PM -0400, John Snow wrote:
> On Thu, Mar 24, 2022 at 1:50 PM Victor Toso <victortoso@redhat.com> wrote:
> >
> > @hide and @soft are potential additions which fits the TODO section
> > perfectly.
> >
> > The main motivation is to avoid this whole block of comment entering
> > the wrong section in the python parser.
> >
> > Signed-off-by: Victor Toso <victortoso@redhat.com>
> > ---
> >  qapi/block-export.json | 10 +++++-----
> >  1 file changed, 5 insertions(+), 5 deletions(-)
> >
> > diff --git a/qapi/block-export.json b/qapi/block-export.json
> > index f183522d0d..1e34927f85 100644
> > --- a/qapi/block-export.json
> > +++ b/qapi/block-export.json
> > @@ -219,13 +219,13 @@
> >  #
> >  # @hard: Drop all connections immediately and remove export.
> >  #
> > -# Potential additional modes to be added in the future:
> > +# TODO: Potential additional modes to be added in the future:
> >  #
> > -# hide: Just hide export from new clients, leave existing connections as is.
> > -# Remove export after all clients are disconnected.
> > +#       hide: Just hide export from new clients, leave existing connections as is.
> > +#       Remove export after all clients are disconnected.
> >  #
> > -# soft: Hide export from new clients, answer with ESHUTDOWN for all further
> > -# requests from existing clients.
> > +#       soft: Hide export from new clients, answer with ESHUTDOWN for all further
> > +#       requests from existing clients.
> >  #
> >  # Since: 2.12
> >  ##
> > --
> > 2.35.1
> >
> 
> Does this help with something in particular? (Got an example for me?)

I'm working on a Golang interface and I'm using the QAPI
documentation to document the Go's types of the QAPI spec. For this
kind of documentation, documentation related to future development
can be excluded. This patch helps me filter it out :)

Example:

  $ cd qemu/scripts && python
  >>> from qapi.schema import QAPISchema
  >>> schema = QAPISchema('../qapi/qapi-schema.json')

  # Without this patch, the 'Potential additional modes' doc is
  # under no specific named Section.
  >>> for s in schema._entity_dict['BlockExportRemoveMode'].doc.sections:
  ...     pprint(vars(s))
  ...
  {'_indent': 0,
   '_parser': <qapi.parser.QAPISchemaParser object at 0x7f4fcf854760>,
   'name': None,
   'text': 'Potential additional modes to be added in the future:\n'
           '\n'
           'hide: Just hide export from new clients, leave existing connections '
           'as is.\n'
           'Remove export after all clients are disconnected.\n'
           '\n'
           'soft: Hide export from new clients, answer with ESHUTDOWN for all '
           'further\n'
           'requests from existing clients.'}
   {'_indent': 7,
   '_parser': <qapi.parser.QAPISchemaParser object at 0x7f4fcf854760>,
   'name': 'Since',
   'text': '2.12'}

  # With this patch, we can filter out TODO section
  >>> pprint(schema._entity_dict['BlockExportRemoveMode'].doc.sections[0]))
  {'_indent': 6,
   '_parser': <qapi.parser.QAPISchemaParser object at 0x7f228d97e950>,
   'name': 'TODO',
   'text': 'Potential additional modes to be added in the future:\n'
           '\n'
           'hide: Just hide export from new clients, leave existing connections '
           'as is.\n'
           'Remove export after all clients are disconnected.\n'
           '\n'
           'soft: Hide export from new clients, answer with ESHUTDOWN for all '
           'further\n'
           'requests from existing clients.'}

Cheers,
Victor

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]