Re: [Xen-devel] [PATCH 14/15] libxl: New API for providing OS events to libxl

[Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>]

Ian Campbell writes ("Re: [Xen-devel] [PATCH 14/15] libxl: New API for 
providing OS events to libxl"):
> One specific pitfall which trips me up is that when one has multiple
> commented function prototypes in a block, thus:
> 
>       a_function(...)
>       /* describe function a...
>        * ...
>        * at length
>        */
>       b_function(...)
>       /* describe function b...
>        * ...
>        * at length
>        */
> then figuring out which comment goes with which prototype is non-obvious

I find these very confusing.  There should be blank lines,
like this:

        a_function(...)
        /* describe function a...
         * ...
         * at length
         */

        b_function(...)
        /* describe function b...
         * ...
         * at length
         */

> and since I naturally look above the prototype for the comment I
> inevitably get the wrong one. This is compounded somewhat because we
> tend to document other types of object above rather than below and
> function prototypes are therefore something of a special case.
> (admittedly the correct solution here is more line breaks whatever the
> style of commenting used)

Yes :-).

> We seem to have a mixture of both styles in libxl headers which is
> obviously much worse than either option. If an opinion is needed to tip
> the scales then I lean slightly towards commenting above but not
> noticeably changing the style of commentary.

OK, I will move them.

Ian.

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