Re: [Qemu-devel] [PATCH 02/11] Add operations to qlist to allow it to be used as a stack

[Luiz Capitulino <lcapitulino@redhat.com>]

On Thu, 12 Nov 2009 11:13:45 -0600
Anthony Liguori <aliguori@linux.vnet.ibm.com> wrote:

> Kevin Wolf wrote:
> > Unfortunately. There are places where such comments could be a good
> > specification on what an interface is actually meant to work like
> > (particularly in error cases). Currently you often can't tell if the
> > implementation or the caller of a function is buggy.
> >
> > Not sure if they are really useful for the simple qlist.c functions (but
> > even there the function name does not tell me what it's doing with NULL
> > parameters), but it might be helpful to have a general discussion about
> > it. I think in general qemu is poorly commented.
> >   
> 
> I agree, but I don't think the solution is forcing boiler plate 
> commenting styles.  I think what we could improve on is asking people to 
> comment bits of code during review.

 I've started adding comments like that because this is an API which
is probably going to be part of a library, as such it has to be properly
documented and very likely to be generated automatically by tools like
doxygen.

 If we do this we should be consistent and document everything which
is public, even simple cases.