[RFC] Coding Style: Function header comments?

Jelmer Vernooij jelmer at samba.org
Wed Nov 28 18:23:11 GMT 2007

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?


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

More information about the samba-technical mailing list