From mboxrd@z Thu Jan  1 00:00:00 1970
From: Ian Campbell <ian.campbell@citrix.com>
Subject: Re: [PATCH v2 0/15+5+5] Begin to disentangle libxenctrl
 and provide some stable libraries
Date: Wed, 22 Jul 2015 14:05:18 +0100
Message-ID: <1437570318.12884.52.camel@citrix.com>
References: <1436975173.32371.121.camel@citrix.com>
	<55A681EC.2050508@citrix.com> <1437563556.12884.32.camel@citrix.com>
	<55AF935E.3080605@citrix.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Return-path: <xen-devel-bounces@lists.xen.org>
In-Reply-To: <55AF935E.3080605@citrix.com>
List-Unsubscribe: <http://lists.xen.org/cgi-bin/mailman/options/xen-devel>,
	<mailto:xen-devel-request@lists.xen.org?subject=unsubscribe>
List-Post: <mailto:xen-devel@lists.xen.org>
List-Help: <mailto:xen-devel-request@lists.xen.org?subject=help>
List-Subscribe: <http://lists.xen.org/cgi-bin/mailman/listinfo/xen-devel>,
	<mailto:xen-devel-request@lists.xen.org?subject=subscribe>
Sender: xen-devel-bounces@lists.xen.org
Errors-To: xen-devel-bounces@lists.xen.org
To: Andrew Cooper <andrew.cooper3@citrix.com>, xen-devel <xen-devel@lists.xen.org>
Cc: minios-devel@lists.xenproject.org, Ian Jackson <Ian.Jackson@eu.citrix.com>, Roger Pau Monne <roger.pau@citrix.com>, Wei Liu <wei.liu2@citrix.com>, Stefano Stabellini <Stefano.Stabellini@eu.citrix.com>
List-Id: xen-devel@lists.xenproject.org

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.