Re: [Xen-devel] Comments on LIBXL_HAVE_* defines (Was: Re: [PATCH V5 01/32] libxl: make cpupool_qualifier_to_cpupoolid a library function)

[George Dunlap <George.Dunlap@xxxxxxxxxxxxx>]

On Wed, May 21, 2014 at 9:37 AM, Ian Campbell <Ian.Campbell@xxxxxxxxxx> wrote:
> On Tue, 2014-05-20 at 18:24 +0100, Wei Liu wrote:
>> I will have the following snippet in libxl.h
>>
>> /* LIBXL_HAVE_CPUPOOL_QUALIFIER_TO_CPUPOOLID
>>  *
>>  * If this is defined, libxl has a library function called
>>  * libxl_cpupool_qualifier_to_cpupoolid, which takes in a CPU pool
>>  * qualifier in the form of number or string, then returns the ID of
>>  * that CPU pool.
>>  */
>> #define LIBXL_HAVE_CPUPOOL_QUALIFIER_TO_CPUPOOLID 1
>
> I have a more general comment/thought about these LIBXL_HAVE comments.
> We've gotten into this pattern of adding a little bit of commentary to
> these comments (I think just because the first one happened too look
> this way) which either duplicate things which seem more or less obvious
> (LIBXL_HAVE_FOO_BAR => The struct FOO has a field BAR) or, worse, add
> documentation of that field which really belongs at the site of the
> field definition not here.
>
> Does anyone else thing that the comments associated with these defines
> should be terse and/or non-existent and that the bulk of most of them
> belongs next to the definition of the field/function in question?

Hmm, that's an interesting idea.  I'd have to think about it some
more, but there does seem to be some sense to doing things that way,
and I don't immediately see an objection.

 -George

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel