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

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Fri, 2011-12-09 at 17:17 +0000, Ian Jackson wrote:
> I definitely don't want to add a sentence next to "timeout_register"
> saying "this is for libxl to register a timeout" and another sentence
> saying that the "struct timeval abs" is the absolute time at which the
> timeout should fire and another sentence saying that "int fd" is the
> file descriptor and on on.

I agree that we don't want/need this style of documentation.

WRT comment placement I don't feel especially strongly (so I'm no doubt
going to regret getting involved) but the comment-after-prototype form
does look odd to me.

Putting the comment first is the norm (at least in the projects I
follow), even those that don't fall into the poor/boilerplate style
documentation traps you describe (which we do have some of :-(). I think
people are just used to reading the prototype and then looking for the
comment above it, no matter how unnatural/inefficient/illogical that
might seem.

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
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)

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.

Ian.


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