Re: inline docs

["Matthias Clasen" <matthiasc poet de>]

----- Original Message -----
From: "Owen Taylor" <otaylor redhat com>
To: "Matthias Clasen" <matthiasc poet de>
Cc: <gtk-devel-list gnome org>
Sent: Monday, September 24, 2001 5:56 PM
Subject: Re: inline docs


> > 3) Should I also move things from templates to doc comments in the c
files ?
> > (I think the consensus is to
> >     move away from templates and go with inline docs.)
>
> In general, yes. But not for gobject for now.
>
> (In general, I'm not sure I would make a project of moving stuff, but
> if you are going to add docs for previously undocumented stuff into
> the C file, then you should move the remaining functions from the
> template files as well.)

Well, I played around with moving stuff from templates to inline comments,
but I discovered, that this won't work smoothly with gtk-doc-0.7.

The problem is that in the templates, you are allowed to use the infinite
possibilities of  docbook markup (<function>, <type>, <note>, <emphasis>,
<filename>...)
but if you move that markup to the doc comments, it ends up literally in the
html, since some tool in the chain prefers to escape the markup (even though
the gtk-doc docs advise me to do the escaping myself.

Unfortunately, this also means that parts of my commit to the unicode api
docs
are currently broken, since they introduced <function> markup in the
comments.

I think that if we're serious about moving to inline docs, gtk-doc must be
changed
to pass docbook markup through.

One further gtk-doc problem I noticed is:

###Can't parse args for function g_get_charset: G_CONST_RETURN char
**charset

Matthias