Re: [Xen-devel] [PATCH 2/3] xen: hypercall docs annotations for xen_sysctl_cpupool_op

[Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>]

Dario Faggioli writes ("Re: [PATCH 2/3] xen: hypercall docs annotations for 
xen_sysctl_cpupool_op"):
> On Thu, 2016-04-14 at 18:07 +0100, Ian Jackson wrote:
> > Signed-off-by: Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>
> > CC: Jan Beulich <jbeulich@xxxxxxxx>
> > CC: Tim Deegan <tim@xxxxxxx>
> >
> Reviewed-by: Dario Faggioli <dario.faggioli@xxxxxxxxxx>
> 
> One thing, out of curiosity. This syntax, here:
> 
> > -/* XEN_SYSCTL_cpupool_op */
> > +/* ` enum XEN_SYSCTL_cpupool_op { */
...
> > +    uint32_t op;          /* IN ` enum XEN_SYSCTL_cpupool_op ` */
> >
> and here, is I guess useful to the hypercall HTML docs generator, as
> mentioned in the cover letter?

Yes.  Observe that here
  http://xenbits.xen.org/docs/unstable/hypercall/x86_64/index.html
does not contain an entry for the cpupool ops in the section
"Enums and sets of #defines".  And it doesn't even formally state that
the `op' in that struct is one of the XEN_SYSCTL_cpupool_op values -
although the reader will probably guess that that's the case.

The extra markup syntax is pretty minimal and is documented at the top
of the script
  docs/xen-headers

> It is not something we do in many other places (if at all, at least in
> this file)... If it is, I'll happily add to my TODO list to convert
> more entries to it.

Ideally I would like to see all hypercalls and all their arguments
documented properly.  That includes annotating them for the html
cross-reference generator.  But it also includes documenting their
semantics and their error conditions.

Unfortunately, we are starting from a rather sketchy baseline.

Thanks for the offer to help!

Ian.

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel