WARNING - OLD ARCHIVES

This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
   
 
 
Xen 
 
Home Products Support Community News
 
   
 

xen-devel

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

To: xen-devel@xxxxxxxxxxxxxxxxxxx
Subject: [Xen-devel] [PATCH 0 of 8 DOCDAY] setup Doxygen for use with hypercall interface headers
From: Ian Campbell <ian.campbell@xxxxxxxxxx>
Date: Wed, 26 Oct 2011 14:02:39 +0100
Cc: Ian Campbell <ian.campbell@xxxxxxxxxx>
Delivery-date: Wed, 26 Oct 2011 06:18:29 -0700
Envelope-to: www-data@xxxxxxxxxxxxxxxxxxx
List-help: <mailto:xen-devel-request@lists.xensource.com?subject=help>
List-id: Xen developer discussion <xen-devel.lists.xensource.com>
List-post: <mailto:xen-devel@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=unsubscribe>
Sender: xen-devel-bounces@xxxxxxxxxxxxxxxxxxx
User-agent: Mercurial-patchbomb/1.6.4
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