Re: [Xen-devel] Xen document day (Oct 12 or 26)

[Ian Campbell <Ian.Campbell@xxxxxxxxxxxxx>]

On Wed, 2011-09-28 at 14:48 +0100, Konrad Rzeszutek Wilk wrote:
> On Wed, Sep 28, 2011 at 02:26:31PM +0100, Ian Jackson wrote:
> > Ian Campbell writes ("Re: [Xen-devel] Xen document day (Oct 12 or 26)"):
> > > Since the guest APIs are stable there should be relatively little churn
> > > so perhaps a wiki page (or even series of pages) would be appropriate
> > > for this sort of thing?
> > 
> > I want this to be in-tree.  If it's in-tree, we can refuse patches
> > which do not update the documentation.
> > 
> > > I think this would be good too and in fact even more important than the
> > > interface documentation. Everyone needs to be able to build Xen to hack
> > > on it but only a subset need to know any particular API.
> > > 
> > > Also although we recommend that users consume Xen via their distro where
> > > possible such a guide would also help any who would rather build from
> > > scratch (e.g. because we've asked them to "try the latest version" or to
> > > bisect a bug etc).
> > 
> > This would be a good candidate for a wiki page, backed up by revisions
> > of the in-tree README.
> 
> 
> Any recommendations on what would be a good format to write these "interface"
> pages in?

For in-line (i.e. in xen/include/public/*.h) docs of APIs I played a
little bit with integrating kernel-doc into the Xen build system but it
is tied a little too closely to the kernel build infrastructure.

Doxygen seems like a plausible alternative with life outside the kernel
etc. We actually appear to already have some doxygen stuff for the
pytyhon stuff (judging from the Makefile, I've not actually noticed the
structured code comments anywhere)

For non-inline docs I think we decided that markdown would be a good
answer.

Ian.


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