Re: Ideas about improving gtk-doc

[Stefan Kost <kost imn htwk-leipzig de>]

Hi Brian,

-- snip --
> 
> 4. Add two new types, FILE and ENVVAR, for documenting files and
> environment
>    variables.  They would also support the "Since" and "Deprecated" tags.
>    They would work much in the same way as ENUM or STRUCT except that they
>    would document a file or environment variable rather than a macro.
>    Files and environment variables are different than other interfaces
> in the
>    sense that these aren't declared like a macro, enumeration or function.
>    Therefore, users could include documentation comments for these two new
>    types either next to a "#define" which is used to specify the FILE or
>    ENVVAR or above a function that makes use of them.
>
That is a still a problem, as for comment in the source one canot yet tell what
for the comment is. gtk-doc relies on the fact that c symbol names are uniqe (at
least in the context of a file). Therefore it can figue out the type form the
source (wheter it is a enum, a struct or a function).
For FILE and ENVVAR stuff we need to invent some markup that I can tell gtk-doc
what this documentation is about. If we do this I would like to see this done so
that also the short,long descriptions and see also sections can be commented in
the source.

example:

/**
 * DISPLAY_ENV_VAR:
 *
 * Allows to set ...
 */
#define DISPLAY_ENV_VAR="DISPLAY";

that would be included in the docs as a plain define.
Unfortunately the 'ClassName::SignalName' is already used.

So we need either a prefix and a delimiter
 * ENVVAR=DISPLAY_ENV_VAR:
 * SHORT_DESC=CLASSNAME:
or a new keyword like
 * DISPLAY_ENV_VAR:
 * Type: Envvar

 * Classname:
 * Type: ShortDescription

Ciao
  Stefan
-- 
      \|/            Stefan Kost
     <@ @>           private            business
+-oOO-(_)-OOo------------------------------------------------------ - - -  -   -
|       __  Address  Simildenstr. 5     HTWK Leipzig, Fb IMN, Postfach 301166
|      ///           04277 Leipzig      04251 Leipzig
| __  ///            Germany            Germany
| \\\///    Phone    +49341 2253538     +49341 30766101
|  \__/     EMail    st_kost_at_gmx.net kost_at_imn.htwk-leipzig.de
|           WWW      www.sonicpulse.de  www.imn.htwk-leipzig.de/~kost/about.html
===-=-=--=---=---------------------------------- - - -  -    -

begin:vcard
fn:Stefan Kost
n:Kost;Stefan
org:HTWK Leipzig;FB. IMN
adr:;;Postfach 301166;Leipzig;;04251;Germany
email;internet:kost imn htwk-leipzig de
title:Dipl. Informatiker
tel;work:+49341 30766440
tel;home:+49341 2253538
tel;cell:+49178 3183742
x-mozilla-html:FALSE
url:http://www.imn.htwk-leipzig.de/~kost/about.html
version:2.1
end:vcard