Re: [Qemu-devel] [PATCH v5 18/22] s390x: implement query-hotpluggable-cpus

[Markus Armbruster]

Cornelia Huck <address@hidden> writes:

> On Wed, 04 Oct 2017 14:42:55 +0200
> Markus Armbruster <address@hidden> wrote:
>
>> Cornelia Huck <address@hidden> writes:
>> 
>> > On Mon, 02 Oct 2017 09:46:41 +0200
>> > Markus Armbruster <address@hidden> wrote:
>> >  
>> >> David Hildenbrand <address@hidden> writes:
>> >>   
>> >> > CPU hotplug is only possible on a per core basis on s390x. So let's
>> >> > add possible_cpus and properly wire everything up.
>> >> >
>> >> > Signed-off-by: David Hildenbrand <address@hidden>    
>> >> [...]  
>> >> > diff --git a/qapi-schema.json b/qapi-schema.json
>> >> > index f3af2cb851..79e9f85404 100644
>> >> > --- a/qapi-schema.json
>> >> > +++ b/qapi-schema.json
>> >> > @@ -3121,6 +3121,22 @@
>> >> >  #      }
>> >> >  #    ]}
>> >> >  #
>> >> > +# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu 
>> >> > qemu
>> >> > +# (Since: 2.11):
>> >> > +#
>> >> > +# -> { "execute": "query-hotpluggable-cpus" }
>> >> > +# <- {"return": [
>> >> > +#      {
>> >> > +#         "type": "qemu-s390-cpu", "vcpus-count": 1,
>> >> > +#         "props": { "core-id": 1 }
>> >> > +#      },
>> >> > +#      {
>> >> > +#         "qom-path": "/machine/unattached/device[0]",
>> >> > +#         "type": "qemu-s390-cpu", "vcpus-count": 1,
>> >> > +#         "props": { "core-id": 0 }
>> >> > +#      }
>> >> > +#    ]}
>> >> > +#
>> >> >  ##
>> >> >  { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'] 
>> >> > }    
>> >> 
>> >> Please stick in '# Example:' like we do in query-hotpluggable-cpus's doc
>> >> comment.  I expect the generated documentation to be illegible[*]
>> >> without it.  
>> >
>> > Should '# Example:' go before each of the examples (instead of the
>> > beginning of the example block), then?  
>> 
>> Whatever makes the generated documentation look better.
>
> The pdf indeed looks ugly, but that's a preexisting problem, and adding
> more '# Example:' lines does not really help.
>
> The basic issue is that the code expects just one example and no
> additional text for the '# Example:' tag -- the explaining text for the
> various statements ends up looking like the qmp examples. That should
> be improved before doing a patch on top for this command (and I don't
> really have the skills or time to improve the output, sorry.)

Marc-André, any ideas?