[RFC] Coding Style: Function header comments?

[Jelmer Vernooij]

There is currently nothing in the coding style guide about comments
above functions, explaining in one or two lines what the function does.
It would be nice to have a standard for this as well. 

So far, I've encountered the following styles:

/* Foo bar */

This is nice and short but has the disadvantage that it is
indistinguishable from any regular comment.

/************************************************************************
 * Foo bar
 **********************************************************************/

This is too much typing, and all the asterisks have no use imho :-)

/**
 * Foo bar
 */

This is the style used by doxygen and javadoc, and the one I like most.
Optionally, we could allow /** foo bar */. The advantage of using this
is that it allows using doxygen to generate API documentation, even if
we don't use all the fancy stuff for documenting individual parameters.

/**
 Foo bar
**/

Thoughts, comments?

Cheers,

Jelmer
-- 
Jelmer Vernooij <jelmer at samba.org> - http://samba.org/~jelmer/
Jabber: jelmer at jabber.fsfe.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 307 bytes
Desc: Dies ist ein digital signierter Nachrichtenteil
Url : http://lists.samba.org/archive/samba-technical/attachments/20071128/dee8f1a6/attachment.bin