From: Ian Jackson <Ian.Jackson@eu.citrix.com>
To: Dario Faggioli <dario.faggioli@citrix.com>
Cc: Juergen Gross <jgross@suse.com>,
xen-devel@lists.xensource.com, Wei Liu <wei.liu2@citrix.com>,
George Dunlap <george.dunlap@eu.citrix.com>,
Tim Deegan <tim@xen.org>, Jan Beulich <jbeulich@suse.com>
Subject: Re: [PATCH 2/3] xen: hypercall docs annotations for xen_sysctl_cpupool_op
Date: Fri, 15 Apr 2016 11:27:43 +0100 [thread overview]
Message-ID: <22288.49695.993010.214036@mariner.uk.xensource.com> (raw)
In-Reply-To: <1460666240.13871.206.camel@citrix.com>
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@eu.citrix.com>
> > CC: Jan Beulich <jbeulich@suse.com>
> > CC: Tim Deegan <tim@xen.org>
> >
> Reviewed-by: Dario Faggioli <dario.faggioli@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
next prev parent reply other threads:[~2016-04-15 10:27 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-04-14 17:07 [PATCH 0/3] Revert xc cpupool retries and document anomaly Ian Jackson
2016-04-14 17:07 ` [PATCH 1/3] libxc: Revert "do some retries in xc_cpupool_removecpu() for EBUSY case" Ian Jackson
2016-04-15 5:15 ` Juergen Gross
2016-04-15 7:46 ` Dario Faggioli
2016-04-14 17:07 ` [PATCH 2/3] xen: hypercall docs annotations for xen_sysctl_cpupool_op Ian Jackson
2016-04-14 20:37 ` Dario Faggioli
2016-04-15 10:27 ` Ian Jackson [this message]
2016-04-14 17:07 ` [PATCH 3/3] xen: Document XEN_SYSCTL_CPUPOOL_OP_RMCPU anomalous EBUSY result Ian Jackson
2016-04-14 17:24 ` Andrew Cooper
2016-04-14 17:56 ` Ian Jackson
2016-04-14 20:22 ` Dario Faggioli
2016-04-15 10:20 ` Ian Jackson
2016-04-15 10:43 ` Juergen Gross
2016-04-15 10:58 ` Dario Faggioli
2016-04-15 11:37 ` Juergen Gross
2016-04-15 13:20 ` Juergen Gross
2016-04-15 13:33 ` Dario Faggioli
2016-04-15 14:11 ` Ian Jackson
2016-04-15 14:39 ` Juergen Gross
2016-04-15 5:35 ` Juergen Gross
2016-04-15 7:42 ` Dario Faggioli
2016-04-15 14:12 ` Ian Jackson
2016-04-15 14:17 ` Konrad Rzeszutek Wilk
2016-04-15 14:34 ` Juergen Gross
2016-04-15 14:44 ` Ian Jackson
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=22288.49695.993010.214036@mariner.uk.xensource.com \
--to=ian.jackson@eu.citrix.com \
--cc=dario.faggioli@citrix.com \
--cc=george.dunlap@eu.citrix.com \
--cc=jbeulich@suse.com \
--cc=jgross@suse.com \
--cc=tim@xen.org \
--cc=wei.liu2@citrix.com \
--cc=xen-devel@lists.xensource.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).