[Xen-devel] [PATCH 0 of 8 DOCDAY] setup Doxygen for use with hypercall interface headers

[Ian Campbell <ian.campbell@xxxxxxxxxx>]

The following series sets up a Doxygen run over xen/include/public and
makes a start at documenting some hypercalls.

I only did mmuext_op so far since I wanted to validate the approach
with the list before persisting any further. I'm not that convinced by
the effect on the readability of the headers but hopefully this is
offset by the ability to generate nice HTML docs?

I hope that this can eventually replace the extremely out of date
(although it's actualy not aged that badly in parts, I've stolen a
paragraph or two already) interfaces.tex with something which people
might actually keep up to date.

One quirk is that hypercalls are generally defined by #defines and
structs and not by actual function calls which does not play well to
Doxygen's strengths. I decided to do the following:
#ifdef __DOXYGEN__
int HYPERVISOR_mmuext_op(
    XEN_GUEST_HANDLE(mmuext_op_t) uops,
    unsigned int count,
    XEN_GUEST_HANDLE(uint) pdone,
    unsigned int foreigndom);
#endif

Combined with creating a Doxygen group for each hypercall (in order to
pull all the #defines etc in to one page) it comes out looking OK:
http://xenbits.xen.org/people/ianc/docs/group__HYPERVISOR__mmuext__op.html

Any thoughts or shall I move onto the next hypercall?


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel