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

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

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?

NB: I'm in no way suggesting that anything in this series needs to
change because of this...

Ian.


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