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.jack...@eu.citrix.com> > > CC: Jan Beulich <jbeul...@suse.com> > > CC: Tim Deegan <t...@xen.org> > > > Reviewed-by: Dario Faggioli <dario.faggi...@citrix.com> > > 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@lists.xen.org http://lists.xen.org/xen-devel