Re: [PATCH v2 0/15+5+5] Begin to disentangle libxenctrl and provide some stable libraries

[Ian Campbell <ian.campbell@citrix.com>]

On Wed, 2015-07-22 at 13:58 +0100, Andrew Cooper wrote:
> On 22/07/15 12:12, Ian Campbell wrote:
> > 
> > > FWIW, also splitting xl and libxl into different directories.
> > Yes, good idea (also "eventually ;-)").
> > 
> > While I'm accumulating TODO items in this thread, every library 
> > which
> > gets split out needs a careful review before it should be declared
> > A[PBI] stable. I'm thinking at least:
> > 
> >       * Consistent error handling (return -1 + setting errno=EFOO)
> >       * Correct types
> >       * Const correctness
> >       * General interface sanity check
> > 
> > Anything else?
> 
> If we are filling even more copious free time,
> 
> * Thoughts about documentation in the header files.

Yes, I think that would be good. As it happens the stuff being stripped
out is from among the better documented bits of libxc. Surely not
perfect though.

> I think a suitably-configured doxygen ought to suffice for this.  (I
> feel like I am nominating myself to try and get this sorted in a
> satisfactory fashon.)

I think this is rather secondary to accurate comments existing in the
header in some form.

Perhaps rather than doing any work up front it would be better to point
us to an existing example of something produced by what you consider a
suitable-configured doxygen so we can see if we agree?

Ian.