Re: [Qemu-devel] [PATCH v5 09/17] qapi: add some sections in docs

[Marc-André Lureau]

Hi

----- Original Message -----
> Second thoughts...
> 
> Marc-André Lureau <address@hidden> writes:
> 
> > Add some more section titles to organize the produced documents.
> >
> > Signed-off-by: Marc-André Lureau <address@hidden>
> > ---
> >  qapi-schema.json     |  4 ++++
> >  qapi/block-core.json |  6 ++++--
> >  qapi/block.json      | 10 ++++++++--
> >  qapi/common.json     |  6 ++++--
> >  qapi/crypto.json     |  5 ++++-
> >  qapi/event.json      |  6 ++++++
> >  qapi/rocker.json     |  4 ++++
> >  qapi/trace.json      |  3 +++
> >  8 files changed, 37 insertions(+), 7 deletions(-)
> >
> > diff --git a/qapi-schema.json b/qapi-schema.json
> > index dfe68ba..69340f2 100644
> > --- a/qapi-schema.json
> > +++ b/qapi-schema.json
> > @@ -20,6 +20,10 @@
> >  # QAPI introspection
> >  { 'include': 'qapi/introspect.json' }
> >  
> > +##
> > +# = QMP commands
> > +##
> > +
> >  ##
> >  # @qmp_capabilities:
> >  #
> > diff --git a/qapi/block-core.json b/qapi/block-core.json
> > index ec1da2a..05cedc3 100644
> > --- a/qapi/block-core.json
> > +++ b/qapi/block-core.json
> > @@ -1,6 +1,8 @@
> >  # -*- Mode: Python -*-
> > -#
> > -# QAPI block core definitions (vm unrelated)
> > +
> > +##
> > +# == QAPI block core definitions (vm unrelated)
> > +##
> >  
> >  # QAPI common definitions
> >  { 'include': 'common.json' }
> > diff --git a/qapi/block.json b/qapi/block.json
> > index 937df05..e4ad74b 100644
> > --- a/qapi/block.json
> > +++ b/qapi/block.json
> > @@ -1,10 +1,16 @@
> >  # -*- Mode: Python -*-
> > -#
> > -# QAPI block definitions (vm related)
> > +
> > +##
> > +# = QAPI block definitions
> > +##
> >  
> >  # QAPI block core definitions
> >  { 'include': 'block-core.json' }
> >  
> > +##
> > +# == QAPI block definitions (vm unrelated)
> > +##
> > +
> >  ##
> >  # @BiosAtaTranslation:
> >  #
> > diff --git a/qapi/common.json b/qapi/common.json
> > index 624a861..d93f159 100644
> > --- a/qapi/common.json
> > +++ b/qapi/common.json
> > @@ -1,6 +1,8 @@
> >  # -*- Mode: Python -*-
> > -#
> > -# QAPI common definitions
> > +
> > +##
> > +# = QAPI common definitions
> > +##
> >  
> >  ##
> >  # @QapiErrorClass:
> > diff --git a/qapi/crypto.json b/qapi/crypto.json
> > index 15d296e..1e517b0 100644
> > --- a/qapi/crypto.json
> > +++ b/qapi/crypto.json
> > @@ -1,6 +1,9 @@
> >  # -*- Mode: Python -*-
> >  #
> > -# QAPI crypto definitions
> > +
> > +##
> > +# = QAPI crypto definitions
> > +##
> >  
> >  ##
> >  # @QCryptoTLSCredsEndpoint:
> > diff --git a/qapi/event.json b/qapi/event.json
> > index 37bf34e..59942b0 100644
> > --- a/qapi/event.json
> > +++ b/qapi/event.json
> > @@ -1,3 +1,9 @@
> > +# -*- Mode: Python -*-
> > +
> > +##
> > +# = Events
> > +##
> > +
> 
> This suggests *all* events are in this section, which isn't the case.
> "Other events"?  "Core events"?  Dunno...

"Other events" sounds nice to me. I think we could improve the organization 
after. 

> >  ##
> >  # @SHUTDOWN:
> >  #
> > diff --git a/qapi/rocker.json b/qapi/rocker.json
> > index ace2776..dd72e02 100644
> > --- a/qapi/rocker.json
> > +++ b/qapi/rocker.json
> > @@ -1,4 +1,8 @@
> >  ##
> > +# = Rocker API
> 
> What about "Rocker switch device"?

ok

> 
> > +##
> > +
> > +##
> >  # @RockerSwitch:
> >  #
> >  # Rocker switch information.
> > diff --git a/qapi/trace.json b/qapi/trace.json
> > index 4fd39b7..3ad7df7 100644
> > --- a/qapi/trace.json
> > +++ b/qapi/trace.json
> > @@ -5,6 +5,9 @@
> >  # This work is licensed under the terms of the GNU GPL, version 2 or
> >  later.
> >  # See the COPYING file in the top-level directory.
> >  
> > +##
> > +# = Tracing commands
> > +##
> >  
> >  ##
> >  # @TraceEventState:
>