Re: inline docs

["Matthias Clasen" <matthiasc poet de>]

Following up a lot on myself today...

----- Original Message -----
From: "Matthias Clasen" <matthiasc poet de>
To: "Owen Taylor" <otaylor redhat com>
Cc: <gtk-devel-list gnome org>
Sent: Tuesday, September 25, 2001 9:34 AM
Subject: Re: inline docs



> 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.
>

Meanwhile I noticed that the gtk-doc docs mention this severe limitation
in a short sentence. If changing this is in fact introducing problems, there
are two approaches I could think of for allowing docbook comments
without breaking sloppy inline docs:

1) Invent a new kind of "docbook-enabled" doc comments, eg let them start
with /*** instead of /**
or
2) try to decide intelligently whether to escape & and < or not,
    eg if they're not followed by a  ; or > on the same line, they're not
sgml markup and have to be escaped.
    Even this may be let to some false decisions regarding & in code
examples, I guess:, a la

    char c;
    char *d = &c;

 but we could probably live without entity references in inline docs as long
as we have tags, so another
 option would be
3)  treat < like in 2), but always escape &.

Matthias