Which is best: *.c or tmpl/*.sgml

[Keith Sharp <kms passback co uk>]

Hello,

I'm trying to help out by improving the API docs for various modules.  I
have finally got to grips with gtk-doc (Aarons doc is excellent), I have
one question: which is considered best using comments in *.c files or
entries in the corresponding tmpl/*.sgml file?

It appears that each module has made its own decision, some even mix the
two techniques.

Any advice would be appreciated,

Keith.