[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

Dario Faggioli writes ("Re: [PATCH 2/3] xen: hypercall docs annotations for 
> 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
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

> 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!


Xen-devel mailing list



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.